@hyperframes/studio 0.7.57 → 0.7.59

package/src/components/storyboard/frameComments.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import { buildCommentsFile, draftEntries, parseCommentsFile, passForFrames } from "./frameComments";
+
+const frames = [
+  { index: 1, status: "built" as const, src: "compositions/frames/01-hook.html", title: "Hook" },
+  {
+    index: 2,
+    status: "built" as const,
+    src: "compositions/frames/02-thesis.html",
+    title: "Thesis",
+  },
+  { index: 3, status: "built" as const, src: "compositions/frames/03-proof.html", title: "Proof" },
+];
+
+describe("passForFrames", () => {
+  it("maps the furthest status to the review pass", () => {
+    expect(passForFrames([{ status: "outline" }, { status: "outline" }])).toBe("storyboard");
+    expect(passForFrames([{ status: "outline" }, { status: "built" }])).toBe("sketch");
+    expect(passForFrames([{ status: "built" }, { status: "animated" }])).toBe("final");
+  });
+});
+
+describe("draftEntries", () => {
+  it("keeps only non-empty drafts, in board order, with src/title echoed", () => {
+    const entries = draftEntries(frames, { 3: "swap the chart", 1: "  ", 2: "tighter kerning" });
+    expect(entries).toEqual([
+      { frame: 2, src: frames[1]?.src, title: "Thesis", text: "tighter kerning" },
+      { frame: 3, src: frames[2]?.src, title: "Proof", text: "swap the chart" },
+    ]);
+  });
+});
+
+describe("parseCommentsFile", () => {
+  it("reads a well-formed file", () => {
+    const parsed = parseCommentsFile(
+      JSON.stringify({
+        version: 1,
+        pass: "sketch",
+        submitted_at: "2026-07-10T00:00:00Z",
+        comments: [{ frame: 2, text: "hi" }],
+      }),
+    );
+    expect(parsed?.pass).toBe("sketch");
+    expect(parsed?.comments).toEqual([{ frame: 2, src: undefined, title: undefined, text: "hi" }]);
+  });
+
+  it("treats empty or malformed input as no file", () => {
+    expect(parseCommentsFile("")).toBeNull();
+    expect(parseCommentsFile("not json")).toBeNull();
+    expect(parseCommentsFile(JSON.stringify({ comments: "nope" }))).toBeNull();
+  });
+
+  it("drops malformed entries but keeps the valid ones", () => {
+    const parsed = parseCommentsFile(
+      JSON.stringify({ comments: [{ frame: 1, text: "ok" }, { frame: "x" }, null] }),
+    );
+    expect(parsed?.comments).toEqual([{ frame: 1, src: undefined, title: undefined, text: "ok" }]);
+  });
+});
+
+describe("buildCommentsFile", () => {
+  it("merges an unconsumed previous batch: new frames win, others stay", () => {
+    const previous = parseCommentsFile(
+      JSON.stringify({
+        version: 1,
+        pass: "sketch",
+        submitted_at: "2026-07-10T00:00:00Z",
+        comments: [
+          { frame: 1, text: "old note on hook" },
+          { frame: 3, text: "old note on proof" },
+        ],
+      }),
+    );
+    const file = buildCommentsFile(
+      frames,
+      { 3: "new note on proof" },
+      previous,
+      "2026-07-10T01:00:00Z",
+    );
+    expect(file.pass).toBe("sketch");
+    expect(file.submitted_at).toBe("2026-07-10T01:00:00Z");
+    expect(file.comments.map((c) => [c.frame, c.text])).toEqual([
+      [1, "old note on hook"],
+      [3, "new note on proof"],
+    ]);
+  });
+
+  it("writes a fresh batch when no previous file exists", () => {
+    const file = buildCommentsFile(frames, { 2: "tighter" }, null, "2026-07-10T01:00:00Z");
+    expect(file.version).toBe(1);
+    expect(file.comments).toEqual([
+      { frame: 2, src: frames[1]?.src, title: "Thesis", text: "tighter" },
+    ]);
+  });
+});

package/src/components/storyboard/frameComments.ts

