@hyperframes/studio 0.8.57 → 0.8.59

package/src/components/editor/propertyPanelFlatSliderReadout.tsx

@@ -0,0 +1,106 @@
+import { useEffect, useRef, useState } from "react";
+
+/** Click-to-type readout. Enter/blur commits; a refused value stays open and turns red. */
+export function FlatSliderReadout({
+  label,
+  displayValue,
+  tier,
+  disabled,
+  onCommitText,
+  onCommitted,
+}: {
+  label: string;
+  displayValue: string;
+  tier: "default" | "explicitCustom";
+  disabled?: boolean;
+  /** Receives the raw text; return false to refuse it and keep the field open. */
+  onCommitText?: (text: string) => boolean | void;
+  /** Fires after an accepted commit, for telemetry. */
+  onCommitted?: () => void;
+}) {
+  const [editing, setEditing] = useState(false);
+  const [text, setText] = useState("");
+  const [invalid, setInvalid] = useState(false);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const editable = Boolean(onCommitText) && !disabled;
+
+  useEffect(() => {
+    if (!editing) return;
+    inputRef.current?.focus();
+    inputRef.current?.select();
+  }, [editing]);
+
+  const begin = () => {
+    if (!editable) return;
+    setText(displayValue);
+    setInvalid(false);
+    setEditing(true);
+  };
+  // Enter and blur both commit, so a value typed and then clicked away from is
+  // not silently dropped. A refused value stays open on Enter (the author is
+  // still there to fix it) and is discarded on blur (they have moved on).
+  const commit = (keepOpenIfRefused: boolean) => {
+    const accepted = onCommitText?.(text.trim());
+    if (accepted === false && keepOpenIfRefused) {
+      setInvalid(true);
+      inputRef.current?.select();
+      return;
+    }
+    setEditing(false);
+    if (accepted !== false) onCommitted?.();
+  };
+
+  if (editing) {
+    return (
+      <input
+        ref={inputRef}
+        data-flat-slider-input="true"
+        aria-label={`${label} value`}
+        aria-invalid={invalid || undefined}
+        value={text}
+        spellCheck={false}
+        onChange={(e) => {
+          setText(e.target.value);
+          setInvalid(false);
+        }}
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            commit(true);
+          } else if (e.key === "Escape") {
+            e.preventDefault();
+            setEditing(false);
+          }
+          // Keep the timeline's own shortcuts from firing on every keystroke.
+          e.stopPropagation();
+        }}
+        onBlur={() => commit(false)}
+        className={`w-11 shrink-0 rounded-[3px] border bg-panel-surface px-1 text-right font-mono text-[10px] text-panel-text-0 outline-none ${
+          invalid ? "border-red-400" : "border-panel-accent"
+        }`}
+      />
+    );
+  }
+
+  return (
+    <span
+      data-flat-slider-value="true"
+      role={editable ? "button" : undefined}
+      tabIndex={editable ? 0 : undefined}
+      title={editable ? "Click to type a value" : undefined}
+      onClick={begin}
+      onKeyDown={(e) => {
+        if (!editable) return;
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          begin();
+        }
+      }}
+      className={`w-11 shrink-0 text-right font-mono text-[10px] ${
+        tier === "explicitCustom" ? "text-panel-text-0" : "text-panel-text-3"
+      } ${editable ? "cursor-text rounded-[3px] hover:bg-panel-hover hover:text-panel-text-0" : ""}`}
+    >
+      {displayValue}
+    </span>
+  );
+}

package/src/components/editor/useColorGradingController.ts

