@hyperframes/studio 0.8.11 → 0.8.12

package/src/components/editor/useFxCarveNodes.ts

@@ -0,0 +1,153 @@
+/**
+ * What a carve analysis COMPILES TO: the filter nodes it mints and the
+ * automation lanes it writes for them.
+ *
+ * Split out of `useFxCarve.ts` to keep it under the studio's 600-line cap. This
+ * half is pure — it takes measurements and returns nodes and lanes — while the
+ * hook keeps the effects, the persistence and the auto-carve decisions.
+ */
+
+import {
+  defaultAudioFxParams,
+  mintAudioFxNodeId,
+  type HfAudioFxChain,
+  type HfAudioFxNode,
+} from "@hyperframes/core/audio-fx";
+import {
+  analyseCarveBands,
+  analyseCarveDuck,
+  analyseCarveDynamics,
+  carveBandsToChain,
+  carveProfile,
+  mixCarveSources,
+} from "@hyperframes/core/audio-carve";
+import { fxAutomationTarget, type HfAutomationLane } from "@hyperframes/core/audio-automation";
+import { clipStart } from "./propertyPanelAudioFxGroupUtils.js";
+
+/** Decode rate every carve measurement shares — see `measureCarve`. */
+const DECODE_SAMPLE_RATE = 48000;
+
+/**
+ * Turns the analysed bands (and, if the carve is asked to match levels, a
+ * ducking envelope) into chain nodes — tagged so a re-run replaces them
+ * instead of stacking, and minted against the nodes already claiming an id
+ * because a dynamic carve automates these filters and a lane addresses its
+ * node by id.
+ */
+export function mintCarveNodes(
+  chain: HfAudioFxChain,
+  carved: HfAudioFxChain,
+  duck: { t: number; v: number }[],
+): { next: HfAudioFxChain; carvedNodes: HfAudioFxNode[]; duckNode: HfAudioFxNode | null } {
+  const kept = chain.nodes.filter((n) => !n.fromCarve);
+  let claimed: HfAudioFxChain = { version: 1, nodes: kept };
+  const mint = (node: HfAudioFxNode): HfAudioFxNode => {
+    const withId = { ...node, id: mintAudioFxNodeId(claimed), fromCarve: true };
+    claimed = { version: 1, nodes: [...claimed.nodes, withId] };
+    return withId;
+  };
+  const carvedNodes: HfAudioFxNode[] = carved.nodes.map(mint);
+  // The gain stage sits after the filters, and only exists when the carve was
+  // asked to make level room. It sits at 0 and is driven by the envelope below.
+  const duckNode =
+    duck.length > 0
+      ? mint({ type: "gain", enabled: true, params: { ...defaultAudioFxParams("gain"), gain: 0 } })
+      : null;
+  return {
+    next: { version: 1, nodes: [...carvedNodes, ...(duckNode ? [duckNode] : []), ...kept] },
+    carvedNodes,
+    duckNode,
+  };
+}
+
+/**
+ * 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
+ * mix. Null on anything that leaves nothing to build a carve from — the
+ * platform lacking an offline context, or a mix that decoded to silence.
+ */
+export async function measureCarve(
+  doc: Document,
+  voices: { src: string; start: string | null }[],
+  strength: number,
+  bedStartAttr: string | null | undefined,
+  bedSrc: string | null | undefined,
+): Promise<{
+  bands: ReturnType<typeof analyseCarveBands>;
+  carved: HfAudioFxChain;
+  duck: { t: number; v: number }[];
+  voiceMix: Float32Array;
+} | null> {
+  // Decoded in an OfflineAudioContext, not a live one. Opening a second output
+  // device mid-playback makes the running track glitch while the hardware is
+  // reconfigured; an offline context touches no device.
+  const Ctor =
+    window.OfflineAudioContext ??
+    (window as unknown as { webkitOfflineAudioContext?: typeof OfflineAudioContext })
+      .webkitOfflineAudioContext;
+  if (!Ctor) return null;
+  const decode = async (relative: string): Promise<AudioBuffer> => {
+    const res = await fetch(new URL(relative, doc.baseURI).href);
+    return new Ctor(1, 1, DECODE_SAMPLE_RATE).decodeAudioData(await res.arrayBuffer());
+  };
+  const bedStart = clipStart(bedStartAttr);
+  // 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
+  // analysis is also what lets the bands and the envelopes stay a single set:
+  // 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),
+      offsetSeconds: clipStart(voice.start) - bedStart,
+    })),
+  );
+  const voiceMix = mixCarveSources(decoded, DECODE_SAMPLE_RATE);
+  if (voiceMix.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;
+  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)
+    : [];
+  return { bands, carved: carveBandsToChain(bands), duck, voiceMix };
+}
+
+/** Each filter's depth as an envelope, plus the level envelope if there is one. */
+export function carveLanes(
+  carvedNodes: HfAudioFxNode[],
+  duckNode: HfAudioFxNode | null,
+  duck: { t: number; v: number }[],
+  voiceMix: Float32Array,
+  bands: ReturnType<typeof analyseCarveBands>,
+): HfAutomationLane[] {
+  // Each filter's depth becomes an envelope of the speech's level in that
+  // band, so pauses leave the bed alone and whoever is talking sets the depth.
+  const lanes = analyseCarveDynamics(voiceMix, DECODE_SAMPLE_RATE, bands).flatMap((dyn, i) => {
+    const id = carvedNodes[i]?.id;
+    return id ? carveLaneFor(id, dyn.points) : [];
+  });
+  // The level envelope rides the gain stage, on the same clock as the bands.
+  if (duckNode?.id && duck.length > 0) lanes.push(...carveLaneFor(duckNode.id, duck));
+  return lanes;
+}
+
+/**
+ * One carve envelope as a lane on this bed's clock.
+ *
+ * No shifting: the voices were summed onto the bed's clock before the analysis
+ * ran, so what comes back is already in the bed's own time. A lane does hold
+ * its first value backwards to the start of its clip, so an envelope that
+ * begins later needs an explicit "no cut" at zero or the bed starts out ducked.
+ */
+function carveLaneFor(id: string, points: { t: number; v: number }[]): HfAutomationLane[] {
+  const timed = points.map((p) => ({ t: Number(p.t.toFixed(3)), v: p.v })).filter((p) => p.t >= 0);
+  if ((timed[0]?.t ?? 0) > 0) timed.unshift({ t: 0, v: 0 });
+  return timed.length > 1 ? [{ target: fxAutomationTarget(id, "gain"), points: timed }] : [];
+}