@@ -0,0 +1,115 @@
+import type { FrameStatus } from "@hyperframes/core/storyboard";
+
+/**
+ * Frame comments — the storyboard review's structured feedback channel.
+ *
+ * The board's per-frame comment boxes write one batch file on submit; the
+ * consuming agent revises exactly the frames named, deletes the file, and
+ * re-presents. The file shape is a cross-repo contract — keep it in sync with
+ * skills/hyperframes-core/references/storyboard-format.md § Frame comments.
+ */
+export const FRAME_COMMENTS_PATH = ".hyperframes/frame-comments.json";
+
+export type FrameCommentsPass = "storyboard" | "sketch" | "final";
+
+export interface FrameCommentEntry {
+  /** The frame's 1-based `index` in the manifest — the key. */
+  frame: number;
+  /** Copied from the frame at submit time so a post-submit reorder is detectable. */
+  src?: string;
+  title?: string;
+  text: string;
+}
+
+export interface FrameCommentsFile {
+  version: 1;
+  pass: FrameCommentsPass;
+  submitted_at: string;
+  comments: FrameCommentEntry[];
+}
+
+interface CommentableFrame {
+  index: number;
+  status: FrameStatus;
+  src?: string;
+  title?: string;
+}
+
+/** Which review the batch belongs to — the furthest status present on the board. */
+export function passForFrames(frames: ReadonlyArray<{ status: FrameStatus }>): FrameCommentsPass {
+  if (frames.some((f) => f.status === "animated")) return "final";
+  if (frames.some((f) => f.status === "built")) return "sketch";
+  return "storyboard";
+}
+
+/** The non-empty drafts as file entries, in board order. */
+export function draftEntries(
+  frames: readonly CommentableFrame[],
+  drafts: Readonly<Record<number, string>>,
+): FrameCommentEntry[] {
+  const entries: FrameCommentEntry[] = [];
+  for (const frame of frames) {
+    const text = drafts[frame.index]?.trim();
+    if (!text) continue;
+    entries.push({ frame: frame.index, src: frame.src, title: frame.title, text });
+  }
+  return entries;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function parseCommentEntry(item: unknown): FrameCommentEntry | null {
+  if (!isRecord(item)) return null;
+  if (typeof item.frame !== "number" || typeof item.text !== "string") return null;
+  return {
+    frame: item.frame,
+    src: typeof item.src === "string" ? item.src : undefined,
+    title: typeof item.title === "string" ? item.title : undefined,
+    text: item.text,
+  };
+}
+
+function parsePass(value: unknown): FrameCommentsPass {
+  return value === "sketch" || value === "final" ? value : "storyboard";
+}
+
+/** Tolerant read of an existing comments file — anything malformed counts as "no file". */
+export function parseCommentsFile(raw: string): FrameCommentsFile | null {
+  if (!raw.trim()) return null;
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(data) || !Array.isArray(data.comments)) return null;
+  const comments = data.comments
+    .map(parseCommentEntry)
+    .filter((entry): entry is FrameCommentEntry => entry !== null);
+  return {
+    version: 1,
+    pass: parsePass(data.pass),
+    submitted_at: typeof data.submitted_at === "string" ? data.submitted_at : "",
+    comments,
+  };
+}
+
+/**
+ * One file = the currently pending feedback. A resubmit before the agent
+ * consumed the previous batch keeps the pending entries for frames the new
+ * batch doesn't mention and overwrites the ones it does.
+ */
+export function buildCommentsFile(
+  frames: readonly CommentableFrame[],
+  drafts: Readonly<Record<number, string>>,
+  previous: FrameCommentsFile | null,
+  submittedAt: string,
+): FrameCommentsFile {
+  const fresh = draftEntries(frames, drafts);
+  const freshIndexes = new Set(fresh.map((entry) => entry.frame));
+  const kept = previous?.comments.filter((entry) => !freshIndexes.has(entry.frame)) ?? [];
+  const comments = [...kept, ...fresh].sort((a, b) => a.frame - b.frame);
+  return { version: 1, pass: passForFrames(frames), submitted_at: submittedAt, comments };
+}