@@ -1,3 +1,4 @@
+import { mediaMetadataUrl } from "../../utils/studioHelpers";
 import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
 import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
 import {
@@ -288,12 +289,7 @@ export function useColorGradingController({
       return;
     }
     const controller = new AbortController();
-    fetch(
-      `/api/projects/${encodeURIComponent(projectId)}/media/metadata?path=${encodeURIComponent(
-        selectedAssetPath,
-      )}`,
-      { signal: controller.signal },
-    )
+    fetch(mediaMetadataUrl(projectId, selectedAssetPath), { signal: controller.signal })
       .then(async (response) => {
         if (!response.ok) return { ok: false as const };
         const data: MediaMetadataResponse | null = await response.json();

package/src/components/nle/AudioMeterStrip.test.tsx

@@ -0,0 +1,124 @@
+// @vitest-environment happy-dom
+// fallow-ignore-file code-duplication
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../../player/store/playerStore";
+import type { TimelineElement } from "../../player/store/timelineElement";
+import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
+import { AudioMeterStrip } from "./AudioMeterStrip";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const iframe = { contentWindow: null as unknown };
+const previewIframeRef = { current: iframe };
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({ previewIframeRef }),
+}));
+
+const makeHook = (groups: Record<string, { l: number; r: number }> = {}) => ({
+  start: vi.fn(),
+  stop: vi.fn(),
+  read: vi.fn(() => ({ master: { l: 1, r: 0.5 }, groups })),
+});
+const setHook = (hook: ReturnType<typeof makeHook> | null) => {
+  iframe.contentWindow = hook ? { __hf: { audioMeter: hook } } : null;
+};
+const clip = (extra: Partial<TimelineElement>) =>
+  ({ id: "a", tag: "audio", ...extra }) as TimelineElement;
+
+let frames: FrameRequestCallback[] = [];
+const tick = () => {
+  const run = frames;
+  frames = [];
+  act(() => run.forEach((cb) => cb(performance.now() + 16)));
+};
+
+beforeEach(() => {
+  frames = [];
+  vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => frames.push(cb));
+  vi.stubGlobal("cancelAnimationFrame", () => {});
+  usePlayerStore.setState({ elements: [] });
+  useAudioMetersVisible.setState({ visible: true });
+});
+const roots: Root[] = [];
+afterEach(() => {
+  act(() => roots.splice(0).forEach((root) => root.unmount()));
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+});
+
+function mount() {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => root.render(<AudioMeterStrip />));
+  roots.push(root);
+  return { host, root };
+}
+
+describe("AudioMeterStrip", () => {
+  it("is absent when the project has no audio", () => {
+    usePlayerStore.setState({ elements: [clip({ tag: "div" })] });
+    expect(mount().host.querySelector("[data-testid=audio-meter-strip]")).toBeNull();
+  });
+
+  it("shows one strip per group plus Master, and hides when toggled off", () => {
+    usePlayerStore.setState({
+      elements: [
+        clip({ id: "1", audioGroup: "music", audioGroupLabel: "Music" }),
+        clip({ id: "2", audioGroup: "vo" }),
+      ],
+    });
+    const { host } = mount();
+    expect(host.textContent).toContain("Music");
+    expect(host.textContent).toContain("vo");
+    expect(host.textContent).toContain("Master");
+    act(() => useAudioMetersVisible.getState().setVisible(false));
+    expect(host.querySelector("[data-testid=audio-meter-strip]")).toBeNull();
+  });
+
+  it("starts the taps once, drives the bars, follows a swapped preview window, and stops on unmount", () => {
+    usePlayerStore.setState({ elements: [clip({ audioGroup: "vo" })] });
+    const first = makeHook({ vo: { l: 1, r: 1 } });
+    setHook(first);
+    const { host, root } = mount();
+    const fill = host.querySelector<HTMLElement>("[class*=bg-green-500]")!;
+    expect(fill.style.transform).toBe("scaleY(0)");
+    tick();
+    tick();
+    expect(first.start).toHaveBeenCalledTimes(1);
+    expect(fill.style.transform).toBe("scaleY(1)");
+    const peak = host.querySelector<HTMLElement>("[data-testid=meter-peak]")!;
+    expect(peak.style.bottom).toBe("100%");
+    expect(peak.style.transform).toBe("translateY(1px)");
+
+    const second = makeHook();
+    setHook(second);
+    tick();
+    expect(first.stop).toHaveBeenCalledTimes(1);
+    expect(second.start).toHaveBeenCalledTimes(1);
+
+    act(() => root.unmount());
+    roots.length = 0;
+    expect(second.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it("follows a new preview hook even when the old stop() throws", () => {
+    usePlayerStore.setState({ elements: [clip({ audioGroup: "vo" })] });
+    const first = makeHook({ vo: { l: 1, r: 1 } });
+    first.stop.mockImplementation(() => {
+      throw new Error("dead realm");
+    });
+    setHook(first);
+    mount();
+    tick();
+    const second = makeHook();
+    setHook(second);
+    tick();
+    expect(second.start).toHaveBeenCalledTimes(1);
+    tick();
+    expect(second.read).toHaveBeenCalled();
+  });
+});

package/src/components/nle/AudioMeterStrip.tsx

@@ -0,0 +1,213 @@
+import { memo, useEffect, useMemo, useRef, type Ref, type RefObject } from "react";
+import { usePlayerStore } from "../../player";
+import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
+import { useStudioShellContext } from "../../contexts/StudioContext";
+import {
+  METER_DB_MARKS,
+  useProjectHasAudio,
+  markFraction,
+  stepPair,
+  type MeterPair as Pair,
+} from "../../utils/audioMeterMath";
+
+interface Levels {
+  master: { l: number; r: number };
+  groups: Record<string, { l: number; r: number }>;
+}
+interface AudioMeterHook {
+  start(): void;
+  stop(): void;
+  read(): Levels;
+}
+interface Strip {
+  id: string | null;
+  label: string;
+}
+type Bars = { fill: HTMLElement | null; peak: HTMLElement | null };
+type StripBars = [Bars, Bars];
+
+const MASTER: Strip = { id: null, label: "Master" };
+
+function useStrips(): Strip[] {
+  const elements = usePlayerStore((s) => s.elements);
+  return useMemo(() => {
+    const labels = new Map<string, string>();
+    for (const el of elements) {
+      if (el.audioGroup && !labels.has(el.audioGroup)) {
+        labels.set(el.audioGroup, el.audioGroupLabel ?? el.audioGroup);
+      }
+    }
+    return [...[...labels].map(([id, label]) => ({ id, label })), MASTER];
+  }, [elements]);
+}
+
+type PreviewWindow = (Window & { __hf?: { audioMeter?: AudioMeterHook } }) | null | undefined;
+
+function readHook(iframe: HTMLIFrameElement | null): AudioMeterHook | null {
+  try {
+    return (iframe?.contentWindow as PreviewWindow)?.__hf?.audioMeter ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** 0 dB is bottom 100% plus 1px down, so the tick stays inside overflow-hidden.
+ *  A calc() bottom does not stick as an inline style on Windows happy-dom. */
+function paintPeak(el: HTMLElement | null, peak: number): void {
+  if (!el) return;
+  el.style.setProperty("bottom", `${peak * 100}%`);
+  el.style.setProperty("transform", peak >= 1 ? "translateY(1px)" : "none");
+}
+
+function paint(bars: StripBars | undefined, channels: Pair): void {
+  channels.forEach((ch, i) => {
+    bars?.[i]?.fill?.style.setProperty("transform", `scaleY(${ch.level})`);
+    paintPeak(bars?.[i]?.peak ?? null, ch.peak);
+  });
+}
+
+/** One rAF loop re-reads the hook off the live preview window, so a reloaded iframe is followed. */
+function useMeterLoop(strips: Strip[], bars: RefObject<Map<string | null, StripBars>>) {
+  const { previewIframeRef } = useStudioShellContext();
+  const stripsRef = useRef(strips);
+  stripsRef.current = strips;
+  useEffect(() => {
+    let raf = 0;
+    let active: AudioMeterHook | null = null;
+    let last = performance.now();
+    const state = new Map<string | null, Pair>();
+    const tick = (now: number) => {
+      raf = requestAnimationFrame(tick);
+      const live = readHook(previewIframeRef.current);
+      if (live !== active) {
+        try {
+          active?.stop();
+        } catch {
+          // Preview iframe was torn down; the old hook is uncallable.
+        }
+        try {
+          live?.start();
+        } catch {
+          // New preview is not ready to attach yet.
+        }
+        active = live;
+      }
+      const levels = active?.read();
+      const dt = now - last;
+      last = now;
+      for (const { id } of stripsRef.current) {
+        const next = stepPair(
+          state.get(id),
+          id === null ? levels?.master : levels?.groups[id],
+          now,
+          dt,
+        );
+        if (next === state.get(id)) continue;
+        state.set(id, next);
+        paint(bars.current.get(id), next);
+      }
+    };
+    raf = requestAnimationFrame(tick);
+    return () => {
+      cancelAnimationFrame(raf);
+      try {
+        active?.stop();
+      } catch {
+        // Preview iframe already gone.
+      }
+    };
+  }, [previewIframeRef, bars]);
+}
+
+function Bar({ fillRef, peakRef }: { fillRef: Ref<HTMLDivElement>; peakRef: Ref<HTMLDivElement> }) {
+  return (
+    <div className="relative h-full w-1.5 overflow-hidden rounded-[1px] bg-neutral-900">
+      <div
+        ref={fillRef}
+        className="absolute inset-0 origin-bottom bg-green-500"
+        style={{ transform: "scaleY(0)" }}
+      />
+      <div
+        ref={peakRef}
+        data-testid="meter-peak"
+        className="absolute inset-x-0 bottom-0 h-px bg-green-400"
+      />
+    </div>
+  );
+}
+
+function MeterStrip({
+  strip,
+  register,
+}: {
+  strip: Strip;
+  register: (id: string | null, bars: StripBars | null) => void;
+}) {
+  const refs = [
+    useRef<HTMLDivElement>(null),
+    useRef<HTMLDivElement>(null),
+    useRef<HTMLDivElement>(null),
+    useRef<HTMLDivElement>(null),
+  ] as const;
+  useEffect(() => {
+    register(strip.id, [
+      { fill: refs[0].current, peak: refs[1].current },
+      { fill: refs[2].current, peak: refs[3].current },
+    ]);
+    return () => register(strip.id, null);
+    // refs are stable objects
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [strip.id, register]);
+  return (
+    <div className="flex w-16 shrink-0 flex-col items-center gap-1 px-1 pt-2 pb-1">
+      <div
+        className="flex min-h-0 flex-1 items-stretch gap-0.5"
+        aria-label={`${strip.label} level`}
+      >
+        <Bar fillRef={refs[0]} peakRef={refs[1]} />
+        <Bar fillRef={refs[2]} peakRef={refs[3]} />
+        <div className="relative ml-1 w-5 font-mono text-[9px] leading-none text-neutral-500">
+          {METER_DB_MARKS.map((db) => (
+            <span
+              key={db}
+              className="absolute right-0 translate-y-1/2"
+              style={{ bottom: `${markFraction(db) * 100}%` }}
+            >
+              {db}
+            </span>
+          ))}
+        </div>
+      </div>
+      <span className="max-w-full truncate text-[10px] text-neutral-400" title={strip.label}>
+        {strip.label}
+      </span>
+    </div>
+  );
+}
+
+export const AudioMeterStrip = memo(function AudioMeterStrip() {
+  const visible = useAudioMetersVisible((s) => s.visible);
+  const projectHasAudio = useProjectHasAudio();
+  if (!visible || !projectHasAudio) return null;
+  return <MeterStripBody />;
+});
+
+function MeterStripBody() {
+  const strips = useStrips();
+  const bars = useRef(new Map<string | null, StripBars>());
+  const register = useRef((id: string | null, b: StripBars | null) => {
+    if (b) bars.current.set(id, b);
+    else bars.current.delete(id);
+  }).current;
+  useMeterLoop(strips, bars);
+  return (
+    <div
+      data-testid="audio-meter-strip"
+      className="flex shrink-0 overflow-x-auto border-l border-neutral-800/50 bg-neutral-950"
+    >
+      {strips.map((strip) => (
+        <MeterStrip key={strip.id ?? "master"} strip={strip} register={register} />
+      ))}
+    </div>
+  );
+}

package/src/components/nle/NLEContext.tsx

@@ -1,7 +1,7 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 import { useContext, useState, useCallback, useRef, useEffect, type ReactNode } from "react";
-import { useTimelinePlayer, usePlayerStore } from "../../player";
-import type { TimelineElement } from "../../player";
+import { useTimelinePlayer } from "../../player/hooks/useTimelinePlayer";
+import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";
 import type { PreviewIframeSlot } from "../../player/hooks/useTimelineSyncCallbacks";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { useCompositionStack } from "./useCompositionStack";
@@ -18,6 +18,8 @@ export interface NLEContextValue {
   projectId: string;
   // player (from useTimelinePlayer — single instance for the whole shell)
   iframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  play: () => void;
+  pause: () => void;
   togglePlay: () => void;
   seek: (time: number, options?: { keepPlaying?: boolean }) => boolean;
   refreshPlayer: () => void;
@@ -84,6 +86,8 @@ export function NLEProvider({
   const containerRef = useRef<HTMLDivElement>(null);
   const {
     iframeRef,
+    play,
+    pause,
     togglePlay,
     seek,
     onIframeLoad: baseOnIframeLoad,
@@ -298,6 +302,8 @@ export function NLEProvider({
   const value: NLEContextValue = {
     projectId,
     iframeRef,
+    play,
+    pause,
     containerRef,
     togglePlay,
     seek,

package/src/components/nle/NLEPreview.test.ts

@@ -261,6 +261,7 @@ describe("NLEPreview", () => {
     expect(players[0].style.clipPath).toBe("");
     expect(players[1].style.clipPath).toBe("inset(100%)");
     expect(players[1].style.visibility).toBe("hidden");
+    expect(players[1].style.pointerEvents).toBe("none");
     view.cleanup();
   });
 

package/src/components/nle/TimelinePane.tsx

@@ -2,6 +2,7 @@ import { useCallback, type ReactNode } from "react";
 import { Timeline } from "../../player";
 import type { TimelineElement, TimelineTimeRange } from "../../player";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
+import { AudioMeterStrip } from "./AudioMeterStrip";
 import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
 import { trackStudioExpandedClipEdit } from "../../telemetry/events";
 import { useNLEContext } from "./NLEContext";
@@ -271,29 +272,34 @@ export function TimelinePane({
         }}
       >
         <div className="shrink-0">{timelineToolbar}</div>
-        <Timeline
-          sessionEpoch={timelineSessionEpoch}
-          onSeek={seek}
-          onDrillDown={handleDrillDown}
-          renderClipContent={renderClipContent}
-          onFileDrop={onFileDrop}
-          onDeleteElement={handleDeleteElement}
-          onAssetDrop={onAssetDrop}
-          onBlockDrop={onBlockDrop}
-          onCompositionDrop={onCompositionDrop}
-          onMoveElement={handleMoveElement}
-          onMoveElements={handleMoveElements}
-          onResizeElement={handleResizeElement}
-          onResizeElements={handleResizeElements}
-          onBlockedEditAttempt={onBlockedEditAttempt}
-          onSplitElement={handleSplitElement}
-          onSelectElement={onSelectTimelineElement}
-          onRangeSelect={onRangeSelect}
-          onCopyClip={onCopyClip}
-          onPasteClip={onPasteClip}
-          onDuplicateClip={onDuplicateClip}
-          canPasteClip={canPasteClip}
-        />
+        <div className="flex min-h-0 flex-1">
+          <div className="min-w-0 flex-1">
+            <Timeline
+              sessionEpoch={timelineSessionEpoch}
+              onSeek={seek}
+              onDrillDown={handleDrillDown}
+              renderClipContent={renderClipContent}
+              onFileDrop={onFileDrop}
+              onDeleteElement={handleDeleteElement}
+              onAssetDrop={onAssetDrop}
+              onBlockDrop={onBlockDrop}
+              onCompositionDrop={onCompositionDrop}
+              onMoveElement={handleMoveElement}
+              onMoveElements={handleMoveElements}
+              onResizeElement={handleResizeElement}
+              onResizeElements={handleResizeElements}
+              onBlockedEditAttempt={onBlockedEditAttempt}
+              onSplitElement={handleSplitElement}
+              onSelectElement={onSelectTimelineElement}
+              onRangeSelect={onRangeSelect}
+              onCopyClip={onCopyClip}
+              onPasteClip={onPasteClip}
+              onDuplicateClip={onDuplicateClip}
+              canPasteClip={canPasteClip}
+            />
+          </div>
+          <AudioMeterStrip />
+        </div>
       </div>
       {timelineFooter && <div className="shrink-0">{timelineFooter}</div>}
       {timelineOverlay && (

package/src/components/nle/useCompositionStack.ts

@@ -1,7 +1,7 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 // Composition drill-down stack management for NLEContext/EditorShell
 import { useState, useCallback, useRef, useEffect } from "react";
-import { usePlayerStore } from "../../player";
+import { usePlayerStore } from "../../player/store/playerStore";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { encodePreviewPath } from "../../player/components/thumbnailUtils";
 

package/src/contexts/TimelineEditContext.tsx

@@ -21,6 +21,10 @@ export function useTimelineEditContextOptional(): TimelineEditCallbacks {
   return useContext(TimelineEditContext) ?? {};
 }
 
+export function useTimelineEditContextValue(): TimelineEditCallbacks | null {
+  return useContext(TimelineEditContext);
+}
+
 export function TimelineEditProvider({
   value,
   children,

package/src/hooks/useCompositionDimensions.test.tsx

@@ -71,7 +71,6 @@ it("re-reads the size from the promoted iframe's document", () => {
     act(() => root.render(<Harness />));
     expect(host.textContent).toBe('{"width":1920,"height":1080}');
     act(() => {
-      ref.current = b;
       usePreviewIframeStore.getState().setIframe(b);
     });
     expect(host.textContent).toBe('{"width":1080,"height":1920}');

package/src/hooks/useSdkSession.lifecycle.test.tsx

@@ -267,6 +267,34 @@ describe("useSdkSession unavailable telemetry", () => {
     await act(async () => root.unmount());
   });
 
+  // A fetch that REJECTS produces no response at all. It used to escape this
+  // function and be caught by the effect's outer `.catch`, which reported it as
+  // `stage: "open"` — a label that means openComposition threw. Every `stage:
+  // open` event on 0.8.56/0.8.57 carries a fetch-rejection message, so the
+  // largest failure class was a network problem reported as a parser one and
+  // was unaddressable in that bucket.
+  it("reports a rejected request as a read failure, not an open failure", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new TypeError("Failed to fetch");
+      }),
+    );
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "network",
+    });
+    expect(trackMock).not.toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "open",
+      error: expect.anything(),
+    });
+    await act(async () => root.unmount());
+  });
+
   it("separates an unexpected response shape from a failed request", async () => {
     vi.stubGlobal(
       "fetch",