@hyperframes/studio 0.8.81 → 0.8.83

package/src/components/editor/useFxCarveNodes.ts

@@ -23,6 +23,7 @@ import {
 } from "@hyperframes/core/audio-carve";
 import { fxAutomationTarget, type HfAutomationLane } from "@hyperframes/core/audio-automation";
 import { clipStart } from "./propertyPanelAudioFxGroupUtils.js";
+import { clipAudioOnItsClock, type ClipClock } from "./clipAudioClock.js";
 
 /** Decode rate every carve measurement shares — see `measureCarve`. */
 const DECODE_SAMPLE_RATE = 48000;
@@ -60,6 +61,13 @@ export function mintCarveNodes(
   };
 }
 
+/** A clip to decode, where it starts on the timeline, and how it plays its file. */
+export interface CarveClip {
+  src: string;
+  start: string | null | undefined;
+  clock: ClipClock;
+}
+
 /**
  * Decode every voice, mix them onto the bed's own clock, and measure the
  * bands (and, if the profile calls for it, the ducking envelope) from that
@@ -68,10 +76,9 @@ export function mintCarveNodes(
  */
 export async function measureCarve(
   doc: Document,
-  voices: { src: string; start: string | null }[],
+  voices: CarveClip[],
   strength: number,
-  bedStartAttr: string | null | undefined,
-  bedSrc: string | null | undefined,
+  bed: Omit<CarveClip, "src"> & { src: string | null | undefined },
 ): Promise<{
   bands: ReturnType<typeof analyseCarveBands>;
   carved: HfAudioFxChain;
@@ -86,11 +93,15 @@ export async function measureCarve(
     (window as unknown as { webkitOfflineAudioContext?: typeof OfflineAudioContext })
       .webkitOfflineAudioContext;
   if (!Ctor) return null;
-  const decode = async (relative: string): Promise<AudioBuffer> => {
+  // Each clip as it plays: trimmed to its in-point and duration, and at its own speed.
+  const decode = async (relative: string, clock: ClipClock): Promise<Float32Array> => {
     const res = await fetch(new URL(relative, doc.baseURI).href);
-    return new Ctor(1, 1, DECODE_SAMPLE_RATE).decodeAudioData(await res.arrayBuffer());
+    const buffer = await new Ctor(1, 1, DECODE_SAMPLE_RATE).decodeAudioData(
+      await res.arrayBuffer(),
+    );
+    return clipAudioOnItsClock(buffer.getChannelData(0), DECODE_SAMPLE_RATE, clock);
   };
-  const bedStart = clipStart(bedStartAttr);
+  const bedStart = clipStart(bed.start);
   // Every voice, summed onto the bed's own clock. One question — where and
   // when is speech masking this bed — with one answer, even when the answer
   // comes from three people talking at different times. Doing this before the
@@ -98,23 +109,24 @@ export async function measureCarve(
   // the chain is fixed, so there is no per-voice filter to switch between.
   const decoded = await Promise.all(
     voices.map(async (voice) => ({
-      samples: (await decode(voice.src)).getChannelData(0),
+      samples: await decode(voice.src, voice.clock),
       offsetSeconds: clipStart(voice.start) - bedStart,
     })),
   );
-  const voiceMix = mixCarveSources(decoded, DECODE_SAMPLE_RATE);
-  if (voiceMix.length === 0) return null;
+  const mixed = mixCarveSources(decoded, DECODE_SAMPLE_RATE);
+  if (mixed.length === 0) return null;
   // Strength is what the author set; these are the numbers it means.
   const profile = carveProfile(strength);
-  // The bed as well as the voice, when the carve is asked to match levels:
-  // "how far over the voice is this bed" cannot be answered by listening to
-  // one of them.
-  const bedBuffer = profile.duckDb > 0 && bedSrc ? await decode(bedSrc).catch(() => null) : null;
+  // The bed as it plays: its length bounds the speech worth carving, and the duck
+  // compares against it ("how far over the voice is this bed" needs both).
+  const bedSamples = bed.src ? await decode(bed.src, bed.clock).catch(() => null) : null;
+  // Speech after the bed stops has no bed to carve.
+  const voiceMix = bedSamples ? mixed.subarray(0, bedSamples.length) : mixed;
   const bands = analyseCarveBands(voiceMix, DECODE_SAMPLE_RATE, profile);
   // The level half of the carve, measured against the speech it has to sit
   // under. No offset to apply: the mix is already on the bed's clock.
-  const duck = bedBuffer
-    ? analyseCarveDuck(voiceMix, bedBuffer.getChannelData(0), DECODE_SAMPLE_RATE, profile, 0)
+  const duck = bedSamples
+    ? analyseCarveDuck(voiceMix, bedSamples, DECODE_SAMPLE_RATE, profile, 0)
     : [];
   return { bands, carved: carveBandsToChain(bands), duck, voiceMix };
 }

package/src/components/editor/useFxLevelling.ts

@@ -14,7 +14,8 @@ import {
   type HfAudioFxChain,
 } from "@hyperframes/core/audio-fx";
 import { levellingResult, removeLevelling } from "@hyperframes/core/audio-leveller";
-import type { HfAutomation } from "@hyperframes/core/audio-automation";
+import type { HfAutomation, HfAutomationPoint } from "@hyperframes/core/audio-automation";
+import { timeAtSourceTime } from "@hyperframes/core/speed-ramp";
 import {
   automationAttrValue,
   HF_AUDIO_AUTOMATION_ATTR,
@@ -23,6 +24,7 @@ import {
 } from "./propertyPanelAutomation";
 import { trackLeveller } from "./audioFxTelemetry.js";
 import type { DomEditSelection } from "./domEditingTypes";
+import { clipSourceWindow, readClipClock } from "./clipAudioClock.js";
 import { useAuditionTransport } from "./useAuditionTransport.js";
 
 /**
@@ -31,11 +33,6 @@ import { useAuditionTransport } from "./useAuditionTransport.js";
  */
 const DECODE_SAMPLE_RATE = 48000;
 
-/** A parsed attribute, kept only when it is a usable positive number. */
-function positiveFinite(n: number): number | null {
-  return Number.isFinite(n) && n > 0 ? n : null;
-}
-
 export function useFxLevelling(
   element: DomEditSelection,
   chain: HfAudioFxChain,
@@ -75,27 +72,19 @@ export function useFxLevelling(
     return next;
   };
 
-  /**
-   * The part of the decoded file this clip actually plays.
-   *
-   * A lane's `t` is seconds from the start of the CLIP, but the decode is the
-   * whole file from its first sample — so measuring a trimmed clip produced an
-   * envelope offset by the trim, and every correction landed early by exactly
-   * `media-start`. Slicing here is what puts the two clocks back on the same
-   * zero.
-   */
-  const clipWindow = (audio: { samples: Float32Array; sampleRate: number }) => {
-    const mediaStart = positiveFinite(Number(element.dataAttributes?.["media-start"] ?? 0));
-    const duration = positiveFinite(Number(element.dataAttributes?.["duration"] ?? Number.NaN));
-    const from = mediaStart
-      ? Math.min(audio.samples.length, Math.floor(mediaStart * audio.sampleRate))
-      : 0;
-    const to = duration
-      ? Math.min(audio.samples.length, from + Math.ceil(duration * audio.sampleRate))
-      : audio.samples.length;
-    return from === 0 && to === audio.samples.length
-      ? audio.samples
-      : audio.samples.subarray(from, to);
+  /** The levelled chain and its lane, with the lane moved from the source's clock onto the clip's. */
+  const measureLevelling = (audio: { samples: Float32Array; sampleRate: number }) => {
+    // Measured on the part of the file the clip plays, so lane times map from that window's zero.
+    const clock = readClipClock((name) => element.dataAttributes?.[name.slice(5)]);
+    const played = clipSourceWindow(audio.samples, audio.sampleRate, clock);
+    const result = levellingResult(chain, played, audio.sampleRate);
+    if (!result) return null;
+    const lane = result.automation.lanes[0];
+    const toClipTime = (point: HfAutomationPoint) => ({
+      ...point,
+      t: Number(timeAtSourceTime(clock.rate, point.t).toFixed(3)),
+    });
+    return { chain: result.chain, lane: lane && { ...lane, points: lane.points.map(toClipTime) } };
   };
 
   const runLeveller = async (): Promise<void> => {
@@ -103,14 +92,14 @@ export function useFxLevelling(
     try {
       const audio = await decodeTrack();
       if (!audio) return;
-      const result = levellingResult(chain, clipWindow(audio), audio.sampleRate);
+      const result = measureLevelling(audio);
       if (!result) return;
       trackLeveller("run");
       await onSetAttributeQuiet(HF_AUDIO_FX_ATTR, serializeAudioFxChain(result.chain));
       // Merged by target, never written wholesale: the script describes its own
       // lane only, and replacing the attribute would take the carve's lanes and
       // the volume lane with it.
-      const lane = result.automation.lanes[0];
+      const lane = result.lane;
       if (lane) {
         void onSetAttributeQuiet(
           HF_AUDIO_AUTOMATION_ATTR,
@@ -160,10 +149,10 @@ export function useFxLevelling(
       const audio = await decodeTrack();
       // Gone, or superseded by a later hover. Either way this result is stale.
       if (!audio || run !== auditionRun.current) return;
-      const result = levellingResult(chain, clipWindow(audio), audio.sampleRate);
+      const result = measureLevelling(audio);
       if (!result || run !== auditionRun.current) return;
       void onSetAttributeLive(HF_AUDIO_FX_ATTR, serializeAudioFxChain(result.chain));
-      const lane = result.automation.lanes[0];
+      const lane = result.lane;
       if (lane) {
         void onSetAttributeLive(
           HF_AUDIO_AUTOMATION_ATTR,

package/src/components/editor/useInlineTextEditing.tsx

@@ -1,4 +1,4 @@
-import { useRef, type ReactNode, type RefObject } from "react";
+import { useEffect, useRef, type ReactNode, type RefObject } from "react";
 import { InlineTextToolbar } from "./InlineTextToolbar";
 import { useDomEditActionsContextOptional } from "../../contexts/DomEditContext";
 import { useInlineTextEdit } from "../../hooks/useInlineTextEdit";
@@ -12,6 +12,8 @@ import {
 } from "./domEditInlineText";
 import type { DomEditSelection } from "./domEditingTypes";
 
+type KeyChord = Pick<KeyboardEvent, "key" | "shiftKey" | "ctrlKey" | "metaKey" | "altKey">;
+
 /**
  * The canvas' side of editing text where it sits.
  *
@@ -23,18 +25,15 @@ import type { DomEditSelection } from "./domEditingTypes";
  * props, the same way the agent surfaces in that overlay read it, and it is
  * absent in standalone player mounts, which have no project to edit.
  */
-export function useInlineTextEditing(selectionRef: RefObject<DomEditSelection | null>): {
+export function useInlineTextEditing(
+  selectionRef: RefObject<DomEditSelection | null>,
+  { enterFromWindow = false }: { enterFromWindow?: boolean } = {},
+): {
   editing: boolean;
   /** Open an edit when this press pairs with the last one. */
   startFromPress: (event: { clientX: number; clientY: number }) => boolean;
   /** Handle a key on the canvas. Returns true when it opened an edit. */
-  handleKeyDown: (event: {
-    key: string;
-    shiftKey: boolean;
-    ctrlKey: boolean;
-    metaKey: boolean;
-    altKey: boolean;
-  }) => boolean;
+  handleKeyDown: (event: KeyChord) => boolean;
   /**
    * The styling controls for the current selection, for the caller to render.
    *
@@ -84,6 +83,32 @@ export function useInlineTextEditing(selectionRef: RefObject<DomEditSelection |
     return { x: (event.clientX - box.left) / scale, y: (event.clientY - box.top) / scale };
   };
 
+  // Enter opens the selected element's text, the way every design tool does,
+  // and is the dependable way in: a double press has to survive the canvas'
+  // gesture machinery, while this is one key on a selection that has settled.
+  const handleKeyDown = (event: KeyChord) => {
+    if (event.key !== "Enter" || event.shiftKey || event.ctrlKey || event.metaKey || event.altKey)
+      return false;
+    const target = selectionRef.current;
+    if (inlineText.session || !target || !canEditTextInline(target)) return false;
+    return inlineText.start(target.element);
+  };
+  const handleKeyDownRef = useRef(handleKeyDown);
+  handleKeyDownRef.current = handleKeyDown;
+  // A host-mode canvas takes no presses of its own, so it is rarely focused;
+  // with nothing focused, Enter comes via the window.
+  useEffect(() => {
+    if (!enterFromWindow) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      const { body, documentElement } = window.document;
+      if (event.defaultPrevented || (event.target !== body && event.target !== documentElement))
+        return;
+      if (handleKeyDownRef.current(event)) event.preventDefault();
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [enterFromWindow]);
+
   return {
     editing: inlineText.session !== null,
     toolbar: (
@@ -92,16 +117,7 @@ export function useInlineTextEditing(selectionRef: RefObject<DomEditSelection |
         iframe={actions?.previewIframeRef?.current ?? null}
       />
     ),
-    // Enter opens the selected element's text, the way every design tool does,
-    // and is the dependable way in: a double press has to survive the canvas'
-    // gesture machinery, while this is one key on a selection that has settled.
-    handleKeyDown: (event) => {
-      if (event.key !== "Enter" || event.shiftKey || event.ctrlKey || event.metaKey || event.altKey)
-        return false;
-      const target = selectionRef.current;
-      if (inlineText.session || !target || !canEditTextInline(target)) return false;
-      return inlineText.start(target.element);
-    },
+    handleKeyDown,
     startFromPress: (event) => {
       if (inlineText.session) return false;
       const element = elementUnderPress(event);

package/src/components/feedback/projectProvenance.ts

@@ -16,6 +16,7 @@ import { buildProjectApiPath } from "../../utils/projectRouting";
 // ---------------------------------------------------------------------------
 
 import type { FeedbackContext } from "./feedbackTrigger";
+import { isMediaFile } from "../../utils/mediaTypes";
 
 /** Written by `hyperframes init`; absent in a hand-made or copied project. */
 const CONFIG_FILE = "hyperframes.json";
@@ -23,12 +24,10 @@ const CONFIG_FILE = "hyperframes.json";
 /** Matches the CLI's own slug gate, so a hand-edited value cannot leak text. */
 const SKILL_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
-const MEDIA_EXTENSIONS = /\.(mp4|mov|webm|m4v|mp3|wav|m4a|aac|ogg|png|jpe?g|gif|webp|svg|avif)$/i;
-
 let snapshot: FeedbackContext = {};
 
 function countMedia(files: string[]): number {
-  return files.filter((f) => MEDIA_EXTENSIONS.test(f)).length;
+  return files.filter(isMediaFile).length;
 }
 
 /**

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

@@ -11,6 +11,7 @@ import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
 import { SILENT_CHANNEL } from "../../utils/audioMeterMath";
 import {
   AudioMeterStrip,
+  type AudioMeterStripProps,
   evictGoneMeterState,
   followMeterHook,
   stepAndPaintStrips,
@@ -20,8 +21,9 @@ import {
 
 const iframe = { contentWindow: null as unknown };
 const previewIframeRef = { current: iframe };
+let shell: { previewIframeRef: typeof previewIframeRef } | null = { previewIframeRef };
 vi.mock("../../contexts/StudioContext", () => ({
-  useStudioShellContext: () => ({ previewIframeRef }),
+  useStudioShellContextOptional: () => shell,
 }));
 
 const onSetAudioGroupAttributeLive = vi.fn();
@@ -88,6 +90,7 @@ const tick = () => {
 };
 
 beforeEach(() => {
+  shell = { previewIframeRef };
   frames = [];
   vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => frames.push(cb));
   vi.stubGlobal("cancelAnimationFrame", () => {});
@@ -103,11 +106,11 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
-function mount() {
+function mount(props: AudioMeterStripProps = {}) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
-  act(() => root.render(<AudioMeterStrip />));
+  act(() => root.render(<AudioMeterStrip {...props} />));
   roots.push(root);
   return { host, root };
 }
@@ -177,6 +180,26 @@ describe("AudioMeterStrip", () => {
     expect(second.read).toHaveBeenCalled();
   });
 
+  it("reads a host's preview iframe over the shell's", () => {
+    usePlayerStore.setState({ elements: [clip({ audioGroup: "vo" })] });
+    const shellHook = makeHook();
+    setHook(shellHook);
+    const hostHook = makeHook();
+    const hostIframe = { contentWindow: { __hf: { audioMeter: hostHook } } };
+    mount({ previewIframeRef: { current: hostIframe as unknown as HTMLIFrameElement } });
+    tick();
+    expect(hostHook.start).toHaveBeenCalledTimes(1);
+    expect(shellHook.start).not.toHaveBeenCalled();
+  });
+
+  it("mounts with no shell and no preview iframe", () => {
+    shell = null;
+    usePlayerStore.setState({ elements: [clip({ audioGroup: "vo" })] });
+    const { host } = mount();
+    tick();
+    expect(host.querySelector("[data-testid=audio-meter-strip]")).not.toBeNull();
+  });
+
   it("keeps authored gain 2 above unity and writes exactly 1 at the midpoint", () => {
     usePlayerStore.setState({ elements: [clip({ audioGroup: "vo", audioGroupVolume: 2 })] });
     const { host } = mount();

package/src/components/nle/AudioMeterStrip.tsx

@@ -20,7 +20,7 @@ import type { StereoLevel } from "@hyperframes/core/runtime/levelTap";
 import { usePlayerStore } from "../../player";
 import { clampNumber } from "../../utils/studioHelpers";
 import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
-import { useStudioShellContext } from "../../contexts/StudioContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import {
   METER_DB_MARKS,
@@ -107,7 +107,7 @@ function useVolumeHandlers(): {
 
 type PreviewWindow = (Window & { __hf?: { audioMeter?: AudioMeterHook } }) | null | undefined;
 
-function readHook(iframe: HTMLIFrameElement | null): AudioMeterHook | null {
+function readHook(iframe: HTMLIFrameElement | null | undefined): AudioMeterHook | null {
   try {
     return (iframe?.contentWindow as PreviewWindow)?.__hf?.audioMeter ?? null;
   } catch {
@@ -123,9 +123,8 @@ function paintPeak(el: HTMLElement | null, peak: number): void {
   el.style.setProperty("transform", peak >= 1 ? "translateY(1px)" : "none");
 }
 
-/** The fill is a fixed green/amber/red backdrop; painting only moves the dark
- *  mask that covers the unlit top portion, so a loud peak lights the real red
- *  band instead of tinting a flat colour brighter. */
+/** The fill is a fixed green/amber/red backdrop; painting only moves the dark mask that covers the unlit top
+ *  portion, so a loud peak lights the real red band instead of tinting a flat colour brighter. */
 function paint(bars: StripBars | undefined, channels: Pair): void {
   channels.forEach((ch, i) => {
     bars?.[i]?.mask?.style.setProperty("height", `${(1 - ch.level) * 100}%`);
@@ -179,8 +178,13 @@ export function stepAndPaintStrips(
 }
 
 /** 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();
+function useMeterLoop(
+  strips: Strip[],
+  bars: RefObject<Map<string | null, StripBars>>,
+  iframeRef: RefObject<HTMLIFrameElement | null> | undefined,
+) {
+  const shell = useStudioShellContextOptional();
+  const previewIframeRef = iframeRef ?? shell?.previewIframeRef;
   const stripsRef = useRef(strips);
   stripsRef.current = strips;
   useEffect(() => {
@@ -190,7 +194,7 @@ function useMeterLoop(strips: Strip[], bars: RefObject<Map<string | null, StripB
     const state = new Map<string | null, Pair>();
     const tick = (now: number) => {
       raf = requestAnimationFrame(tick);
-      active = followMeterHook(active, readHook(previewIframeRef.current));
+      active = followMeterHook(active, readHook(previewIframeRef?.current));
       const levels = active?.read();
       const dt = now - last;
       last = now;
@@ -395,14 +399,21 @@ function MeterStrip({
   );
 }
 
-export const AudioMeterStrip = memo(function AudioMeterStrip() {
+export interface AudioMeterStripProps {
+  /** Pass a stable ref (useRef): a new object each render restarts the meter loop. */
+  previewIframeRef?: RefObject<HTMLIFrameElement | null>;
+}
+
+export const AudioMeterStrip = memo(function AudioMeterStrip({
+  previewIframeRef,
+}: AudioMeterStripProps) {
   const visible = useAudioMetersVisible((s) => s.visible);
   const projectHasAudio = useProjectHasAudio();
   if (!visible || !projectHasAudio) return null;
-  return <MeterStripBody />;
+  return <MeterStripBody previewIframeRef={previewIframeRef} />;
 });
 
-function MeterStripBody() {
+function MeterStripBody({ previewIframeRef }: AudioMeterStripProps) {
   const strips = useStrips();
   const bars = useRef(new Map<string | null, StripBars>());
   const register = useRef((id: string | null, b: StripBars | null) => {
@@ -410,7 +421,7 @@ function MeterStripBody() {
     else bars.current.delete(id);
   }).current;
   const { onLive, onCommit } = useVolumeHandlers();
-  useMeterLoop(strips, bars);
+  useMeterLoop(strips, bars, previewIframeRef);
   return (
     <div
       data-testid="audio-meter-strip"