package/src/components/storyboard/useFrameComments.ts

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useFileManagerContext } from "../../contexts/FileManagerContext";
+import type { StoryboardFrameView } from "../../hooks/useStoryboard";
+import {
+  FRAME_COMMENTS_PATH,
+  buildCommentsFile,
+  parseCommentsFile,
+  type FrameCommentEntry,
+} from "./frameComments";
+
+export type CommentsSubmitState = "idle" | "saving";
+
+export interface FrameCommentsValue {
+  /** Draft text per frame index — "" / absent means no comment. */
+  drafts: Record<number, string>;
+  setDraft: (index: number, text: string) => void;
+  /** How many frames currently carry a non-empty draft. */
+  draftCount: number;
+  submitState: CommentsSubmitState;
+  /** Write the batch to `.hyperframes/frame-comments.json` and clear the drafts. */
+  submit: () => Promise<void>;
+  /**
+   * Comments already submitted but not yet consumed by the agent (the file
+   * still exists on disk). Refreshed on mount, after submit, and on window
+   * focus — the agent deletes the file once it has applied the feedback.
+   */
+  pending: FrameCommentEntry[] | null;
+  /** Re-read the comments file — callers hook this to board data refreshes. */
+  refreshPending: () => Promise<void>;
+}
+
+/** Per-frame comment drafts + the batch submit that writes the comments file. */
+export function useFrameComments(frames: StoryboardFrameView[]): FrameCommentsValue {
+  const { writeProjectFile, readOptionalProjectFile } = useFileManagerContext();
+  const [drafts, setDrafts] = useState<Record<number, string>>({});
+  const [submitState, setSubmitState] = useState<CommentsSubmitState>("idle");
+  const [pending, setPending] = useState<FrameCommentEntry[] | null>(null);
+
+  const refreshPending = useCallback(async () => {
+    try {
+      const parsed = parseCommentsFile(await readOptionalProjectFile(FRAME_COMMENTS_PATH));
+      setPending(parsed && parsed.comments.length > 0 ? parsed.comments : null);
+    } catch {
+      // Transient read failure — keep whatever is currently shown.
+    }
+  }, [readOptionalProjectFile]);
+
+  useEffect(() => {
+    void refreshPending();
+    const onFocus = () => void refreshPending();
+    window.addEventListener("focus", onFocus);
+    return () => window.removeEventListener("focus", onFocus);
+  }, [refreshPending]);
+
+  const setDraft = useCallback((index: number, text: string) => {
+    setDrafts((prev) => ({ ...prev, [index]: text }));
+  }, []);
+
+  const draftCount = useMemo(
+    () => Object.values(drafts).filter((text) => text.trim().length > 0).length,
+    [drafts],
+  );
+
+  const submit = useCallback(async () => {
+    if (draftCount === 0 || submitState === "saving") return;
+    setSubmitState("saving");
+    try {
+      const previous = parseCommentsFile(await readOptionalProjectFile(FRAME_COMMENTS_PATH));
+      const file = buildCommentsFile(frames, drafts, previous, new Date().toISOString());
+      await writeProjectFile(FRAME_COMMENTS_PATH, `${JSON.stringify(file, null, 2)}\n`);
+      setDrafts({});
+      setPending(file.comments);
+    } catch {
+      // writeProjectFile surfaces save failures through the studio save banner;
+      // just re-arm the button so the user can retry.
+    } finally {
+      setSubmitState("idle");
+    }
+  }, [draftCount, submitState, frames, drafts, readOptionalProjectFile, writeProjectFile]);
+
+  return { drafts, setDraft, draftCount, submitState, submit, pending, refreshPending };
+}

package/src/contexts/DesignPanelInputContext.test.tsx