package/src/components/editor/useFxLevelling.ts

@@ -23,7 +23,7 @@ import {
 } from "./propertyPanelAutomation";
 import { trackLeveller } from "./audioFxTelemetry.js";
 import type { DomEditSelection } from "./domEditingTypes";
-import { usePlayerStore } from "../../player";
+import { useAuditionTransport } from "./useAuditionTransport.js";
 
 /**
  * Rate the track is decoded at. Analysis is self-consistent because it reads
@@ -125,39 +125,10 @@ export function useFxLevelling(
     }
   };
 
-  /**
-   * Where the playhead was when an audition started the transport, so leaving
-   * can put it back. Null means this audition did not start playback — the
-   * transport was already running and must be left alone.
-   */
-  const auditionReturn = useRef<number | null>(null);
-
-  /**
-   * Start playback for an audition, and stop it again on the way out.
-   *
-   * An audition writes the preset to the running graph, which is silent while
-   * the transport is paused — so a paused author hovering a preset heard
-   * nothing at all, and the whole affordance only worked mid-playback. Hovering
-   * now plays from the playhead, and leaving stops and rewinds to exactly where
-   * it started: browsing the shelf must not cost the author their place.
-   *
-   * Already playing, this does nothing in either direction. The author started
-   * that, and stopping their transport because they passed over a preset would
-   * be the panel taking a decision that was not offered to it.
-   */
-  const auditionTransport = (on: boolean): void => {
-    const store = usePlayerStore.getState();
-    if (on) {
-      if (store.isPlaying || auditionReturn.current !== null) return;
-      auditionReturn.current = store.currentTime;
-      store.requestPlayback(true);
-      return;
-    }
-    const returnTo = auditionReturn.current;
-    if (returnTo === null) return;
-    auditionReturn.current = null;
-    store.requestPlayback(false, returnTo);
-  };
+  // Hovering plays from the playhead and leaving rewinds to exactly where it
+  // started: browsing the shelf must not cost the author their place. Shared
+  // with the timeline's FX popover — see `useAuditionTransport`.
+  const auditionTransport = useAuditionTransport();
 
   const [auditioningLevel, setAuditioningLevel] = useState(false);
   /**

package/src/components/nle/NLEContext.tsx

@@ -1,12 +1,4 @@
-import {
-  createContext,
-  useContext,
-  useState,
-  useCallback,
-  useRef,
-  useEffect,
-  type ReactNode,
-} from "react";
+import { useContext, useState, useCallback, useRef, useEffect, type ReactNode } from "react";
 import { useTimelinePlayer, usePlayerStore } from "../../player";
 import type { TimelineElement } from "../../player";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
@@ -16,6 +8,7 @@ import { setCompositionSourceMap } from "../editor/domEditingDom";
 import { ensureMotionPathPluginLoaded } from "../../utils/gsapSoftReload";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
+import { createStableContext } from "../../utils/hmrStableContext";
 
 // Timeline gets a generous default height so the preview isn't oversized and the
 // tracks have room to breathe (CapCut-style). Users can still drag the divider.
@@ -55,7 +48,7 @@ export interface NLEContextValue {
   setPreviewCompositionSize: (size: { width: number; height: number } | null) => void;
 }
 
-const NLEContext = createContext<NLEContextValue | null>(null);
+const NLEContext = createStableContext<NLEContextValue | null>("NLEContext", null);
 
 export function useNLEContext(): NLEContextValue {
   const ctx = useContext(NLEContext);

package/src/components/nle/PreviewPane.tsx

@@ -156,7 +156,6 @@ export function PreviewPane({
           disabled={timelineDisabled}
           isFullscreen={isFullscreen}
           onToggleFullscreen={toggleFullscreen}
-          previewIframeRef={iframeRef}
         />
       </div>
     </div>

package/src/components/nle/useTimelineEditCallbacks.ts

@@ -47,7 +47,11 @@ export interface TimelineEditCallbackDeps {
   handleRazorSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   handleRazorSplitAll: (splitTime: number) => Promise<void> | void;
   /** C1's ungrouped-track FX pointer — same auto-grouping write B6's carve uses. */
