@hyperframes/studio 0.8.190 → 0.8.191

package/src/components/panels/MotionBlurPanel.tsx

@@ -0,0 +1,163 @@
+import { memo, useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import type { Composition } from "@hyperframes/sdk";
+import type { MotionBlurSettings } from "@hyperframes/core/motion-blur-settings";
+import { useStudioPlaybackContext, useStudioShellContext } from "../../contexts/StudioContext";
+import { useFileManagerContext } from "../../contexts/FileManagerContext";
+import {
+  useVariablesPersist,
+  type UseVariablesPersistParams,
+} from "../../hooks/useVariablesPersist";
+import { resolveMasterCompositionPath } from "../../utils/studioUrlState";
+import { Button } from "../ui";
+import {
+  BLUR_LEVELS,
+  changedEdits,
+  findCompositionRoot,
+  levelOf,
+  patchForLevel,
+  readPreviewRootAttributes,
+  sameAttributes,
+  settingsOf,
+  withEdits,
+  type BlurLevel,
+  type RootAttributes,
+} from "./motionBlurPanelModel";
+
+export interface MotionBlurPanelProps {
+  sdkSession: Composition | null;
+  publishSdkSession?: UseVariablesPersistParams["publishSdkSession"];
+  reloadPreview: () => void;
+  recordEdit: UseVariablesPersistParams["recordEdit"];
+}
+
+const POLL_MS = 500;
+/** After a write the preview is reloading: keep what was just written instead of the old document. */
+const SETTLE_MS = 1500;
+
+/** Thrown from the edit when the file already holds the level, so nothing is written or recorded for undo. */
+class NothingToChange extends Error {}
+
+/** The preview's own root attributes, polled; `hold` pins an optimistic value until the preview catches up. */
+function useLivePreviewAttributes(
+  previewIframeRef: { current: HTMLIFrameElement | null },
+  refreshKey: number,
+) {
+  const [live, setLive] = useState<RootAttributes | null>(null);
+  const holdUntil = useRef(0);
+  useEffect(() => {
+    const read = () => {
+      const found = readPreviewRootAttributes(previewIframeRef.current);
+      if (found && Date.now() >= holdUntil.current) {
+        setLive((current) => (sameAttributes(current, found) ? current : found));
+      }
+    };
+    read();
+    const timer = setInterval(read, POLL_MS);
+    return () => clearInterval(timer);
+  }, [previewIframeRef, refreshKey]);
+  const hold = useCallback((next: (current: RootAttributes | null) => RootAttributes) => {
+    holdUntil.current = Date.now() + SETTLE_MS;
+    setLive(next);
+  }, []);
+  return [live, hold] as const;
+}
+
+export const MotionBlurPanel = memo(function MotionBlurPanel({
+  sdkSession,
+  publishSdkSession,
+  reloadPreview,
+  recordEdit,
+}: MotionBlurPanelProps) {
+  const { activeCompPath, previewIframeRef, showToast } = useStudioShellContext();
+  const { refreshKey } = useStudioPlaybackContext();
+  const { readProjectFile, writeProjectFile, compositions } = useFileManagerContext();
+  const [, rerender] = useReducer((n: number) => n + 1, 0);
+  const [live, hold] = useLivePreviewAttributes(previewIframeRef, refreshKey);
+
+  useEffect(() => sdkSession?.on("change", rerender), [sdkSession]);
+
+  const root = sdkSession ? findCompositionRoot(sdkSession.getRootElements()) : null;
+  // The preview's own root is the truth after an undo or an outside edit, which the shared session does not follow.
+  const attributes = live ?? root?.attributes ?? null;
+  const settings = useMemo(() => (attributes ? settingsOf(attributes) : null), [attributes]);
+  const isMain =
+    activeCompPath == null || activeCompPath === resolveMasterCompositionPath(compositions);
+  const persist = useVariablesPersist({
+    sdkSession,
+    activeCompPath,
+    readProjectFile,
+    writeProjectFile,
+    recordEdit,
+    reloadPreview,
+    publishSdkSession,
+  });
+
+  const apply = useCallback(
+    async (patch: Partial<MotionBlurSettings>) => {
+      if (!attributes) return;
+      // The write lands on the file's own root, so the edits are worked out there, not from the preview.
+      let applied: Array<{ name: string; value: string | null }> = [];
+      try {
+        await persist("Edit motion blur", (session) => {
+          const target = findCompositionRoot(session.getRootElements());
+          if (!target) return;
+          const next = { ...settingsOf(target.attributes), ...patch };
+          applied = changedEdits(target.attributes, next);
+          if (applied.length === 0) throw new NothingToChange();
+          for (const e of applied) {
+            session.dispatch({
+              type: "setAttribute",
+              target: target.id,
+              name: e.name,
+              value: e.value,
+            });
+          }
+        });
+        hold((current) => withEdits(current ?? attributes, applied));
+        rerender();
+      } catch (err) {
+        if (err instanceof NothingToChange) return;
+        showToast(err instanceof Error ? err.message : String(err), "error");
+      }
+    },
+    [attributes, persist, hold, showToast],
+  );
+
+  if (!settings) {
+    return (
+      <p className="p-3 text-[10px] leading-relaxed text-neutral-500">
+        Open a composition to set up motion blur.
+      </p>
+    );
+  }
+  const locked = !isMain;
+  // A sub-composition's own root is not the setting being edited, so no level is shown while locked.
+  const current = locked ? null : levelOf(settings);
+
+  return (
+    <div className="flex h-full flex-col gap-3 overflow-y-auto p-3 text-[11px] text-neutral-300">
+      <span className="text-[12px] font-medium text-neutral-100">Motion blur</span>
+      <div role="radiogroup" aria-label="Motion blur" className="flex gap-1.5">
+        {BLUR_LEVELS.map(({ level, label }) => (
+          <Button
+            key={level}
+            role="radio"
+            aria-checked={current === level}
+            size="sm"
+            variant={current === level ? "secondary" : "ghost"}
+            className="flex-1"
+            disabled={locked}
+            onClick={() => void apply(patchForLevel(level as BlurLevel))}
+          >
+            {label}
+          </Button>
+        ))}
+      </div>
+      {locked ? (
+        <p className="text-[10px] leading-relaxed text-amber-400/90">
+          Motion blur is read from the main composition. Open it to change this setting.
+        </p>
+      ) : null}
+    </div>
+  );
+});

package/src/components/panels/motionBlurPanelModel.test.ts

@@ -0,0 +1,143 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+import { openComposition } from "@hyperframes/sdk";
+import {
+  changedEdits,
+  findCompositionRoot,
+  readPreviewRootAttributes,
+  sameAttributes,
+  levelOf,
+  patchForLevel,
+  settingsOf,
+  withEdits,
+} from "./motionBlurPanelModel";
+
+const html = (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>`;
+
+async function rootOf(attrs?: string) {
+  const session = await openComposition(html(attrs), { history: false });
+  const root = findCompositionRoot(session.getRootElements());
+  if (!root) throw new Error("no root");
+  return root;
+}
+
+describe("findCompositionRoot and settingsOf", () => {
+  it("finds the composition root and reads its settings", async () => {
+    const root = await rootOf(' data-motion-blur="on" data-motion-blur-shutter="360"');
+    expect(settingsOf(root.attributes)).toMatchObject({
+      enabled: true,
+      shutterDeg: 360,
+      tier: "auto",
+    });
+  });
+
+  it("reads defaults from a root that has no blur attributes", async () => {
+    expect(settingsOf((await rootOf()).attributes)).toMatchObject({
+      enabled: false,
+      shutterDeg: 240,
+    });
+  });
+
+  it("is null for a document with nothing in it", async () => {
+    const session = await openComposition("<!DOCTYPE html><html><body></body></html>", {
+      history: false,
+    });
+    expect(findCompositionRoot(session.getRootElements())).toBeNull();
+  });
+});
+
+describe("changedEdits", () => {
+  it("lists only the attributes that would change", async () => {
+    const root = await rootOf(' data-motion-blur="on"');
+    const base = settingsOf(root.attributes);
+    expect(changedEdits(root.attributes, base)).toEqual([]);
+    expect(changedEdits(root.attributes, { ...base, shutterDeg: 360, tier: "filter" })).toEqual([
+      { name: "data-motion-blur-shutter", value: "360" },
+      { name: "data-motion-blur-tier", value: "filter" },
+    ]);
+    expect(changedEdits(root.attributes, { ...base, enabled: false })).toEqual([
+      { name: "data-motion-blur", value: null },
+    ]);
+  });
+});
+
+describe("withEdits and sameAttributes", () => {
+  it("applies sets and removals without touching the input", () => {
+    const before = { "data-motion-blur": "on", "data-motion-blur-shutter": "360" };
+    const after = withEdits(before, [
+      { name: "data-motion-blur-shutter", value: null },
+      { name: "data-motion-blur-tier", value: "filter" },
+    ]);
+    expect(after).toEqual({ "data-motion-blur": "on", "data-motion-blur-tier": "filter" });
+    expect(before).toEqual({ "data-motion-blur": "on", "data-motion-blur-shutter": "360" });
+  });
+
+  it("compares attribute sets by content", () => {
+    expect(sameAttributes({ a: "1" }, { a: "1" })).toBe(true);
+    expect(sameAttributes({ a: "1" }, { a: "2" })).toBe(false);
+    expect(sameAttributes({ a: "1" }, {})).toBe(false);
+    expect(sameAttributes(null, {})).toBe(false);
+    expect(sameAttributes(null, null)).toBe(true);
+  });
+});
+
+describe("readPreviewRootAttributes", () => {
+  it("reads only the blur attributes from the preview's composition root", () => {
+    const doc = document.implementation.createHTMLDocument("p");
+    doc.body.innerHTML =
+      '<div data-composition-id="main" data-width="1920" data-motion-blur="on" data-motion-blur-shutter="360"></div>';
+    const frame = { contentDocument: doc } as unknown as HTMLIFrameElement;
+    expect(readPreviewRootAttributes(frame)).toEqual({
+      "data-motion-blur": "on",
+      "data-motion-blur-shutter": "360",
+    });
+  });
+
+  it("is null when there is no preview, no root, or the document cannot be read", () => {
+    expect(readPreviewRootAttributes(null)).toBeNull();
+    const empty = document.implementation.createHTMLDocument("p");
+    expect(
+      readPreviewRootAttributes({ contentDocument: empty } as unknown as HTMLIFrameElement),
+    ).toBeNull();
+    const blocked = {
+      get contentDocument(): never {
+        throw new Error("cross-origin");
+      },
+    } as unknown as HTMLIFrameElement;
+    expect(readPreviewRootAttributes(blocked)).toBeNull();
+  });
+});
+
+describe("levelOf and patchForLevel", () => {
+  const on = (shutterDeg: number, enabled = true) => ({
+    enabled,
+    shutterDeg,
+    samples: null,
+    events: false,
+    tier: "auto" as const,
+  });
+
+  it("reads off, subtle and strong from the root's settings", () => {
+    expect(levelOf(on(240, false))).toBe("off");
+    expect(levelOf(on(240))).toBe("subtle");
+    expect(levelOf(on(180))).toBe("subtle");
+    expect(levelOf(on(360))).toBe("subtle");
+    expect(levelOf(on(480))).toBe("subtle");
+    expect(levelOf(on(481))).toBe("strong");
+    expect(levelOf(on(720))).toBe("strong");
+  });
+
+  it("sets Subtle to the default blur and Strong to the maximum, and leaves the rest alone for Off", () => {
+    expect(patchForLevel("subtle")).toEqual({ enabled: true, shutterDeg: 240, samples: null });
+    expect(patchForLevel("strong")).toEqual({ enabled: true, shutterDeg: 720, samples: 64 });
+    expect(patchForLevel("off")).toEqual({ enabled: false });
+  });
+
+  it("reads back as the level that was chosen", () => {
+    for (const level of ["subtle", "strong"] as const) {
+      expect(levelOf({ ...on(300), ...patchForLevel(level) })).toBe(level);
+    }
+  });
+});

package/src/components/panels/motionBlurPanelModel.ts

@@ -0,0 +1,98 @@
+/** What the Motion blur panel reads from and writes to a composition root, and how it describes the preview. */
+
+import type { ElementSnapshot } from "@hyperframes/sdk";
+import {
+  MOTION_BLUR_ATTR,
+  MOTION_BLUR_LIMITS,
+  type MotionBlurSettings,
+  motionBlurAttributeEdits,
+  readMotionBlurSettings,
+} from "@hyperframes/core/motion-blur-settings";
+
+export interface CompositionRoot {
+  id: string;
+  attributes: Readonly<Record<string, string>>;
+}
+
+/** The composition's own root: the top-level element that names a composition, else the first. */
+export function findCompositionRoot(roots: readonly ElementSnapshot[]): CompositionRoot | null {
+  const root = roots.find((el) => "data-composition-id" in el.attributes) ?? roots[0];
+  return root ? { id: root.id, attributes: root.attributes } : null;
+}
+
+export type RootAttributes = Readonly<Record<string, string>>;
+
+export const settingsOf = (attributes: RootAttributes): MotionBlurSettings =>
+  readMotionBlurSettings((name) => attributes[name] ?? null);
+
+/** Only the attributes whose value would change, so a no-op edit writes nothing. */
+export function changedEdits(
+  attributes: RootAttributes,
+  next: MotionBlurSettings,
+): Array<{ name: string; value: string | null }> {
+  return Object.entries(motionBlurAttributeEdits(next))
+    .filter(([name, value]) => (attributes[name] ?? null) !== value)
+    .map(([name, value]) => ({ name, value }));
+}
+
+/** `attributes` with `edits` applied: a value sets, null removes. */
+export function withEdits(
+  attributes: RootAttributes,
+  edits: ReadonlyArray<{ name: string; value: string | null }>,
+): RootAttributes {
+  const next: Record<string, string> = { ...attributes };
+  for (const { name, value } of edits) {
+    if (value === null) delete next[name];
+    else next[name] = value;
+  }
+  return next;
+}
+
+/** The blur attributes on the live preview's composition root: what actually runs, after an undo or an outside edit too. */
+export function readPreviewRootAttributes(iframe: HTMLIFrameElement | null): RootAttributes | null {
+  try {
+    const root = iframe?.contentDocument?.querySelector("[data-composition-id]");
+    if (!root) return null;
+    const found: Record<string, string> = {};
+    for (const name of Object.values(MOTION_BLUR_ATTR)) {
+      const value = root.getAttribute(name);
+      if (value !== null) found[name] = value;
+    }
+    return found;
+  } catch {
+    return null;
+  }
+}
+
+export const sameAttributes = (a: RootAttributes | null, b: RootAttributes | null): boolean =>
+  a === b ||
+  (a !== null && b !== null && Object.keys({ ...a, ...b }).every((name) => a[name] === b[name]));
+
+export type BlurLevel = "off" | "subtle" | "strong";
+
+export const BLUR_LEVELS: ReadonlyArray<{ level: BlurLevel; label: string }> = [
+  { level: "off", label: "Off" },
+  { level: "subtle", label: "Subtle" },
+  { level: "strong", label: "Strong" },
+];
+
+/** Subtle is the default blur; Strong opens the shutter and the samples as far as they go. */
+const LEVEL_SETTINGS = {
+  subtle: { shutterDeg: MOTION_BLUR_LIMITS.shutterDeg.default, samples: null },
+  strong: {
+    shutterDeg: MOTION_BLUR_LIMITS.shutterDeg.max,
+    samples: MOTION_BLUR_LIMITS.samples.max,
+  },
+} as const;
+/** Halfway between the two shutters: above it a root reads as Strong, so a hand-set 360 reads as Subtle. */
+const STRONG_ABOVE = (LEVEL_SETTINGS.subtle.shutterDeg + LEVEL_SETTINGS.strong.shutterDeg) / 2;
+
+export function levelOf(settings: MotionBlurSettings): BlurLevel {
+  if (!settings.enabled) return "off";
+  return settings.shutterDeg > STRONG_ABOVE ? "strong" : "subtle";
+}
+
+/** What choosing `level` changes; Off leaves the shutter, samples and every other setting where they were. */
+export function patchForLevel(level: BlurLevel): Partial<MotionBlurSettings> {
+  return level === "off" ? { enabled: false } : { enabled: true, ...LEVEL_SETTINGS[level] };
+}

package/src/hooks/usePanelLayout.test.ts

@@ -105,7 +105,7 @@ describe("usePanelLayout over the dock", () => {
     act(() => view.layout.setRightCollapsed(true));
     const hidden = vi.mocked(controller.setGroupVisible).mock.calls;
     expect(hidden.map(([id]) => id).sort()).toEqual(
-      ["design", "layers", "renders", "slideshow", "variables"].sort(),
+      ["design", "layers", "motionBlur", "renders", "slideshow", "variables"].sort(),
     );
     expect(hidden.every(([, visible]) => visible === false)).toBe(true);
   });

package/src/player/components/TimelineClip.filmstrip.test.tsx

@@ -140,7 +140,7 @@ describe("Filmstrip clips", () => {
     const picture = host.querySelector(".timeline-clip__content");
     expect(clip?.classList.contains("is-audio")).toBe(true);
     expect(picture?.classList.contains("inset-0")).toBe(true);
-    expect(css).toMatch(/--timeline-clip-audio-radius:\s*21px;/);
+    expect(css).toMatch(/--timeline-clip-audio-radius:\s*var\(--timeline-clip-radius\);/);
     expect(clip instanceof HTMLElement && clip.style.borderRadius).toBe(
       "var(--timeline-clip-audio-radius)",
     );

package/src/player/components/timelineMotionStyles.test.ts

@@ -92,7 +92,7 @@ describe("timeline motion styles", () => {
     expect(themeCss).toContain("--timeline-clip-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.85)");
     expect(themeCss).toContain("--timeline-clip-selection-highlight: rgb(255 255 255 / 0.55)");
     expect(themeCss).toContain("--timeline-clip-radius: 12px");
-    expect(themeCss).toContain("--timeline-clip-audio-radius: 21px");
+    expect(themeCss).toContain("--timeline-clip-audio-radius: var(--timeline-clip-radius)");
     expect(themeCss).toContain("--timeline-clip-highlight: rgb(255 255 255 / 0.08)");
     expect(themeCss).toContain("--timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.3)");
     expect(themeCss).toContain("--timeline-clip-chip-bg: rgba(15, 22, 18, 0.73)");

package/src/styles/theme.css

@@ -123,7 +123,7 @@
   --timeline-clip-band-height: 15px;
   --timeline-clip-band-bg: rgb(12 12 14);
   --timeline-clip-hover-duration: 60ms;
-  --timeline-clip-audio-radius: 21px;
+  --timeline-clip-audio-radius: var(--timeline-clip-radius);
   --timeline-clip-highlight: rgb(255 255 255 / 0.08);
   --timeline-clip-shadow: 0 2px 6px rgb(0 0 0 / 0.3);
   --timeline-clip-chip-bg: rgba(15, 22, 18, 0.73);

package/src/utils/studioHelpers.ts

@@ -23,7 +23,8 @@ export type RightPanelTab =
   | "renders"
   | "block-params"
   | "slideshow"
-  | "variables";
+  | "variables"
+  | "motionBlur";
 export interface AgentModalAnchorPoint {
   x: number;
   y: number;

package/src/utils/studioUrlState.ts

@@ -28,7 +28,14 @@ export interface StudioUrlState {
   selection: StudioUrlSelectionState | null;
 }
 
-const VALID_TABS: RightPanelTab[] = ["layers", "design", "renders", "slideshow", "variables"];
+const VALID_TABS: RightPanelTab[] = [
+  "layers",
+  "design",
+  "renders",
+  "slideshow",
+  "variables",
+  "motionBlur",
+];
 
 /**
  * The composition auto-open and a schema-level panel (Variables / Slideshow)