@@ -0,0 +1,81 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const trackDesignInput = vi.fn();
+vi.mock("../utils/designInputTracking", () => ({
+  trackDesignInput: (...args: unknown[]) => trackDesignInput(...args),
+}));
+
+import { DesignPanelInputProvider, useTrackDesignInput } from "./DesignPanelInputContext";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+beforeEach(() => trackDesignInput.mockReset());
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function FireButton({ control, name }: { control: string; name: string }) {
+  const track = useTrackDesignInput();
+  return (
+    <button type="button" onClick={() => track(control, name)}>
+      fire
+    </button>
+  );
+}
+
+function renderAndClick(tree: React.ReactElement) {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  act(() => root.render(tree));
+  act(() => {
+    host.querySelector("button")!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+  });
+  act(() => root.unmount());
+}
+
+describe("DesignPanelInputContext", () => {
+  it("binds the tracker to the enclosing ui + section", () => {
+    renderAndClick(
+      <DesignPanelInputProvider ui="flat" section="style">
+        <FireButton control="metric" name="Opacity" />
+      </DesignPanelInputProvider>,
+    );
+    expect(trackDesignInput).toHaveBeenCalledWith({
+      ui: "flat",
+      section: "style",
+      control: "metric",
+      name: "Opacity",
+    });
+  });
+
+  it("nested provider overrides section but inherits ui from parent", () => {
+    renderAndClick(
+      <DesignPanelInputProvider ui="flat" section="outer">
+        <DesignPanelInputProvider section="color-grading">
+          <FireButton control="slider" name="Exposure" />
+        </DesignPanelInputProvider>
+      </DesignPanelInputProvider>,
+    );
+    expect(trackDesignInput).toHaveBeenCalledWith({
+      ui: "flat",
+      section: "color-grading",
+      control: "slider",
+      name: "Exposure",
+    });
+  });
+
+  it("defaults to classic/unknown with no provider", () => {
+    renderAndClick(<FireButton control="button" name="Reset" />);
+    expect(trackDesignInput).toHaveBeenCalledWith({
+      ui: "classic",
+      section: "unknown",
+      control: "button",
+      name: "Reset",
+    });
+  });
+});

package/src/contexts/DesignPanelInputContext.tsx

@@ -0,0 +1,48 @@
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
+import { trackDesignInput, type DesignInputUi } from "../utils/designInputTracking";
+
+// Carries which inspector UI and which section the currently-rendered design-panel
+// inputs belong to, so commit sites only pass { control, name } and never thread
+// section/ui through every call. Providers nest: PropertyPanel sets `ui` once at the
+// top; each Section sets `section` and inherits `ui` from the parent.
+
+interface DesignPanelInputContextValue {
+  ui: DesignInputUi;
+  section: string;
+}
+
+const DesignPanelInputContext = createContext<DesignPanelInputContextValue>({
+  ui: "classic",
+  section: "unknown",
+});
+
+export function DesignPanelInputProvider({
+  ui,
+  section,
+  children,
+}: {
+  ui?: DesignInputUi;
+  section?: string;
+  children: ReactNode;
+}) {
+  const parent = useContext(DesignPanelInputContext);
+  const value = useMemo(
+    () => ({ ui: ui ?? parent.ui, section: section ?? parent.section }),
+    [ui, section, parent.ui, parent.section],
+  );
+  return (
+    <DesignPanelInputContext.Provider value={value}>{children}</DesignPanelInputContext.Provider>
+  );
+}
+
+/**
+ * Returns a stable `track(control, name)` fn bound to the current UI + section.
+ * Call it from any input's commit handler.
+ */
+export function useTrackDesignInput(): (control: string, name: string) => void {
+  const { ui, section } = useContext(DesignPanelInputContext);
+  return useCallback(
+    (control: string, name: string) => trackDesignInput({ ui, section, control, name }),
+    [ui, section],
+  );
+}

package/src/contexts/DomEditContext.tsx

@@ -16,6 +16,7 @@ export interface DomEditActionsValue extends Pick<
   | "handleDomAttributeCommit"
   | "handleDomAttributeLiveCommit"
   | "handleDomHtmlAttributeCommit"
+  | "handleDomAttributesCommit"
   | "handleDomPathOffsetCommit"
   | "handleDomGroupPathOffsetCommit"
   | "handleDomZIndexReorderCommit"