-  handleGroupClips?: (clipIds: readonly string[], groupId: string) => Promise<void>;
+  handleGroupClips?: (
+    clipIds: readonly string[],
+    groupId: string,
+    groupLabel?: string,
+  ) => Promise<void>;
   /** C1's single-clip FX write, addressed by the clip itself. */
   setElementFxAttribute?: {
     setLive: (element: TimelineElement, attr: string, value: string | null) => void;

package/src/contexts/DesignPanelInputContext.tsx

@@ -1,4 +1,5 @@
-import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
+import { useCallback, useContext, useMemo, type ReactNode } from "react";
+import { createStableContext } from "../utils/hmrStableContext";
 import { trackDesignInput, type DesignInputUi } from "../utils/designInputTracking";
 
 // Carries which inspector UI and which section the currently-rendered design-panel
@@ -11,10 +12,10 @@ interface DesignPanelInputContextValue {
   section: string;
 }
 
-const DesignPanelInputContext = createContext<DesignPanelInputContextValue>({
-  ui: "classic",
-  section: "unknown",
-});
+const DesignPanelInputContext = createStableContext<DesignPanelInputContextValue>(
+  "DesignPanelInputContext",
+  { ui: "classic", section: "unknown" },
+);
 
 export function DesignPanelInputProvider({
   ui,

package/src/contexts/DomEditContext.tsx

@@ -1,6 +1,7 @@
 // fallow-ignore-file code-duplication
-import { createContext, useCallback, useContext, useMemo, useRef, type ReactNode } from "react";
 import type { useDomEditSession } from "../hooks/useDomEditSession";
+import { useCallback, useContext, useMemo, useRef, type ReactNode } from "react";
+import { createStableContext } from "../utils/hmrStableContext";
 
 type DomEditValue = ReturnType<typeof useDomEditSession>;
 
@@ -93,8 +94,14 @@ export interface DomEditSelectionValue extends Pick<
   | "agentPromptSelectionContext"
 > {}
 
-const DomEditActionsContext = createContext<DomEditActionsValue | null>(null);
-const DomEditSelectionContext = createContext<DomEditSelectionValue | null>(null);
+const DomEditActionsContext = createStableContext<DomEditActionsValue | null>(
+  "DomEditActionsContext",
+  null,
+);
+const DomEditSelectionContext = createStableContext<DomEditSelectionValue | null>(
+  "DomEditSelectionContext",
+  null,
+);
 
 export function useDomEditActionsContext(): DomEditActionsValue {
   const ctx = useContext(DomEditActionsContext);

package/src/contexts/FileManagerContext.tsx

@@ -1,9 +1,10 @@
-import { createContext, useContext, useMemo, type ReactNode } from "react";
 import type { useFileManager } from "../hooks/useFileManager";
+import { useContext, useMemo, type ReactNode } from "react";
+import { createStableContext } from "../utils/hmrStableContext";
 
 type FileManagerValue = ReturnType<typeof useFileManager>;
 
-const FileManagerContext = createContext<FileManagerValue | null>(null);
+const FileManagerContext = createStableContext<FileManagerValue | null>("FileManagerContext", null);
 
 export function useFileManagerContext(): FileManagerValue {
   const ctx = useContext(FileManagerContext);

package/src/contexts/PanelLayoutContext.tsx

@@ -1,9 +1,10 @@
-import { createContext, useContext, useMemo, type ReactNode } from "react";
 import type { usePanelLayout } from "../hooks/usePanelLayout";
+import { useContext, useMemo, type ReactNode } from "react";
+import { createStableContext } from "../utils/hmrStableContext";
 
 type PanelLayoutValue = ReturnType<typeof usePanelLayout>;
 
-const PanelLayoutContext = createContext<PanelLayoutValue | null>(null);
+const PanelLayoutContext = createStableContext<PanelLayoutValue | null>("PanelLayoutContext", null);
 
 export function usePanelLayoutContext(): PanelLayoutValue {
   const ctx = useContext(PanelLayoutContext);

package/src/contexts/StudioContext.tsx

@@ -1,7 +1,8 @@
-import { createContext, useContext, useMemo, type ReactNode } from "react";
 import type { TimelineElement } from "../player";
 import type { CompositionDimensions } from "../components/renders/RenderQueue";
 import type { FfmpegStatus } from "../components/renders/useFfmpegStatus";
+import { useContext, useMemo, type ReactNode } from "react";
+import { createStableContext } from "../utils/hmrStableContext";
 
 export interface StudioShellValue {
   projectId: string;
@@ -52,8 +53,11 @@ export interface StudioPlaybackValue {
 
 export type StudioContextValue = StudioShellValue & StudioPlaybackValue;
 
-const StudioShellContext = createContext<StudioShellValue | null>(null);
-const StudioPlaybackContext = createContext<StudioPlaybackValue | null>(null);
+const StudioShellContext = createStableContext<StudioShellValue | null>("StudioShellContext", null);
+const StudioPlaybackContext = createStableContext<StudioPlaybackValue | null>(
+  "StudioPlaybackContext",
+  null,
+);
 
 export function useStudioShellContext(): StudioShellValue {
   const ctx = useContext(StudioShellContext);

package/src/contexts/TimelineEditContext.tsx

@@ -1,7 +1,11 @@
-import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { useContext, useMemo, type ReactNode } from "react";
+import { createStableContext } from "../utils/hmrStableContext";
 import type { TimelineEditCallbacks } from "../player/components/timelineCallbacks";
 
-const TimelineEditContext = createContext<TimelineEditCallbacks | null>(null);
+const TimelineEditContext = createStableContext<TimelineEditCallbacks | null>(
+  "TimelineEditContext",
+  null,
+);
 
 export function useTimelineEditContext(): TimelineEditCallbacks {
   const ctx = useContext(TimelineEditContext);

package/src/contexts/VariablePromoteContext.tsx

@@ -7,7 +7,6 @@
  * and callbacks to promote or to edit the bound variable's default in place.
  */
 
-import { createContext, useContext, useEffect, useMemo, useState } from "react";
 import type { Composition, CompositionVariable } from "@hyperframes/sdk";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
@@ -22,6 +21,8 @@ import {
   uniqueId,
   type PromoteChannel,
 } from "./variablePromoteHelpers";
+import { useContext, useEffect, useMemo, useState } from "react";
+import { createStableContext } from "../utils/hmrStableContext";
 
 export type { PromoteChannel };
 
@@ -47,7 +48,10 @@ interface VariablePromoteContextValue {
   onPersistError: (error: unknown) => void;
 }
 
-const VariablePromoteContext = createContext<VariablePromoteContextValue | null>(null);
+const VariablePromoteContext = createStableContext<VariablePromoteContextValue | null>(
+  "VariablePromoteContext",
+  null,
+);
 
 function readBinding(session: Composition, hfId: string, channel: PromoteChannel): string | null {
   const snapshot = session.getElement(hfId);

package/src/contexts/ViewModeContext.tsx

@@ -1,5 +1,4 @@
 import {
-  createContext,
   useCallback,
   useContext,
   useEffect,
@@ -8,6 +7,7 @@ import {
   useState,
   type ReactNode,
 } from "react";
+import { createStableContext } from "../utils/hmrStableContext";
 
 /**
  * Top-level Studio view mode.
@@ -123,7 +123,7 @@ export function useViewModeState(): ViewModeValue {
   );
 }
 
-const ViewModeContext = createContext<ViewModeValue | null>(null);
+const ViewModeContext = createStableContext<ViewModeValue | null>("ViewModeContext", null);
 
 export function useViewMode(): ViewModeValue {
   const ctx = useContext(ViewModeContext);

package/src/hooks/domEditDeleteMembers.ts

@@ -0,0 +1,34 @@
+/**
+ * Which elements a delete acts on.
+ *
+ * Its own module so `useDomEditSession.ts` stays under the studio's 600-line
+ * cap; it reads only its arguments.
+ */
+
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { EditHistoryKind } from "../utils/editHistory";
+
+/** One entry in the studio's edit history, as `useDomEditSession`'s caller
+ *  supplies it. */
+export interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: Record<string, { before: string; after: string }>;
+}
+
+/**
+ * Which elements a delete acts on. `expandGroup` widens the primary to the
+ * whole marquee group, which is what the Delete key means.
+ *
+ * The caller chooses rather than the delete deciding for everyone: Cut copies
+ * the primary alone, so expanding for it put one element on the clipboard and
+ * removed every other member of the group with it.
+ */
+export function membersForDelete(
+  selection: DomEditSelection,
+  group: DomEditSelection[],
+  options?: { expandGroup?: boolean },
+): DomEditSelection[] {
+  return options?.expandGroup && group.length > 0 ? group : [selection];
+}