@hyperframes/studio 0.8.57 → 0.8.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.57",
+  "version": "0.8.59",
   "description": "",
   "repository": {
     "type": "git",
@@ -51,11 +51,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.57",
-    "@hyperframes/player": "0.8.57",
-    "@hyperframes/parsers": "0.8.57",
-    "@hyperframes/sdk": "0.8.57",
-    "@hyperframes/studio-server": "0.8.57"
+    "@hyperframes/core": "0.8.59",
+    "@hyperframes/parsers": "0.8.59",
+    "@hyperframes/player": "0.8.59",
+    "@hyperframes/studio-server": "0.8.59",
+    "@hyperframes/sdk": "0.8.59"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -71,7 +71,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.57"
+    "@hyperframes/producer": "0.8.59"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/TimelineToolbar.tsx

@@ -4,6 +4,7 @@ import {
   Magnet,
   MagnifyingGlassMinus,
   MagnifyingGlassPlus,
+  SpeakerHigh,
   Waves,
 } from "@phosphor-icons/react";
 import {
@@ -28,6 +29,8 @@ import { Scissors } from "../icons/SystemIcons";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "./editor/domEditingTypes";
 import { canSplitElement } from "../utils/timelineElementSplit";
+import { useAudioMetersVisible } from "../utils/audioMeterVisibility";
+import { useProjectHasAudio } from "../utils/audioMeterMath";
 import { canAddBeatAt, addBeatAtCompositionTime } from "../utils/beatEditActions";
 
 interface DomEditSessionSlice extends EnableKeyframesSession {
@@ -141,6 +144,9 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
   const thumbnailMode = usePlayerStore((s) => s.thumbnailMode);
   const setThumbnailMode = usePlayerStore((s) => s.setThumbnailMode);
   const thumbnailsVisible = thumbnailMode === "adaptive";
+  const audioMetersVisible = useAudioMetersVisible((s) => s.visible);
+  const setAudioMetersVisible = useAudioMetersVisible((s) => s.setVisible);
+  const projectHasAudio = useProjectHasAudio();
   // Subscribe so the add-beat button reacts to playhead movement and analysis load.
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatAnalysisReady = usePlayerStore((s) => s.beatAnalysis !== null);
@@ -249,6 +255,19 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
               <Waves size={16} weight="bold" aria-hidden="true" />
             </button>
           </Tooltip>
+          {projectHasAudio && (
+            <Tooltip label={audioMetersVisible ? "Hide audio meters" : "Show audio meters"}>
+              <button
+                type="button"
+                onClick={() => setAudioMetersVisible(!audioMetersVisible)}
+                aria-label="Toggle audio meters"
+                aria-pressed={audioMetersVisible}
+                className={audioMetersVisible ? flatActive : flatIdle}
+              >
+                <SpeakerHigh size={16} weight="bold" aria-hidden="true" />
+              </button>
+            </Tooltip>
+          )}
           {/* Always rendered (CapCut-style): with no keyframeable selection the
               button fades to a disabled state instead of unmounting, so the
               toolbar layout never shifts. */}

package/src/components/editor/MotionPathOverlay.test.tsx

@@ -52,7 +52,6 @@ it("re-evaluates set-destination availability when a reload swaps the live ifram
     expect(usePlayerStore.getState().motionPathCreateAvailable).toBe(false);
 
     act(() => {
-      ref.current = after;
       usePreviewIframeStore.getState().setIframe(after);
     });
     expect(usePlayerStore.getState().motionPathCreateAvailable).toBe(true);

package/src/components/editor/audioInspectorInput.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { MAX_AUDIO_GAIN } from "@hyperframes/core/audio-gain";
+import { RATE_RANGE } from "@hyperframes/core/audio-automation";
+import { parseGainInput, parseRateInput, parseSecondsInput } from "./audioInspectorInput";
+
+describe("parseGainInput", () => {
+  it("reads decibels as the readout shows them", () => {
+    expect(parseGainInput("0")).toBeCloseTo(1, 6);
+    expect(parseGainInput("+0.5 dB")).toBeCloseTo(10 ** (0.5 / 20), 6);
+    expect(parseGainInput("-6")).toBeCloseTo(10 ** (-6 / 20), 6);
+    expect(parseGainInput("-6dB")).toBeCloseTo(10 ** (-6 / 20), 6);
+    expect(parseGainInput("-inf")).toBe(0);
+  });
+  it("also takes a linear multiplier or a percentage", () => {
+    expect(parseGainInput("x0.8")).toBeCloseTo(0.8, 6);
+    expect(parseGainInput("0.8x")).toBeCloseTo(0.8, 6);
+    expect(parseGainInput("80%")).toBeCloseTo(0.8, 6);
+  });
+  it("clamps to the fader's ceiling and refuses nonsense", () => {
+    expect(parseGainInput("+40 dB")).toBeCloseTo(MAX_AUDIO_GAIN, 6);
+    expect(parseGainInput("loud")).toBeNull();
+    expect(parseGainInput("")).toBeNull();
+    expect(parseGainInput("x-1")).toBeNull();
+  });
+});
+
+describe("parseRateInput", () => {
+  it("reads a multiplier with or without the x, and a percentage", () => {
+    expect(parseRateInput("1.5x")).toBe(1.5);
+    expect(parseRateInput("1.5")).toBe(1.5);
+    expect(parseRateInput("x2")).toBe(2);
+    expect(parseRateInput("150%")).toBe(1.5);
+  });
+  it("clamps to the rate range and refuses zero or text", () => {
+    expect(parseRateInput("100x")).toBe(RATE_RANGE.max);
+    expect(parseRateInput("0.001")).toBe(RATE_RANGE.min);
+    expect(parseRateInput("0")).toBeNull();
+    expect(parseRateInput("fast")).toBeNull();
+  });
+});
+
+describe("parseSecondsInput", () => {
+  it("reads seconds, milliseconds and minutes:seconds", () => {
+    expect(parseSecondsInput("2.5")).toBe(2.5);
+    expect(parseSecondsInput("2.5s")).toBe(2.5);
+    expect(parseSecondsInput("500ms")).toBe(0.5);
+    expect(parseSecondsInput("1:02.5")).toBe(62.5);
+    expect(parseSecondsInput("0")).toBe(0);
+  });
+  it("refuses negatives and text", () => {
+    expect(parseSecondsInput("-1")).toBeNull();
+    expect(parseSecondsInput("soon")).toBeNull();
+    expect(parseSecondsInput("")).toBeNull();
+  });
+});

package/src/components/editor/audioInspectorInput.ts

@@ -0,0 +1,55 @@
+import { audioDbToGain, clampAudioGain } from "@hyperframes/core/audio-gain";
+import { RATE_RANGE } from "@hyperframes/core/audio-automation";
+
+const NUMBER = String.raw`[-+]?(?:\d+\.?\d*|\.\d+)`;
+
+/** Gain as the readout shows it (dB, "x0.8", "80%"). Returns linear gain, or null to refuse. */
+export function parseGainInput(text: string): number | null {
+  const t = text.trim().toLowerCase().replace(/\s+/g, "");
+  if (!t) return null;
+  if (t === "-inf" || t === "-infinity" || t === "-∞" || t === "silence" || t === "mute") return 0;
+  let m = new RegExp(`^(${NUMBER})%$`).exec(t);
+  if (m) return finiteGain(Number(m[1]) / 100);
+  m = new RegExp(`^(?:x(${NUMBER})|(${NUMBER})x)$`).exec(t);
+  if (m) return finiteGain(Number(m[1] ?? m[2]));
+  m = new RegExp(`^(${NUMBER})(?:db)?$`).exec(t);
+  if (m) return finiteGain(audioDbToGain(Number(m[1])));
+  return null;
+}
+
+function finiteGain(gain: number): number | null {
+  return Number.isFinite(gain) && gain >= 0 ? clampAudioGain(gain) : null;
+}
+
+/** Playback rate: "1.5x", "1.5", "150%". Clamped to the rate lane's range. */
+export function parseRateInput(text: string): number | null {
+  const t = text.trim().toLowerCase().replace(/\s+/g, "");
+  if (!t) return null;
+  let value: number;
+  let m = new RegExp(`^(${NUMBER})%$`).exec(t);
+  if (m) value = Number(m[1]) / 100;
+  else {
+    m = new RegExp(`^(?:x(${NUMBER})|(${NUMBER})x?)$`).exec(t);
+    if (!m) return null;
+    value = Number(m[1] ?? m[2]);
+  }
+  if (!Number.isFinite(value) || value <= 0) return null;
+  return Math.min(RATE_RANGE.max, Math.max(RATE_RANGE.min, value));
+}
+
+/** Non-negative duration or offset: "2.5", "2.5s", "500ms", "1:02.5". Returns seconds, or null to refuse. */
+export function parseSecondsInput(text: string): number | null {
+  const t = text.trim().toLowerCase().replace(/\s+/g, "");
+  if (!t) return null;
+  let m = new RegExp(`^(\\d+):(\\d{1,2}(?:\\.\\d*)?)$`).exec(t);
+  if (m) return finiteSeconds(Number(m[1]) * 60 + Number(m[2]));
+  m = new RegExp(`^(${NUMBER})ms$`).exec(t);
+  if (m) return finiteSeconds(Number(m[1]) / 1000);
+  m = new RegExp(`^(${NUMBER})(?:s|sec|secs)?$`).exec(t);
+  if (m) return finiteSeconds(Number(m[1]));
+  return null;
+}
+
+function finiteSeconds(seconds: number): number | null {
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}

package/src/components/editor/propertyPanelFlatMediaSection.test.tsx

@@ -474,3 +474,175 @@ describe("FlatMediaSection — fit/position", () => {
     act(() => root.unmount());
   });
 });
+
+function makeAudioElement(dataAttributes: Record<string, string> = {}): DomEditSelection {
+  const el = document.createElement("audio");
+  el.setAttribute("src", "assets/music.wav");
+  return makeVideoElement({
+    element: el,
+    id: "music",
+    selector: "#music",
+    label: "Music",
+    tagName: "audio",
+    dataAttributes: { duration: "10", ...dataAttributes },
+  });
+}
+
+function renderWithRate(element: DomEditSelection, onSetAttribute = vi.fn()) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(
+      <FlatMediaSection
+        projectDir={null}
+        element={element}
+        styles={{}}
+        onSetStyle={vi.fn()}
+        onSetAttribute={onSetAttribute}
+        onSetHtmlAttribute={vi.fn()}
+        rate={{
+          automated: false,
+          automatedValue: undefined,
+          onAutomate: vi.fn(),
+          onRemoveAutomation: vi.fn(),
+          onCommitAt: vi.fn(),
+          canApplyPreset: true,
+          onApplyPreset: vi.fn(),
+        }}
+      />,
+    );
+  });
+  return { host, root, onSetAttribute };
+}
+
+function labelsOf(host: HTMLElement): string[] {
+  return [...host.querySelectorAll('[data-flat-slider-track="true"]')].map(
+    (track) => track.getAttribute("aria-label") ?? "",
+  );
+}
+
+describe("FlatMediaSection — audio clips", () => {
+  it("offers speed presets on video but not on audio", () => {
+    const video = renderWithRate(makeVideoElement({ dataAttributes: { duration: "10" } }));
+    expect(video.host.textContent).toContain("Speed preset");
+    act(() => video.root.unmount());
+
+    const audio = renderWithRate(makeAudioElement());
+    expect(audio.host.textContent).not.toContain("Speed preset");
+    act(() => audio.root.unmount());
+  });
+
+  it("shows Fade in / Fade out rows for audio, and for video only when it carries audio", () => {
+    const audio = renderWithRate(makeAudioElement());
+    expect(labelsOf(audio.host)).toEqual(
+      expect.arrayContaining(["Volume", "Speed", "Media start", "Fade in", "Fade out"]),
+    );
+    act(() => audio.root.unmount());
+
+    const silentVideo = renderWithRate(makeVideoElement({ dataAttributes: { duration: "10" } }));
+    expect(labelsOf(silentVideo.host)).not.toContain("Fade in");
+    act(() => silentVideo.root.unmount());
+
+    const audibleVideo = renderWithRate(
+      makeVideoElement({ dataAttributes: { duration: "10", "has-audio": "true" } }),
+    );
+    expect(labelsOf(audibleVideo.host)).toContain("Fade out");
+    act(() => audibleVideo.root.unmount());
+  });
+
+  it("reads the authored fades and writes data-fade-in from the slider, clearing it at zero", () => {
+    const { host, root, onSetAttribute } = renderWithRate(
+      makeAudioElement({ "fade-in": "0.5", "fade-out": "2" }),
+    );
+    const readouts = [...host.querySelectorAll('[data-flat-slider-value="true"]')].map(
+      (node) => node.textContent,
+    );
+    expect(readouts).toEqual(expect.arrayContaining(["0.50s", "2.00s"]));
+
+    const fadeInTrack = host.querySelector<HTMLElement>(
+      '[data-flat-slider-track="true"][aria-label="Fade in"]',
+    );
+    if (!fadeInTrack) throw new Error("expected a Fade in slider");
+    Object.defineProperty(fadeInTrack, "getBoundingClientRect", {
+      value: () => ({ left: 0, width: 100, top: 0, height: 2, right: 100, bottom: 2 }),
+    });
+    // The other fade reserves 2 s: a quarter of the remaining 8 s is 2 s.
+    act(() => {
+      fadeInTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 25 }));
+      fadeInTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 25 }));
+    });
+    expect(onSetAttribute).toHaveBeenCalledWith("fade-in", "2");
+    act(() => {
+      fadeInTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 0 }));
+      fadeInTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 0 }));
+    });
+    // An empty write removes the attribute rather than leaving data-fade-in="0" behind.
+    expect(onSetAttribute).toHaveBeenCalledWith("fade-in", "");
+    act(() => root.unmount());
+  });
+
+  it.each([
+    ["Media start", "media-start", "45.00", {}, "9999"],
+    ["Fade in", "fade-in", "10", {}, "9999"],
+    ["Fade out", "fade-out", "10", {}, "9999"],
+    ["Fade in", "fade-in", "5", { "fade-out": "5" }, "8"],
+    ["Fade out", "fade-out", "5", { "fade-in": "5" }, "8"],
+  ] as const)("bounds typed %s to the slider limit", (label, attribute, expected, fades, typed) => {
+    const { host, root, onSetAttribute } = renderWithRate(
+      makeAudioElement({ "source-duration": "45", ...fades }),
+    );
+    const row = host.querySelector<HTMLElement>(
+      `[data-flat-slider-track="true"][aria-label="${label}"]`,
+    )?.parentElement;
+    const readout = row?.querySelector<HTMLElement>('[data-flat-slider-value="true"]');
+    if (!readout) throw new Error(`expected ${label} readout`);
+    act(() => readout.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    const input = host.querySelector<HTMLInputElement>('[data-flat-slider-input="true"]');
+    if (!input) throw new Error(`expected ${label} input`);
+    act(() => {
+      typeInto(input, typed);
+      input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    });
+    expect(onSetAttribute.mock.calls).toEqual([[attribute, expected]]);
+    act(() => root.unmount());
+  });
+
+  it("commits a typed volume in dB and a typed fade in seconds", () => {
+    const { host, root, onSetAttribute } = renderWithRate(makeAudioElement());
+    const readouts = host.querySelectorAll<HTMLElement>('[data-flat-slider-value="true"]');
+    // Volume is the first slider row.
+    act(() => readouts[0]?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    const volumeInput = host.querySelector<HTMLInputElement>('[data-flat-slider-input="true"]');
+    if (!volumeInput) throw new Error("expected the volume readout to open for typing");
+    act(() => {
+      typeInto(volumeInput, "-6 dB");
+      volumeInput.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    });
+    const [attr, value] = onSetAttribute.mock.calls.at(-1) ?? [];
+    expect(attr).toBe("volume");
+    expect(Number(value)).toBeCloseTo(10 ** (-6 / 20), 2);
+
+    const fadeOutRow = host.querySelector<HTMLElement>(
+      '[data-flat-slider-track="true"][aria-label="Fade out"]',
+    )?.parentElement;
+    const fadeOutReadout = fadeOutRow?.querySelector<HTMLElement>(
+      '[data-flat-slider-value="true"]',
+    );
+    act(() => fadeOutReadout?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    const fadeInput = host.querySelector<HTMLInputElement>('[data-flat-slider-input="true"]');
+    if (!fadeInput) throw new Error("expected the fade readout to open for typing");
+    act(() => {
+      typeInto(fadeInput, "1.25s");
+      fadeInput.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    });
+    expect(onSetAttribute).toHaveBeenLastCalledWith("fade-out", "1.25");
+    act(() => root.unmount());
+  });
+});
+
+function typeInto(input: HTMLInputElement, value: string) {
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+  setter?.call(input, value);
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+}

package/src/components/editor/propertyPanelFlatMediaSection.tsx

@@ -25,6 +25,14 @@ import {
   audioGainToFaderPosition,
   audioGainToText,
 } from "@hyperframes/core/audio-gain";
+import {
+  HF_AUDIO_FADE_IN_DATA_KEY,
+  HF_AUDIO_FADE_OUT_DATA_KEY,
+  clampFadesToDuration,
+  formatFadeSeconds,
+  readFadeSeconds,
+} from "@hyperframes/core/audio-fade";
+import { parseGainInput, parseRateInput, parseSecondsInput } from "./audioInspectorInput";
 
 // fallow-ignore-next-line complexity
 export function FlatMediaSection({
@@ -92,6 +100,10 @@ export function FlatMediaSection({
     (el as HTMLMediaElement).duration ||
     0;
   const mediaStartMax = Math.max(30, Math.ceil(sourceDuration || mediaStart + 10));
+  const fadeIn = readFadeSeconds(element.dataAttributes[HF_AUDIO_FADE_IN_DATA_KEY]);
+  const fadeOut = readFadeSeconds(element.dataAttributes[HF_AUDIO_FADE_OUT_DATA_KEY]);
+  const clipDuration = Number.parseFloat(element.dataAttributes.duration ?? "") || 0;
+  const fadeMax = clipDuration > 0 ? clipDuration : 10;
   const hasLoop = el.hasAttribute("loop");
   const hasMuted = el.hasAttribute("muted");
   const hasAudio = element.dataAttributes["has-audio"] === "true";
@@ -256,6 +268,13 @@ export function FlatMediaSection({
                     void onSetAttribute("volume", formatAudioGain(gain));
                   }
                 }}
+                onCommitText={(text) => {
+                  const gain = parseGainInput(text);
+                  if (gain === null) return false;
+                  if (volumeAutomated) onCommitVolumeAt?.(gain);
+                  else void onSetAttribute("volume", formatAudioGain(gain));
+                  return true;
+                }}
               />
             </div>
             <AutomationToggle
@@ -285,6 +304,13 @@ export function FlatMediaSection({
                     void onSetAttribute("playback-rate", formatNumericValue(speed));
                   }
                 }}
+                onCommitText={(text) => {
+                  const speed = parseRateInput(text);
+                  if (speed === null) return false;
+                  if (rate?.automated) rate.onCommitAt(speed);
+                  else void onSetAttribute("playback-rate", formatNumericValue(speed));
+                  return true;
+                }}
               />
             </div>
             <AutomationToggle
@@ -295,7 +321,10 @@ export function FlatMediaSection({
               onRemoveAutomation={rate ? () => rate.onRemoveAutomation() : undefined}
             />
           </div>
-          {rate?.canApplyPreset && (
+          {/* Speed presets are picture-driven ramps (slow-mo reveals, whip
+              speed-ups); on a bare audio clip they only warp pitch, so the
+              row is video-only. */}
+          {rate?.canApplyPreset && !isAudio && (
             <FlatSelectRow
               label="Speed preset"
               value=""
@@ -312,7 +341,21 @@ export function FlatMediaSection({
             tier={mediaStart === 0 ? "default" : "explicitCustom"}
             displayValue={formatTimingValue(mediaStart)}
             onCommit={(next) => void onSetAttribute("media-start", (next / 100).toFixed(2))}
+            onCommitText={(text) => {
+              const seconds = parseSecondsInput(text);
+              if (seconds === null) return false;
+              void onSetAttribute("media-start", Math.min(seconds, mediaStartMax).toFixed(2));
+              return true;
+            }}
           />
+          {(isAudio || hasAudio) && (
+            <MediaFadeSliders
+              fadeIn={fadeIn}
+              fadeOut={fadeOut}
+              fadeMax={fadeMax}
+              onSetAttribute={onSetAttribute}
+            />
+          )}
           <FlatToggle
             label="Loop"
             checked={hasLoop}
@@ -371,3 +414,46 @@ export function FlatMediaSection({
     </div>
   );
 }
+
+function MediaFadeSliders({
+  fadeIn,
+  fadeOut,
+  fadeMax,
+  onSetAttribute,
+}: {
+  fadeIn: number;
+  fadeOut: number;
+  fadeMax: number;
+  onSetAttribute: (attr: string, value: string) => void | Promise<void>;
+}) {
+  const fadeText = (seconds: number) => (seconds > 0 ? formatFadeSeconds(seconds) : "");
+  return (["in", "out"] as const).map((edge) => {
+    const seconds = edge === "in" ? fadeIn : fadeOut;
+    const dataKey = edge === "in" ? HF_AUDIO_FADE_IN_DATA_KEY : HF_AUDIO_FADE_OUT_DATA_KEY;
+    const edgeMax = Math.max(0, fadeMax - (edge === "in" ? fadeOut : fadeIn));
+    return (
+      <FlatSlider
+        key={edge}
+        label={`Fade ${edge}`}
+        value={Math.round(seconds * 100)}
+        min={0}
+        max={Math.round(edgeMax * 100)}
+        tier={seconds === 0 ? "default" : "explicitCustom"}
+        displayValue={formatTimingValue(seconds)}
+        onCommit={(next) => void onSetAttribute(dataKey, fadeText(next / 100))}
+        onCommitText={(text) => {
+          const parsed = parseSecondsInput(text);
+          if (parsed === null) return false;
+          const next = Math.min(parsed, edgeMax);
+          const bounded = clampFadesToDuration(
+            { fadeIn: edge === "in" ? next : fadeIn, fadeOut: edge === "out" ? next : fadeOut },
+            fadeMax,
+          );
+          void onSetAttribute(dataKey, fadeText(edge === "in" ? bounded.fadeIn : bounded.fadeOut));
+          return true;
+        }}
+        onReset={seconds > 0 ? () => void onSetAttribute(dataKey, "") : undefined}
+      />
+    );
+  });
+}

package/src/components/editor/propertyPanelFlatPrimitives.test.tsx

@@ -1285,3 +1285,95 @@ describe("FlatSelectRow — label/value options", () => {
     act(() => root.unmount());
   });
 });
+
+describe("FlatSlider — typed value", () => {
+  it("keeps the readout inert without onCommitText", () => {
+    const { host, root } = renderInto(
+      <FlatSlider
+        label="Opacity"
+        value={10}
+        min={0}
+        max={100}
+        tier="default"
+        displayValue="10%"
+        onCommit={vi.fn()}
+      />,
+    );
+    const readout = host.querySelector<HTMLElement>('[data-flat-slider-value="true"]');
+    expect(readout?.getAttribute("role")).toBeNull();
+    act(() => readout?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    expect(host.querySelector('[data-flat-slider-input="true"]')).toBeNull();
+    act(() => root.unmount());
+  });
+
+  it("turns the readout into an input on click and commits the typed text on Enter", () => {
+    const onCommitText = vi.fn().mockReturnValue(true);
+    const { host, root } = renderInto(
+      <FlatSlider
+        label="Volume"
+        value={0}
+        min={-100}
+        max={100}
+        tier="default"
+        displayValue="0 dB"
+        onCommit={vi.fn()}
+        onCommitText={onCommitText}
+      />,
+    );
+    const readout = host.querySelector<HTMLElement>('[data-flat-slider-value="true"]');
+    expect(readout?.getAttribute("role")).toBe("button");
+    act(() => readout?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    const input = host.querySelector<HTMLInputElement>('[data-flat-slider-input="true"]');
+    if (!input) throw new Error("expected the readout to become an input");
+    expect(input.value).toBe("0 dB");
+    act(() => {
+      setReactInputValue(input, "-6 dB");
+      input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    });
+    expect(onCommitText).toHaveBeenCalledWith("-6 dB");
+    expect(host.querySelector('[data-flat-slider-input="true"]')).toBeNull();
+    act(() => root.unmount());
+  });
+
+  it("stays open and marks itself invalid when the text is refused, and closes on Escape", () => {
+    const onCommitText = vi.fn().mockReturnValue(false);
+    const { host, root } = renderInto(
+      <FlatSlider
+        label="Speed"
+        value={500}
+        min={0}
+        max={1000}
+        tier="default"
+        displayValue="1x"
+        onCommit={vi.fn()}
+        onCommitText={onCommitText}
+      />,
+    );
+    act(() =>
+      host
+        .querySelector<HTMLElement>('[data-flat-slider-value="true"]')
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true })),
+    );
+    const input = host.querySelector<HTMLInputElement>('[data-flat-slider-input="true"]');
+    if (!input) throw new Error("expected an input");
+    act(() => {
+      setReactInputValue(input, "fast");
+      input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    });
+    expect(onCommitText).toHaveBeenCalledWith("fast");
+    const still = host.querySelector<HTMLInputElement>('[data-flat-slider-input="true"]');
+    expect(still).not.toBeNull();
+    expect(still?.getAttribute("aria-invalid")).toBe("true");
+    act(() => still?.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true })));
+    expect(host.querySelector('[data-flat-slider-input="true"]')).toBeNull();
+    expect(host.querySelector('[data-flat-slider-value="true"]')?.textContent).toBe("1x");
+    act(() => root.unmount());
+  });
+});
+
+/** Drives React's controlled input the way a keystroke would. */
+function setReactInputValue(input: HTMLInputElement, value: string) {
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+  setter?.call(input, value);
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+}

package/src/components/editor/propertyPanelFlatPrimitives.tsx

@@ -1,7 +1,8 @@
-import { useEffect, useRef, useState, type ReactNode } from "react";
+import { type ReactNode, useEffect, useRef, useState } from "react";
 import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
 import { RotateCcw } from "../../icons/SystemIcons";
 import { CommitField } from "./propertyPanelPrimitives";
+import { FlatSliderReadout } from "./propertyPanelFlatSliderReadout";
 import {
   VALUE_TIER_LABEL_CLASS,
   VALUE_TIER_VALUE_CLASS,
@@ -278,6 +279,7 @@ export function FlatSlider({
   centerTick,
   onReset,
   onCommit,
+  onCommitText,
 }: {
   label: string;
   value: number;
@@ -290,6 +292,8 @@ export function FlatSlider({
   centerTick?: boolean;
   onReset?: () => void;
   onCommit: (nextValue: number) => void;
+  /** Typed readout: return false to refuse the text, keep the field open, and mark it invalid. */
+  onCommitText?: (text: string) => boolean | void;
 }) {
   const track = useTrackDesignInput();
   // `draft` gives the knob instant, drag-local visual feedback. `onCommit` is
@@ -538,14 +542,14 @@ export function FlatSlider({
           style={{ left: `${clampedPct}%` }}
         />
       </div>
-      <span
-        data-flat-slider-value="true"
-        className={`w-11 shrink-0 text-right font-mono text-[10px] ${
-          tier === "explicitCustom" ? "text-panel-text-0" : "text-panel-text-3"
-        }`}
-      >
-        {displayValue}
-      </span>
+      <FlatSliderReadout
+        label={label}
+        displayValue={displayValue}
+        tier={tier}
+        disabled={disabled}
+        onCommitText={onCommitText}
+        onCommitted={() => track("input", label)}
+      />
       {(centerTick || onReset) && (
         <span data-flat-slider-reset-slot="true" className="w-3.5 shrink-0">
           {tier === "explicitCustom" && onReset && (