@hyperframes/studio 0.8.82 → 0.8.84

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

@@ -0,0 +1,163 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getPreviewState, iframeRef } from "../nle/PreviewOverlaysTestMocks";
+import { PreviewOverlays } from "../nle/PreviewOverlays";
+import { ConnectedDomEditOverlay } from "./ConnectedDomEditOverlay";
+
+// Overlay prop -> session handler, as PreviewOverlays wired DomEditOverlay itself.
+const WIRING = {
+  onCanvasMouseDown: "handlePreviewCanvasMouseDown",
+  onCanvasPointerMove: "handlePreviewCanvasPointerMove",
+  onCanvasPointerLeave: "handlePreviewCanvasPointerLeave",
+  onSelectionChange: "applyDomSelection",
+  onBlockedMove: "handleBlockedDomMove",
+  onManualDragStart: "handleDomManualDragStart",
+  onPathOffsetCommit: "handleDomPathOffsetCommit",
+  onGroupPathOffsetCommit: "handleDomGroupPathOffsetCommit",
+  onBoxSizeCommit: "handleDomBoxSizeCommit",
+  onRotationCommit: "handleDomRotationCommit",
+  onStyleCommit: "handleDomStyleCommit",
+  onDeleteSelection: "handleDomEditElementDelete",
+  onMarqueeSelect: "applyMarqueeSelection",
+} as const;
+
+const ctx = vi.hoisted(() => ({
+  overlayProps: null as Record<string, unknown> | null,
+  actions: {} as Record<string, unknown>,
+  selection: {
+    domEditHoverSelection: { label: "hover" },
+    domEditSelection: { label: "selected" },
+    domEditGroupSelections: [{ label: "member" }],
+  },
+}));
+
+vi.mock("../../contexts/DomEditContext", () => ({
+  useDomEditSelectionContext: () => ctx.selection,
+  useDomEditActionsContext: () => ctx.actions,
+}));
+vi.mock("./DomEditOverlay", () => ({
+  DomEditOverlay: (props: Record<string, unknown>) => {
+    ctx.overlayProps = props;
+    return null;
+  },
+}));
+vi.mock("./TopologyLens", () => ({ TopologyLens: () => null }));
+vi.mock("./MotionPathOverlay", () => ({ MotionPathOverlay: () => null }));
+vi.mock("./SnapToolbar", () => ({ SnapToolbar: () => null }));
+vi.mock("./GridOverlay", () => ({ GridOverlay: () => null }));
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root;
+
+function mount(node: React.ReactNode): Record<string, unknown> {
+  ctx.actions = {
+    previewIframeRef: iframeRef,
+    handleDomZIndexReorderCommit: vi.fn(() => Promise.resolve(undefined)),
+  };
+  for (const name of Object.values(WIRING)) ctx.actions[name] = vi.fn();
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => root.render(node));
+  return ctx.overlayProps!;
+}
+
+afterEach(() => {
+  act(() => root.unmount());
+  ctx.overlayProps = null;
+  getPreviewState().isPlaying = false;
+  document.body.replaceChildren();
+});
+
+describe("ConnectedDomEditOverlay", () => {
+  it("is what PreviewOverlays renders, with every handler from the session", () => {
+    const props = mount(
+      <PreviewOverlays
+        shouldShowMotionPath={false}
+        shouldShowSelectedDomBounds={true}
+        recordingState={"idle" as never}
+        onToggleRecording={vi.fn()}
+      />,
+    );
+    // The overlay never read these, so the connected wrapper does not pass them.
+    expect(props).not.toHaveProperty("recordingState");
+    expect(props).not.toHaveProperty("onToggleRecording");
+    for (const [prop, handler] of Object.entries(WIRING)) {
+      expect(props[prop], prop).toBe(ctx.actions[handler]);
+    }
+    expect(props).toMatchObject({
+      iframeRef,
+      activeCompositionPath: "index.html",
+      hoverSelection: ctx.selection.domEditHoverSelection,
+      selection: ctx.selection.domEditSelection,
+      groupSelections: ctx.selection.domEditGroupSelections,
+      allowCanvasMovement: true,
+      canvasInput: undefined,
+      onTextEditingChange: undefined,
+    });
+  });
+
+  it("shows no hover box while playback runs", () => {
+    getPreviewState().isPlaying = true;
+    const props = mount(
+      <PreviewOverlays shouldShowMotionPath={false} shouldShowSelectedDomBounds={true} />,
+    );
+    expect(props.hoverSelection).toBeNull();
+    expect(props.selection).toBe(ctx.selection.domEditSelection);
+  });
+
+  it("hides the selection and stops movement while a gesture records", () => {
+    const props = mount(
+      <PreviewOverlays
+        shouldShowMotionPath={false}
+        shouldShowSelectedDomBounds={false}
+        isGestureRecording={true}
+      />,
+    );
+    expect(props).toMatchObject({
+      selection: null,
+      groupSelections: [],
+      allowCanvasMovement: false,
+    });
+  });
+
+  it("persists a z-order change through the session's reorder commit", () => {
+    const props = mount(
+      <PreviewOverlays shouldShowMotionPath={false} shouldShowSelectedDomBounds={true} />,
+    );
+    const element = document.createElement("div");
+    element.id = "card";
+    const sel = { element, id: "card", selector: "#card", sourceFile: "index.html" };
+    const apply = props.onApplyZIndex as (...args: unknown[]) => void;
+    act(() => apply(sel, [{ element, zIndex: 4 }], "bring-forward", null));
+    expect(ctx.actions.handleDomZIndexReorderCommit).toHaveBeenCalledWith(
+      [expect.objectContaining({ element, zIndex: 4, id: "card", sourceFile: "index.html" })],
+      expect.stringContaining("z-reorder:bring-forward"),
+      "bring-forward",
+    );
+  });
+
+  it("passes a host's canvas input, text-editing listener and hover gate to the overlay", () => {
+    const onTextEditingChange = vi.fn();
+    const props = mount(
+      <ConnectedDomEditOverlay
+        activeCompositionPath={null}
+        showHoverSelection={false}
+        shouldShowSelectedDomBounds={true}
+        canvasInput="host"
+        onTextEditingChange={onTextEditingChange}
+      />,
+    );
+    expect(props).toMatchObject({
+      canvasInput: "host",
+      onTextEditingChange,
+      hoverSelection: null,
+      selection: ctx.selection.domEditSelection,
+      iframeRef,
+    });
+  });
+});

