Commit dab5f6e6e02e78675655e69503aa89654e5b8050 | the-knife

author	Theo Browne <me@t3.gg> 2026-09-04 07:50:15-07:00
committer	GitHub <noreply@github.com> 2026-09-04 07:50:15-07:00
log	dab5f6e6e02e78675655e69503aa89654e5b8050
tree	1dfcda353297683202f74a8910a67e01a87e5f60
parent	777f5bb2e11fe30e7fdcb5741b0b1d9bb20924d6
signature	Signed by PGP key B5690EEEBB952194

perf(web): defer composer draft serialization (#9695)

Defer the draft walk and JSON serialization until the storage write flushes.
Preserve hydration, migrations, attachment verification, and final flushes.

Continues the web portion of [#9049](https://github.com/pingdotgg/t3code/pull/9049).
The mobile storage migration remains separate.

Created with GPT-6 Astra (preview) in Codex.

Co-authored-by: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

3 files changed, 185 insertions(+), 86 deletions(-)

apps
- web
  - src
    composerDraftStore.test.ts
    composerDraftStore.ts
    lib
    storage.ts

apps/web/src/composerDraftStore.test.ts+137-75

 @@ -75,6 +75,7 @@ import {
   type ComposerFileAttachment,
   type ComposerImageAttachment,
   composerFileNeedsReattach,
+  partializeComposerDraftStoreState,
   useComposerDraftStore,
   DraftId,
 } from "./composerDraftStore";
 @@ -84,7 +85,7 @@ import {
   insertInlineTerminalContextPlaceholder,
   type TerminalContextDraft,
 } from "./lib/terminalContext";
-import { createDebouncedStorage } from "./lib/storage";
+import { createDeferredStorage } from "./lib/storage";
 function makeImage(input: {
   id: string;
 @@ -196,37 +197,42 @@ describe("composerDraftStore assistant citations", () => {
   beforeEach(resetComposerDraftStore);
   afterEach(resetComposerDraftStore);
-  it("keeps quotes, comments, and remote source IDs through persistence and removes them on clear", () => {
+  it("keeps quotes, comments, and remote source IDs through persistence and removes them on clear", async () => {
-    const threadId = ThreadId.make("citation-draft");
+    await useComposerDraftStore.persist.clearStorage();
-    const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
+    vi.useFakeTimers();
-    const citation = {
+    try {
-      version: 1 as const,
+      const threadId = ThreadId.make("citation-draft");
-      environmentId: EnvironmentId.make("remote-source"),
+      const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
-      threadId: ThreadId.make("source-thread"),
+      const citation = {
-      messageId: MessageId.make("source-message"),
+        version: 1 as const,
-      text: "Preserve the selected text after reload.",
+        environmentId: EnvironmentId.make("remote-source"),
-      comment: "Why is this important?\nPlease show an example.",
+        threadId: ThreadId.make("source-thread"),
-      start: 12,
+        messageId: MessageId.make("source-message"),
-      end: 52,
+        text: "Preserve the selected text after reload.",
-      prefix: "Before. ",
+        comment: "Why is this important?\nPlease show an example.",
-      suffix: " After.",
+        start: 12,
-    };
+        end: 52,
-    const prompt = `Explain ${serializeAssistantCitation(citation)} further.`;
+        prefix: "Before. ",
-    useComposerDraftStore.getState().setPrompt(threadRef, prompt);
+        suffix: " After.",
-    const options = useComposerDraftStore.persist.getOptions();
+      };
-    const saved = JSON.parse(
+      const prompt = `Explain ${serializeAssistantCitation(citation)} further.`;
-      JSON.stringify(options.partialize!(useComposerDraftStore.getState())),
+      useComposerDraftStore.getState().setPrompt(threadRef, prompt);
-    ) as unknown;
+      await vi.advanceTimersByTimeAsync(300);
-    resetComposerDraftStore();
+      resetComposerDraftStore();
-    const hydrated = options.merge!(saved, useComposerDraftStore.getState());
+      await useComposerDraftStore.persist.rehydrate();
-    useComposerDraftStore.setState(hydrated);
+      const restored = draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt ?? "";
-    const restored = draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt ?? "";
+      expect(restored).toBe(prompt);
-    expect(restored).toBe(prompt);
+      expect(collectAssistantCitations(restored).map((entry) => entry.citation)).toEqual([
-    expect(collectAssistantCitations(restored).map((entry) => entry.citation)).toEqual([citation]);
+        citation,
-    useComposerDraftStore.getState().clearComposerContent(threadRef);
+      ]);
-    expect(
+      useComposerDraftStore.getState().clearComposerContent(threadRef);
-      collectAssistantCitations(draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt ?? ""),
+      expect(
-    ).toEqual([]);
+        collectAssistantCitations(draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt ?? ""),
+      ).toEqual([]);
+    } finally {
+      await useComposerDraftStore.persist.clearStorage();
+      vi.useRealTimers();
+    }
   });
 });
 @@ -388,7 +394,6 @@ describe("composerDraftStore file attachments", () => {
     const persistApi = useComposerDraftStore.persist as unknown as {
       getOptions: () => {
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
         merge: (
           persistedState: unknown,
           currentState: ReturnType<typeof useComposerDraftStore.getState>,
 @@ -396,9 +401,7 @@ describe("composerDraftStore file attachments", () => {
       };
     };
     const options = persistApi.getOptions();
-    const persisted = options.partialize(useComposerDraftStore.getState()) as {
+    const persisted = partializeComposerDraftStoreState(useComposerDraftStore.getState());
-      draftsByThreadKey: Record<string, { files?: Array<Record<string, unknown>> }>;
-    };
     expect(persisted.draftsByThreadKey[threadKeyFor(threadId, TEST_ENVIRONMENT_ID)]?.files).toEqual(
       [
 @@ -436,7 +439,6 @@ describe("composerDraftStore file attachments", () => {
     const persistApi = useComposerDraftStore.persist as unknown as {
       getOptions: () => {
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
         merge: (
           persistedState: unknown,
           currentState: ReturnType<typeof useComposerDraftStore.getState>,
 @@ -444,9 +446,7 @@ describe("composerDraftStore file attachments", () => {
       };
     };
     const options = persistApi.getOptions();
-    const persisted = options.partialize(useComposerDraftStore.getState()) as {
+    const persisted = partializeComposerDraftStoreState(useComposerDraftStore.getState());
-      draftsByThreadKey: Record<string, { files?: Array<Record<string, unknown>> }>;
-    };
     expect(persisted.draftsByThreadKey[threadKeyFor(threadId, TEST_ENVIRONMENT_ID)]?.files).toEqual(
       [
 @@ -835,12 +835,9 @@ describe("composerDraftStore terminal contexts", () => {
       .getState()
       .addTerminalContext(threadRef, makeTerminalContext({ id: "ctx-persist" }));
-    const persistApi = useComposerDraftStore.persist as unknown as {
+    const persistedState = partializeComposerDraftStoreState(
-      getOptions: () => {
+      useComposerDraftStore.getState(),
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
+    ) as unknown as {
-      };
-    };
-    const persistedState = persistApi.getOptions().partialize(useComposerDraftStore.getState()) as {
       draftsByThreadKey?: Record<string, { terminalContexts?: Array<Record<string, unknown>> }>;
     };
 @@ -1009,12 +1006,9 @@ describe("composerDraftStore element contexts", () => {
   it("persists element contexts via the partializer (round-trippable)", () => {
     useComposerDraftStore.getState().addElementContext(threadRef, baseSelection);
-    const persistApi = useComposerDraftStore.persist as unknown as {
+    const persisted = partializeComposerDraftStoreState(
-      getOptions: () => {
+      useComposerDraftStore.getState(),
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
+    ) as unknown as {
-      };
-    };
-    const persisted = persistApi.getOptions().partialize(useComposerDraftStore.getState()) as {
       draftsByThreadKey?: Record<string, { elementContexts?: Array<Record<string, unknown>> }>;
     };
     const entry =
 @@ -1067,12 +1061,9 @@ describe("composerDraftStore review comments", () => {
   it("persists review comments and clears them with composer content", () => {
     const store = useComposerDraftStore.getState();
     store.addReviewComment(threadRef, comment);
-    const persistApi = useComposerDraftStore.persist as unknown as {
+    const persisted = partializeComposerDraftStoreState(
-      getOptions: () => {
+      useComposerDraftStore.getState(),
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
+    ) as unknown as {
-      };
-    };
-    const persisted = persistApi.getOptions().partialize(useComposerDraftStore.getState()) as {
       draftsByThreadKey?: Record<string, { reviewComments?: Array<Record<string, unknown>> }>;
     };
 @@ -2517,7 +2508,7 @@ describe("composerDraftStore runtime and interaction settings", () => {
 });
 // ---------------------------------------------------------------------------
-// createDebouncedStorage
+// createDeferredStorage
 // ---------------------------------------------------------------------------
 function createMockStorage() {
 @@ -2533,9 +2524,75 @@ function createMockStorage() {
   };
 }
-describe("createDebouncedStorage", () => {
+describe("composer draft persistence", () => {
+  it("defers attachment reads and serialization until typing stops, then restores the last draft", async () => {
+    await useComposerDraftStore.persist.clearStorage();
+    vi.useFakeTimers();
+    const stringify = vi.spyOn(JSON, "stringify");
+    try {
+      resetComposerDraftStore();
+      const heavyThreadId = ThreadId.make("heavy-draft");
+      const typingThreadId = ThreadId.make("typing-draft");
+      const heavyRef = scopeThreadRef(TEST_ENVIRONMENT_ID, heavyThreadId);
+      const typingRef = scopeThreadRef(TEST_ENVIRONMENT_ID, typingThreadId);
+      const heavyKey = scopedThreadKey(heavyRef);
+      useComposerDraftStore.getState().setPrompt(heavyRef, "Keep this image");
+      const attachments = [
+        {
+          id: "heavy-image",
+          name: "image.png",
+          mimeType: "image/png",
+          sizeBytes: 49_152,
+          dataUrl: `data:image/png;base64,${"AQID".repeat(16_384)}`,
+        },
+      ];
+      let attachmentReads = 0;
+      useComposerDraftStore.setState((state) => ({
+        draftsByThreadKey: {
+          ...state.draftsByThreadKey,
+          [heavyKey]: {
+            ...state.draftsByThreadKey[heavyKey]!,
+            get persistedAttachments() {
+              attachmentReads += 1;
+              return attachments;
+            },
+          },
+        },
+      }));
+      attachmentReads = 0;
+      stringify.mockClear();
+      for (let index = 1; index <= 20; index++) {
+        useComposerDraftStore.getState().setPrompt(typingRef, `Draft ${index}`);
+      }
+      expect(attachmentReads).toBe(0);
+      expect(stringify).not.toHaveBeenCalled();
+      await vi.advanceTimersByTimeAsync(300);
+      expect(attachmentReads).toBe(1);
+      expect(stringify).toHaveBeenCalledTimes(1);
+      resetComposerDraftStore();
+      await useComposerDraftStore.persist.rehydrate();
+      expect(draftFor(typingThreadId, TEST_ENVIRONMENT_ID)?.prompt).toBe("Draft 20");
+      expect(draftFor(heavyThreadId, TEST_ENVIRONMENT_ID)?.persistedAttachments).toEqual(
+        attachments,
+      );
+    } finally {
+      stringify.mockRestore();
+      await useComposerDraftStore.persist.clearStorage();
+      vi.useRealTimers();
+      resetComposerDraftStore();
+    }
+  });
+});
+describe("createDeferredStorage", () => {
+  const serialize = vi.fn((value: string) => `s:${value}`);
   beforeEach(() => {
     vi.useFakeTimers();
+    serialize.mockClear();
   });
   afterEach(() => {
 @@ -2545,69 +2602,74 @@ describe("createDebouncedStorage", () => {
   it("delegates getItem immediately", () => {
     const base = createMockStorage();
     base.getItem.mockReturnValueOnce("value");
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
     expect(storage.getItem("key")).toBe("value");
     expect(base.getItem).toHaveBeenCalledWith("key");
   });
-  it("does not write to base storage until the debounce fires", () => {
+  it("neither serializes nor writes until the debounce fires", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
     storage.setItem("key", "v1");
+    expect(serialize).not.toHaveBeenCalled();
     expect(base.setItem).not.toHaveBeenCalled();
     vi.advanceTimersByTime(299);
+    expect(serialize).not.toHaveBeenCalled();
     expect(base.setItem).not.toHaveBeenCalled();
     vi.advanceTimersByTime(1);
-    expect(base.setItem).toHaveBeenCalledWith("key", "v1");
+    expect(base.setItem).toHaveBeenCalledWith("key", "s:v1");
   });
-  it("only writes the last value when setItem is called rapidly", () => {
+  it("serializes and writes only the last value when setItem is called rapidly", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
     storage.setItem("key", "v1");
     storage.setItem("key", "v2");
     storage.setItem("key", "v3");
     vi.advanceTimersByTime(300);
+    expect(serialize).toHaveBeenCalledTimes(1);
     expect(base.setItem).toHaveBeenCalledTimes(1);
-    expect(base.setItem).toHaveBeenCalledWith("key", "v3");
+    expect(base.setItem).toHaveBeenCalledWith("key", "s:v3");
   });
   it("removeItem cancels a pending setItem write", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
     storage.setItem("key", "v1");
     storage.removeItem("key");
     vi.advanceTimersByTime(300);
+    expect(serialize).not.toHaveBeenCalled();
     expect(base.setItem).not.toHaveBeenCalled();
     expect(base.removeItem).toHaveBeenCalledWith("key");
   });
-  it("flush writes the pending value immediately", () => {
+  it("flush serializes and writes the pending value immediately", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
     storage.setItem("key", "v1");
     expect(base.setItem).not.toHaveBeenCalled();
     storage.flush();
-    expect(base.setItem).toHaveBeenCalledWith("key", "v1");
+    expect(base.setItem).toHaveBeenCalledWith("key", "s:v1");
     // Timer should be cancelled; no duplicate write.
     vi.advanceTimersByTime(300);
+    expect(serialize).toHaveBeenCalledTimes(1);
     expect(base.setItem).toHaveBeenCalledTimes(1);
   });
   it("flush is a no-op when nothing is pending", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
     storage.flush();
     expect(base.setItem).not.toHaveBeenCalled();
 @@ -2615,7 +2677,7 @@ describe("createDebouncedStorage", () => {
   it("flush after removeItem is a no-op", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
     storage.setItem("key", "v1");
     storage.removeItem("key");
 @@ -2626,7 +2688,7 @@ describe("createDebouncedStorage", () => {
   it("setItem works normally after removeItem cancels a pending write", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
     storage.setItem("key", "v1");
     storage.removeItem("key");
 @@ -2634,6 +2696,6 @@ describe("createDebouncedStorage", () => {
     vi.advanceTimersByTime(300);
     expect(base.setItem).toHaveBeenCalledTimes(1);
-    expect(base.setItem).toHaveBeenCalledWith("key", "v2");
+    expect(base.setItem).toHaveBeenCalledWith("key", "s:v2");
   });
 });

apps/web/src/composerDraftStore.ts+36-6

 @@ -53,9 +53,9 @@ import {
   newElementContextId,
 } from "./lib/elementContext";
 import { create } from "zustand";
-import { createJSONStorage, persist } from "zustand/middleware";
+import { persist, type PersistStorage, type StorageValue } from "zustand/middleware";
 import { useShallow } from "zustand/react/shallow";
-import { createDebouncedStorage, createMemoryStorage } from "./lib/storage";
+import { createDeferredStorage, createMemoryStorage } from "./lib/storage";
 import { getDefaultServerModel } from "./providerModels";
 import { UnifiedSettings } from "@t3tools/contracts/settings";
 import { ReviewCommentContextSchema, type ReviewCommentContext } from "./reviewCommentContext";
 @@ -73,11 +73,39 @@ export type DraftId = typeof DraftId.Type;
 const COMPOSER_PERSIST_DEBOUNCE_MS = 300;
-const composerDebouncedStorage = createDebouncedStorage(
+// Keep the immutable state until flush. Migration writebacks already have the persisted shape.
+type ComposerPersistState =
+  | { capturedState: ComposerDraftStoreState }
+  | PersistedComposerDraftStoreState;
+const composerDebouncedStorage = createDeferredStorage<StorageValue<ComposerPersistState>>(
   typeof localStorage !== "undefined" ? localStorage : createMemoryStorage(),
+  (value) =>
+    JSON.stringify({
+      state:
+        "capturedState" in value.state
+          ? partializeComposerDraftStoreState(value.state.capturedState)
+          : value.state,
+      version: value.version,
+    }),
   COMPOSER_PERSIST_DEBOUNCE_MS,
 );
+const composerPersistStorage: PersistStorage<ComposerPersistState> = {
+  getItem: (name) => {
+    // The base storage is localStorage (or in-memory), which is synchronous.
+    const raw = composerDebouncedStorage.getItem(name);
+    if (typeof raw !== "string") {
+      return null;
+    }
+    // Parsed persisted JSON. `migrate` and `merge` normalize it from unknown,
+    // so the cast mirrors the one zustand's createJSONStorage performs.
+    return JSON.parse(raw) as StorageValue<ComposerPersistState>;
+  },
+  setItem: (name, value) => composerDebouncedStorage.setItem(name, value),
+  removeItem: (name) => composerDebouncedStorage.removeItem(name),
+};
 // Flush pending composer draft writes before page unload to prevent data loss.
 if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
   window.addEventListener("beforeunload", () => {
 @@ -2013,7 +2041,8 @@ function migratePersistedComposerDraftStoreState(
   };
 }
-function partializeComposerDraftStoreState(
+/** Select the persisted draft fields when the storage write is ready to flush. */
+export function partializeComposerDraftStoreState(
   state: ComposerDraftStoreState,
 ): PersistedComposerDraftStoreState {
   // Draft sessions worth persisting: mapped (a new-thread flow targets
 @@ -3876,9 +3905,10 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
     {
       name: COMPOSER_DRAFT_STORAGE_KEY,
       version: COMPOSER_DRAFT_STORAGE_VERSION,
-      storage: createJSONStorage(() => composerDebouncedStorage),
+      storage: composerPersistStorage,
       migrate: migratePersistedComposerDraftStoreState,
-      partialize: partializeComposerDraftStoreState,
+      // Defer the draft walk and serialization until the storage write flushes.
+      partialize: (state): ComposerPersistState => ({ capturedState: state }),
       merge: (persistedState, currentState) => {
         const normalizedPersisted =
           normalizeCurrentPersistedComposerDraftStoreState(persistedState);

apps/web/src/lib/storage.ts+12-5

 @@ -6,7 +6,10 @@ export interface StateStorage<R = unknown> {
   removeItem: (name: string) => R;
 }
-export interface DebouncedStorage<R = unknown> extends StateStorage<R> {
+export interface DeferredStorage<TValue> {
+  getItem: (name: string) => string | null | Promise<string | null>;
+  setItem: (name: string, value: TValue) => void;
+  removeItem: (name: string) => void;
   flush: () => void;
 }
 @@ -39,14 +42,16 @@ export function resolveStorage(storage: Partial<StateStorage> | null | undefined
   return isStateStorage(storage) ? storage : createMemoryStorage();
 }
-export function createDebouncedStorage(
+/** Keep the latest value and serialize it when the debounce fires or `flush` runs. */
+export function createDeferredStorage<TValue>(
   baseStorage: Partial<StateStorage> | null | undefined,
+  serialize: (value: TValue) => string,
   debounceMs: number = 300,
-): DebouncedStorage {
+): DeferredStorage<TValue> {
   const resolvedStorage = resolveStorage(baseStorage);
   const debouncedSetItem = new Debouncer(
-    (name: string, value: string) => {
+    (name: string, value: TValue) => {
-      resolvedStorage.setItem(name, value);
+      resolvedStorage.setItem(name, serialize(value));
     },
     { wait: debounceMs },
   );
 @@ -58,6 +63,8 @@ export function createDebouncedStorage(
     },
     removeItem: (name) => {
       debouncedSetItem.cancel();
+      // cancel() leaves the captured value in Pacer's lastArgs.
+      debouncedSetItem.reset();
       resolvedStorage.removeItem(name);
     },
     flush: () => {