@@ -138,6 +139,7 @@ export function DomEditProvider({
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomHtmlAttributeCommit,
+    handleDomAttributesCommit,
     handleDomPathOffsetCommit,
     handleDomGroupPathOffsetCommit,
     handleDomZIndexReorderCommit,
@@ -224,6 +226,7 @@ export function DomEditProvider({
       handleDomAttributeCommit,
       handleDomAttributeLiveCommit,
       handleDomHtmlAttributeCommit,
+      handleDomAttributesCommit,
       handleDomPathOffsetCommit,
       handleDomGroupPathOffsetCommit,
       handleDomZIndexReorderCommit,
@@ -291,6 +294,7 @@ export function DomEditProvider({
       handleDomAttributeCommit,
       handleDomAttributeLiveCommit,
       handleDomHtmlAttributeCommit,
+      handleDomAttributesCommit,
       handleDomPathOffsetCommit,
       handleDomGroupPathOffsetCommit,
       handleDomZIndexReorderCommit,

package/src/contexts/VariablePromoteContext.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import type { Composition } from "@hyperframes/sdk";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import {
+  VariablePromoteProvider,
+  useVariablePromoteChannel,
+  type ChannelPromote,
+} from "./VariablePromoteContext";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("VariablePromoteProvider save failures", () => {
+  it("reports a rejected promote instead of leaving an unhandled promise", async () => {
+    const snapshot = {
+      attributes: { id: "box" },
+      inlineStyles: {},
+      text: "",
+      children: [],
+    };
+    const session = {
+      getElement: vi.fn().mockReturnValue(snapshot),
+      getVariableDeclarations: vi.fn().mockReturnValue([]),
+      on: vi.fn().mockReturnValue(() => {}),
+    } as unknown as Composition;
+    const selection = {
+      hfId: "hf-box",
+      tagName: "div",
+      label: "Box",
+      capabilities: { canEditStyles: true },
+      computedStyles: { color: "rgb(255, 0, 0)" },
+    } as unknown as DomEditSelection;
+    const error = new Error("write failed");
+    const persist = vi.fn().mockRejectedValue(error);
+    const onPersistError = vi.fn();
+    let channel: ChannelPromote | null = null;
+
+    function Consumer() {
+      channel = useVariablePromoteChannel({ kind: "style", prop: "color" });
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    act(() => {
+      root.render(
+        <VariablePromoteProvider
+          session={session}
+          selection={selection}
+          persist={persist}
+          onPersistError={onPersistError}
+        >
+          <Consumer />
+        </VariablePromoteProvider>,
+      );
+    });
+    act(() => channel?.promote());
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    expect(persist).toHaveBeenCalledOnce();
+    expect(onPersistError).toHaveBeenCalledWith(error);
+    act(() => root.unmount());
+  });
+});

package/src/contexts/VariablePromoteContext.tsx

@@ -44,6 +44,7 @@ interface VariablePromoteContextValue {
   actions: BindAction[];
   declarations: CompositionVariable[];
   persist: (label: string, mutate: (session: Composition) => void) => Promise<boolean>;
+  onPersistError: (error: unknown) => void;
 }
 
 const VariablePromoteContext = createContext<VariablePromoteContextValue | null>(null);
@@ -58,11 +59,13 @@ export function VariablePromoteProvider({
   session,
   selection,
   persist,
+  onPersistError,
   children,
 }: {
   session: Composition | null;
   selection: DomEditSelection | null;
   persist: (label: string, mutate: (session: Composition) => void) => Promise<boolean>;
+  onPersistError: (error: unknown) => void;
   children: React.ReactNode;
 }) {
   // Re-derive actions/bindings after each persisted schema edit.
@@ -85,8 +88,8 @@ export function VariablePromoteProvider({
   }, [session, revision]);
 
   const value = useMemo<VariablePromoteContextValue>(
-    () => ({ session, selection, actions, declarations, persist }),
-    [session, selection, actions, declarations, persist],
+    () => ({ session, selection, actions, declarations, persist, onPersistError }),
+    [session, selection, actions, declarations, persist, onPersistError],
   );
 
   return (
@@ -105,7 +108,7 @@ export function useVariablePromoteChannel(channel: PromoteChannel): ChannelPromo
 
   return useMemo(() => {
     if (!ctx || !ctx.session || !ctx.selection?.hfId) return null;
-    const { session, selection, actions, declarations, persist } = ctx;
+    const { session, selection, actions, declarations, persist, onPersistError } = ctx;
     const hfId = selection.hfId!;
     const action = matchAction(actions, channel);
     const boundId = readBinding(session, hfId, channel);
@@ -125,12 +128,14 @@ export function useVariablePromoteChannel(channel: PromoteChannel): ChannelPromo
         const id = uniqueId(action.suggestedId, declarations);
         void persist(`Bind ${action.label.toLowerCase()} to variable "${id}"`, (s) =>
           applyBind(s, hfId, action, id),
-        );
+        ).catch(onPersistError);
       },
       setDefault: (raw: string) => {
         if (!boundId || !declaration) return;
         const next = declaration.type === "color" ? rgbToHex(raw) : raw;
-        void persist(`Set default for "${boundId}"`, (s) => s.setVariableValue(boundId, next));
+        void persist(`Set default for "${boundId}"`, (s) =>
+          s.setVariableValue(boundId, next),
+        ).catch(onPersistError);
       },
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/src/hooks/domEditCommitRunner.ts

@@ -7,6 +7,15 @@ interface DomEditCommitRunnerConfig {
   onError: (error: unknown) => void;
   shouldResync: () => boolean;
   resync: () => void | Promise<void>;
+  /**
+   * Reports success/failure without changing this function's own resolve-
+   * always contract — `persist` failures are handled here (revert + onError)
+   * and never rethrown, so callers awaiting `runDomEditCommit` can't observe
+   * failure via rejection. A caller that needs to react to a specific
+   * commit's outcome (e.g. reverting its OWN optimistic state) can pass this
+   * instead of relying on a rejection that will never come.
+   */
+  onSettled?: (ok: boolean) => void;
 }
 
 interface CommitVersionRef {
@@ -34,11 +43,13 @@ export async function runDomEditCommit(config: DomEditCommitRunnerConfig): Promi
 
   try {
     await config.persist();
+    config.onSettled?.(true);
   } catch (error) {
     if (config.shouldRevert(error)) {
       config.revert();
     }
     config.onError(error);
+    config.onSettled?.(false);
   }
 
   if (!config.shouldResync()) return;

package/src/hooks/domEditCommitTypes.ts

@@ -11,6 +11,8 @@ export type CommitDomEditPatchBatches = (
   options: {
     label: string;
     coalesceKey: string;
+    /** Per-entry undo coalesce window override (ms) — see EditHistoryEntry.coalesceMs. */
+    coalesceMs?: number;
     /**
      * Request skipping the preview iframe reload after a successful persist.
      * Only honored when the persist is provably in sync with the live DOM:
@@ -20,7 +22,21 @@ export type CommitDomEditPatchBatches = (
      */
     skipReload?: boolean;
   },
-) => Promise<void>;
+) => Promise<DomEditPatchBatchesResult>;
+
+/**
+ * Durability report for a patch-batches commit. `durable === false` means the
+ * server could not locate at least one patch target on disk — the preview was
+ * reloaded to reconverge, and dependent follow-up writes (the z→lane timeline
+ * mirror) must be skipped. `allMatched` retains the underlying match detail.
+ * `changed === false` means no source file was written: every patch was a
+ * byte-identical no-op, or the atomic gesture was refused before any write.
+ */
+export interface DomEditPatchBatchesResult {
+  durable: boolean;
+  allMatched: boolean;
+  changed: boolean;
+}
 
 export type PersistDomEditOperations = (
   selection: DomEditSelection,

package/src/hooks/elementLifecycleOpsTestUtils.ts

@@ -0,0 +1,25 @@
+import { vi } from "vitest";
+import type { useElementLifecycleOps } from "./useElementLifecycleOps";
+
+type LifecycleOpsParams = Parameters<typeof useElementLifecycleOps>[0];
+
+/**
+ * Baseline `useElementLifecycleOps` params for tests: inert stubs for every
+ * dependency, overridden per test (typically just `commitDomEditPatchBatches`).
+ * Shared by the z-reorder commit tests and the timeline-mirror harness.
+ */
+export function makeLifecycleOpsParams(
+  overrides: Partial<LifecycleOpsParams> & Pick<LifecycleOpsParams, "commitDomEditPatchBatches">,
+): LifecycleOpsParams {
+  return {
+    activeCompPath: "index.html",
+    showToast: vi.fn(),
+    writeProjectFile: vi.fn(async () => {}),
+    domEditSaveTimestampRef: { current: 0 },
+    editHistory: { recordEdit: vi.fn(async () => {}) },
+    projectIdRef: { current: null },
+    reloadPreview: vi.fn(),
+    clearDomSelection: vi.fn(),
+    ...overrides,
+  };
+}

package/src/hooks/fetchStubTestUtils.ts

@@ -0,0 +1,16 @@
+// Shared helpers for test-side `fetch` stubs (timelineTimingSync.test.ts,
+// useTimelineEditing.test.tsx): a JSON Response factory and a Request → URL
+// normalizer. Test-only module — imported exclusively from *.test.* files.
+
+export function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export function requestUrl(input: Parameters<typeof fetch>[0]): string {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.toString();
+  return input.url;
+}