package/src/components/editor/ConnectedDomEditOverlay.tsx

@@ -0,0 +1,206 @@
+import type { ComponentProps } from "react";
+import { DomEditOverlay } from "./DomEditOverlay";
+import {
+  useDomEditActionsContext,
+  useDomEditSelectionContext,
+} from "../../contexts/DomEditContext";
+import { readHfId, type DomEditSelection } from "./domEditing";
+import { buildStableSelector } from "./domEditingDom";
+import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
+import { zReorderCoalesceKey } from "../../hooks/useElementLifecycleOps";
+import { useCanvasZOrderTimelineMirror } from "../nle/useCanvasZOrderTimelineMirror";
+import { runZLaneGesture } from "../nle/zLaneGesture";
+
+type HostInputProps = Pick<
+  ComponentProps<typeof DomEditOverlay>,
+  "canvasInput" | "onSelectionBoxClick"
+>;
+
+export interface ConnectedDomEditOverlayProps extends HostInputProps {
+  activeCompositionPath: string | null;
+  showHoverSelection: boolean;
+  shouldShowSelectedDomBounds: boolean;
+  isGestureRecording?: boolean;
+  /** True when an in-place text edit opens its caret, false when it ends or unmounts. */
+  onTextEditingChange?: (editing: boolean) => void;
+}
+
+type ZIndexReorderEntry = {
+  element: HTMLElement;
+  zIndex: number;
+  id?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile: string;
+  /** Timeline store key — lets the commit update the store zIndex synchronously. */
+  key?: string;
+};
+
+/** Can this element be robustly re-targeted for a persisted z change? */
+function canTargetZIndexElement(
+  element: HTMLElement,
+  id: string | undefined,
+  selector: string | undefined,
+): boolean {
+  return Boolean(id || selector || readHfId(element));
+}
+
+/** The selected element carries its full selection identity. */
+function selectedZIndexEntry(sel: DomEditSelection, zIndex: number): ZIndexReorderEntry {
+  return {
+    element: sel.element,
+    zIndex,
+    id: sel.id ?? undefined,
+    selector: sel.selector,
+    selectorIndex: sel.selectorIndex,
+    sourceFile: sel.sourceFile,
+    key: deriveTimelineStoreKey({
+      domId: sel.id ?? undefined,
+      selector: sel.selector,
+      selectorIndex: sel.selectorIndex,
+      sourceFile: sel.sourceFile,
+    }),
+  };
+}
+
+/** A raw iframe sibling in the selection's file; null with no id or selector (z stays live). */
+function siblingZIndexEntry(
+  element: HTMLElement,
+  zIndex: number,
+  sourceFile: string,
+): ZIndexReorderEntry | null {
+  const id = element.id || undefined;
+  const selector = buildStableSelector(element);
+  if (!canTargetZIndexElement(element, id, selector)) return null;
+  return {
+    element,
+    zIndex,
+    id,
+    selector,
+    selectorIndex: undefined,
+    sourceFile,
+    key: deriveTimelineStoreKey({ domId: id, selector, sourceFile }),
+  };
+}
+
+/** Short human-readable label for a dropped sibling, for the console warning below. */
+function describeZIndexElement(element: HTMLElement): string {
+  if (element.id) return `#${element.id}`;
+  const firstClass = element.classList.item(0);
+  return firstClass
+    ? `${element.tagName.toLowerCase()}.${firstClass}`
+    : element.tagName.toLowerCase();
+}
+
+// Resolve z-index patches into commit entries; a sibling with no stable
+// id/selector can't be written to source, so it is returned as `dropped` for
+// the revert-on-reload warning. Exported so tests can drive the menu → commit path.
+export function resolveZIndexEntries(
+  sel: DomEditSelection,
+  patches: ReadonlyArray<{ element: HTMLElement; zIndex: number }>,
+): { entries: ZIndexReorderEntry[]; dropped: Array<{ element: HTMLElement; zIndex: number }> } {
+  const entries: ZIndexReorderEntry[] = [];
+  const dropped: Array<{ element: HTMLElement; zIndex: number }> = [];
+  for (const patch of patches) {
+    if (patch.element === sel.element) {
+      entries.push(selectedZIndexEntry(sel, patch.zIndex));
+      continue;
+    }
+    const entry = siblingZIndexEntry(patch.element, patch.zIndex, sel.sourceFile);
+    if (entry) entries.push(entry);
+    else dropped.push(patch);
+  }
+  return { entries, dropped };
+}
+
+// Studio's DomEditOverlay wired to the session in DomEditProvider, so a host
+// outside EditorShell mounts the same canvas editing without its own callbacks.
+export function ConnectedDomEditOverlay({
+  activeCompositionPath,
+  showHoverSelection,
+  shouldShowSelectedDomBounds,
+  isGestureRecording,
+  canvasInput,
+  onTextEditingChange,
+  onSelectionBoxClick,
+}: ConnectedDomEditOverlayProps) {
+  const { domEditHoverSelection, domEditSelection, domEditGroupSelections } =
+    useDomEditSelectionContext();
+  const {
+    previewIframeRef,
+    handlePreviewCanvasMouseDown,
+    handlePreviewCanvasPointerMove,
+    handlePreviewCanvasPointerLeave,
+    applyDomSelection,
+    handleBlockedDomMove,
+    handleDomManualDragStart,
+    handleDomPathOffsetCommit,
+    handleDomGroupPathOffsetCommit,
+    handleDomBoxSizeCommit,
+    handleDomRotationCommit,
+    handleDomStyleCommit,
+    applyMarqueeSelection,
+    handleDomEditElementDelete,
+    handleDomZIndexReorderCommit,
+  } = useDomEditActionsContext();
+  const mirrorZOrderToTimeline = useCanvasZOrderTimelineMirror();
+
+  return (
+    <DomEditOverlay
+      iframeRef={previewIframeRef}
+      activeCompositionPath={activeCompositionPath}
+      hoverSelection={showHoverSelection ? domEditHoverSelection : null}
+      selection={shouldShowSelectedDomBounds ? domEditSelection : null}
+      groupSelections={shouldShowSelectedDomBounds ? domEditGroupSelections : []}
+      allowCanvasMovement={!isGestureRecording}
+      canvasInput={canvasInput}
+      onTextEditingChange={onTextEditingChange}
+      onSelectionBoxClick={onSelectionBoxClick}
+      onCanvasMouseDown={handlePreviewCanvasMouseDown}
+      onCanvasPointerMove={handlePreviewCanvasPointerMove}
+      onCanvasPointerLeave={handlePreviewCanvasPointerLeave}
+      onSelectionChange={applyDomSelection}
+      onBlockedMove={handleBlockedDomMove}
+      onManualDragStart={handleDomManualDragStart}
+      onPathOffsetCommit={handleDomPathOffsetCommit}
+      onGroupPathOffsetCommit={handleDomGroupPathOffsetCommit}
+      onBoxSizeCommit={handleDomBoxSizeCommit}
+      onRotationCommit={handleDomRotationCommit}
+      onStyleCommit={handleDomStyleCommit}
+      onDeleteSelection={handleDomEditElementDelete}
+      onApplyZIndex={(sel, patches, action, crossed) => {
+        const { entries, dropped } = resolveZIndexEntries(sel, patches);
+        if (dropped.length > 0) {
+          // These siblings can't be written to source. Apply their live z
+          // anyway so the resolved stacking order renders coherently — it
+          // just reverts to the prior order on the next reload.
+          for (const patch of dropped) patch.element.style.zIndex = String(patch.zIndex);
+          console.warn(
+            "[studio] z-index reorder: dropping sibling(s) with no stable id/selector " +
+              "(will revert on reload):",
+            dropped.map((patch) => describeZIndexElement(patch.element)).join(", "),
+          );
+        }
+        if (entries.length === 0) return;
+        // One coalesce key for the z persist AND the lane mirror folds both into one undo entry;
+        // passed explicitly so the mirror shares it by construction, not by formula duplication.
+        const coalesceKey = zReorderCoalesceKey(entries, action);
+        // One serialized z→lane transaction: the mirror runs only AFTER a durable z commit and
+        // no second gesture interleaves (see runZLaneGesture). A failed z commit has already
+        // toasted and rolled back, so the catch only keeps its rejection from going unhandled.
+        runZLaneGesture({
+          commitZ: () => handleDomZIndexReorderCommit(entries, coalesceKey, action),
+          mirror: () =>
+            mirrorZOrderToTimeline({
+              selectionKey: entries.find((e) => e.element === sel.element)?.key,
+              action,
+              crossed,
+              sourceFile: sel.sourceFile,
+              coalesceKey,
+            }),
+        }).catch(() => undefined);
+      }}
+      onMarqueeSelect={applyMarqueeSelection}
+    />
+  );
+}

package/src/components/editor/DomEditOverlay.tsx

@@ -54,6 +54,14 @@ interface DomEditOverlayProps {
   groupSelections?: DomEditSelection[];
   hoverSelection: DomEditSelection | null;
   allowCanvasMovement?: boolean;
+  /** "host": no hover, marquee or box re-select; Enter with nothing focused still opens text. */
+  canvasInput?: "overlay" | "host";
+  onTextEditingChange?: (editing: boolean) => void;
+  /** A click on a single selection's box, in either mode; the event may be the pointerup. */
+  onSelectionBoxClick?: (
+    event: React.MouseEvent<HTMLDivElement>,
+    selection: DomEditSelection,
+  ) => void;
   onCanvasMouseDown: (
     event: React.MouseEvent<HTMLDivElement>,
     options?: PreviewMouseDownOptions,
@@ -117,7 +125,10 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   groupSelections = [],
   hoverSelection,
   allowCanvasMovement = true,
-  onCanvasMouseDown,
+  canvasInput = "overlay",
+  onTextEditingChange,
+  onSelectionBoxClick,
+  onCanvasMouseDown: onCanvasMouseDownProp,
   onCanvasPointerMove,
   onCanvasPointerLeave,
   onSelectionChange,
@@ -133,6 +144,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onApplyZIndex,
 }: DomEditOverlayProps) {
   const readOnly = usePreviewReadOnly();
+  const hostInput = canvasInput === "host";
   const overlayRef = useRef<HTMLDivElement | null>(null);
   const boxRef = useRef<HTMLDivElement | null>(null);
   const onMarqueeSelectRef = useRef(onMarqueeSelect);
@@ -150,6 +162,13 @@ export const DomEditOverlay = memo(function DomEditOverlay({
 
   const selectionRef = useRef(selection);
   selectionRef.current = selection;
+  const onCanvasMouseDown: typeof onCanvasMouseDownProp = (event, options) => {
+    const sel = selectionRef.current;
+    if (sel && boxRef.current?.contains(event.target as Node | null)) {
+      onSelectionBoxClick?.(event, sel);
+    }
+    if (!hostInput) onCanvasMouseDownProp(event, options);
+  };
 
   // Brief highlight on the sibling a forward/backward z step crossed — drawn
   // in this studio overlay, never in the iframe DOM (see useZOrderCrossedFlash).
@@ -163,7 +182,14 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   hoverSelectionRef.current = hoverSelection;
 
   // Double-click an element to edit its text where it sits.
-  const inlineText = useInlineTextEditing(selectionRef);
+  const inlineText = useInlineTextEditing(selectionRef, { enterFromWindow: hostInput });
+  const onTextEditingChangeRef = useRef(onTextEditingChange);
+  onTextEditingChangeRef.current = onTextEditingChange;
+  useEffect(() => {
+    if (!inlineText.editing) return;
+    onTextEditingChangeRef.current?.(true);
+    return () => onTextEditingChangeRef.current?.(false);
+  }, [inlineText.editing]);
   const onPathOffsetCommitRef = useRef(onPathOffsetCommit);
   onPathOffsetCommitRef.current = onPathOffsetCommit;
   const onGroupPathOffsetCommitRef = useRef(onGroupPathOffsetCommit);
@@ -322,7 +348,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
 
   // fallow-ignore-next-line complexity
   const handleOverlayPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
-    if (!allowCanvasMovement || event.button !== 0) return;
+    if (!allowCanvasMovement || hostInput || event.button !== 0) return;
     if (event.shiftKey) {
       const shiftIframe = iframeRef.current;
       const candidate = resolveShiftClickCandidate({
@@ -378,9 +404,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           )
         : null;
       if (freshTarget) return;
-      const overlayEl = overlayRef.current;
-      if (overlayEl) {
-        const oRect = overlayEl.getBoundingClientRect();
+      if (overlayRef.current) {
         // Anywhere empty on the overlay starts one, not just inside the frame.
         // An element dragged past the edge sits OUT there in the grey, and a
         // rubber band that refuses to start there cannot reach it — which left
@@ -390,17 +414,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
         event.preventDefault();
         event.stopPropagation();
         suppressNextOverlayMouseDownRef.current = true;
-        (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
-        const cx = event.clientX - oRect.left;
-        const cy = event.clientY - oRect.top;
-        marquee.marqueeRef.current = {
-          startX: cx,
-          startY: cy,
-          currentX: cx,
-          currentY: cy,
-          pointerId: event.pointerId,
-          pastThreshold: false,
-        };
+        marquee.begin(event);
         return;
       }
     }
@@ -440,7 +454,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       // Standing aside is the only way the caret below can be reached, and is
       // what keeps selection, drag and marquee from firing mid-edit.
       className={`absolute inset-0 z-10 outline-hidden ${
-        inlineText.editing ? "pointer-events-none" : "pointer-events-auto"
+        inlineText.editing || hostInput ? "pointer-events-none" : "pointer-events-auto"
       }`}
       data-editing-text={inlineText.editing ? "true" : undefined}
       tabIndex={-1}
@@ -451,6 +465,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
         // A pointer gesture supersedes a pending nudge burst — commit it first
         // so the gesture's member snapshot starts from the nudged position.
         flushNudge();
+        suppressNextBoxClickRef.current = false;
         // Not while editing: taking focus back would send the keystroke nowhere.
         if (!inlineText.editing) {
           focusDomEditOverlayElement(event.currentTarget as FocusableDomEditOverlay);
@@ -467,9 +482,9 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       onPointerLeave={() => onCanvasPointerLeaveRef.current()}
       onPointerUp={marquee.onPointerUp}
       onPointerCancel={marquee.onPointerCancel}
-      onContextMenu={handleContextMenu}
+      onContextMenu={hostInput ? undefined : handleContextMenu}
     >
-      {hoverSelection && hoverRect && compRect.width > 0 && (
+      {!hostInput && hoverSelection && hoverRect && compRect.width > 0 && (
         <div
           aria-hidden="true"
           data-dom-edit-hover-box="true"
@@ -516,7 +531,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           editing session, which does. */}
       {inlineText.toolbar}
       <OffCanvasIndicators
-        rects={offCanvasRects}
+        rects={hostInput ? [] : offCanvasRects}
         elements={offCanvasElementsRef}
         compRect={compRect}
         selection={selection}

package/src/components/editor/LayersPanel.tsx

@@ -343,7 +343,7 @@ export const LayersPanel = memo(function LayersPanel() {
 
       // ONE undo entry for the whole gesture: the z persist and the timeline
       // lane mirror below share this per-gesture-unique key (same contract as
-      // the canvas menu's wiring in PreviewOverlays).
+      // the canvas menu's wiring in ConnectedDomEditOverlay).
       const coalesceKey = zReorderCoalesceKey(entries, "layer-drag");
       const desiredOrderKeys = desiredBottomToTop.map(
         (l) =>

package/src/components/editor/MarqueeOverlay.tsx

@@ -1,6 +1,6 @@
 import type { Rect } from "../../utils/marqueeGeometry";
 
-interface MarqueeOverlayProps {
+export interface MarqueeOverlayProps {
   /** Elements the marquee currently intersects — outlined live before mouse-up. */
   candidateRects: Rect[];
   /** The marquee drag rectangle itself, or null when not marquee-selecting. */

package/src/components/editor/SnapGuideOverlay.tsx

@@ -15,7 +15,7 @@ const GUIDE_COLOR = "rgba(255, 68, 204, 0.85)";
 const SPACING_COLOR = "rgba(255, 68, 204, 0.6)";
 const SPACING_BG = "rgba(255, 68, 204, 0.15)";
 
-interface SnapGuideOverlayProps {
+export interface SnapGuideOverlayProps {
   snapGuidesRef: RefObject<SnapGuidesState | null>;
   /** Composition rect in overlay space — guide lines span exactly this rect. */
   compositionLeft: number;

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { clipAudioOnItsClock, readClipClock } from "./clipAudioClock";
+
+const RATE = 48000;
+const sine = (seconds: number, hz: number) =>
+  Float32Array.from({ length: RATE * seconds }, (_, i) => Math.sin((2 * Math.PI * hz * i) / RATE));
+const zeroCrossingsPerSecond = (x: Float32Array) => {
+  let n = 0;
+  for (let i = 1; i < x.length; i += 1) if (x[i - 1]! < 0 !== x[i]! < 0) n += 1;
+  return n / (x.length / RATE);
+};
+
+describe("readClipClock", () => {
+  it("reads the in-point, the rate lane over the constant, and a positive duration", () => {
+    const attrs: Record<string, string> = {
+      "data-playback-start": "1.5",
+      "data-media-start": "9",
+      "data-playback-rate": "3",
+      "data-automation":
+        '{"version":1,"lanes":[{"target":"rate","points":[{"t":0,"v":2},{"t":4,"v":2}]}]}',
+      "data-duration": "4",
+    };
+    const clock = readClipClock((name) => attrs[name]);
+    expect({ ...clock, rate: typeof clock.rate }).toEqual({
+      inPoint: 1.5,
+      rate: "object",
+      duration: 4,
+    });
+    expect(readClipClock((name) => (name === "data-duration" ? "0" : null))).toEqual({
+      inPoint: 0,
+      rate: 1,
+      duration: null,
+    });
+  });
+});
+
+describe("clipAudioOnItsClock", () => {
+  it("is the exact slice the clip plays at rate 1", () => {
+    const samples = sine(4, 440);
+    const out = clipAudioOnItsClock(samples, RATE, { inPoint: 1, rate: 1, duration: 2 });
+    expect(Array.from(out)).toEqual(Array.from(samples.subarray(RATE, 3 * RATE)));
+  });
+
+  it("lasts the clip's duration at 2x, consuming twice as much source", () => {
+    // Each sample holds its own source time, so the output reads back where it was taken from.
+    const samples = Float32Array.from({ length: RATE * 6 }, (_, i) => i / RATE);
+    const out = clipAudioOnItsClock(samples, RATE, { inPoint: 1, rate: 2, duration: 2 });
+    expect({ length: out.length, atOneSecond: Number(out[RATE]!.toFixed(1)) }).toEqual({
+      length: 2 * RATE,
+      atOneSecond: 3,
+    });
+  });
+
+  it("keeps the pitch at 2x and 0.5x", () => {
+    const samples = sine(4, 440);
+    for (const rate of [2, 0.5]) {
+      const out = clipAudioOnItsClock(samples, RATE, { inPoint: 0, rate, duration: 1.5 });
+      expect(zeroCrossingsPerSecond(out) / 880).toBeCloseTo(1, 1);
+    }
+  });
+});

package/src/components/editor/clipAudioClock.ts

@@ -0,0 +1,78 @@
+import {
+  resolveRateSpec,
+  sourceTimeAt,
+  timeAtSourceTime,
+  type RateSpec,
+} from "@hyperframes/core/speed-ramp";
+import {
+  readDataDurationSeconds,
+  readMediaOffsetSeconds,
+  readPlaybackRate,
+  type AttrReader,
+} from "@hyperframes/parsers/media-duration";
+
+/** Where a clip's audio starts in its file, how fast it plays, and for how long (null: to the end). */
+export interface ClipClock {
+  inPoint: number;
+  rate: RateSpec;
+  duration: number | null;
+}
+
+export function readClipClock(getAttr: AttrReader): ClipClock {
+  return {
+    inPoint: readMediaOffsetSeconds(getAttr),
+    rate: resolveRateSpec(getAttr("data-automation"), readPlaybackRate(getAttr)),
+    duration: readDataDurationSeconds(getAttr),
+  };
+}
+
+/** The source samples a clip plays, still on the file's clock. */
+export function clipSourceWindow(
+  samples: Float32Array,
+  sampleRate: number,
+  clock: ClipClock,
+): Float32Array {
+  const from = Math.min(samples.length, Math.floor(clock.inPoint * sampleRate));
+  const to = clock.duration
+    ? Math.min(
+        samples.length,
+        from + Math.ceil(sourceTimeAt(clock.rate, clock.duration) * sampleRate),
+      )
+    : samples.length;
+  return samples.subarray(from, to);
+}
+
+const GRAIN = 4096;
+const HOP = GRAIN / 2;
+const HANN = Float32Array.from(
+  { length: GRAIN },
+  (_, k) => 0.5 - 0.5 * Math.cos((2 * Math.PI * k) / GRAIN),
+);
+
+/**
+ * The audio heard over clip time [0, duration]. Off rate 1, Hann grains overlap-added at the source
+ * time each lands on: pitch kept, like export's atempo, close enough for band and level analysis.
+ */
+export function clipAudioOnItsClock(
+  samples: Float32Array,
+  sampleRate: number,
+  clock: ClipClock,
+): Float32Array {
+  const source = clipSourceWindow(samples, sampleRate, clock);
+  if (clock.rate === 1) return source;
+  const out = new Float32Array(
+    Math.round(timeAtSourceTime(clock.rate, source.length / sampleRate) * sampleRate),
+  );
+  // Grains are not phase-aligned, so off rate 1 the level reads ~1.3 dB low (up to ~3 dB on
+  // tones); a WSOLA stretch would keep it.
+  for (let at = -HOP; at < out.length; at += HOP) {
+    const centre = Math.round(sourceTimeAt(clock.rate, (at + HOP) / sampleRate) * sampleRate);
+    for (let k = 0; k < GRAIN; k += 1) {
+      const o = at + k;
+      const s = centre - HOP + k;
+      if (o < 0 || o >= out.length || s < 0 || s >= source.length) continue;
+      out[o] = (out[o] ?? 0) + (HANN[k] ?? 0) * (source[s] ?? 0);
+    }
+  }
+  return out;
+}