Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(sdk): drain pending saves and adapter storage on flush (#5285)
Abdullah M. Nazif8efd9ca52326
diff --git a/docs/sdk/reference/utilities.mdx b/docs/sdk/reference/utilities.mdxindex 88144b32f9..a4cbea42ed 100644--- a/docs/sdk/reference/utilities.mdx+++ b/docs/sdk/reference/utilities.mdx@@ -162,7 +162,7 @@ interface PersistQueueModule {```<ParamField path="flush" type="() => Promise<void>">- Cancels any pending debounced write and immediately writes the current serialized HTML to the adapter. Resolves when the write commits. Use before app close or page unload.+ Immediately saves any pending edit, waits for in-flight saves, and flushes the adapter's storage before resolving. With no pending edit, it flushes storage without writing another version. Use before app close or page unload.</ParamField><ParamField path="dispose" type="() => void">@@ -183,7 +183,7 @@ interface PersistQueueOptions {</ParamField><ParamField path="onError" type="(e: PersistErrorEvent) => void">- Called when `adapter.write()` rejects. Receives a `PersistErrorEvent` with `{ error: { message, cause? } }`. Use this to surface persistence failures in your UI or logging layer.+ Called when `adapter.write()` or `adapter.flush()` rejects. Receives a `PersistErrorEvent` with `{ error: { message, cause? } }`. Use this to surface persistence failures in your UI or logging layer.</ParamField>---diff --git a/packages/sdk/src/persist-queue.ts b/packages/sdk/src/persist-queue.tsindex d8b9d8a7f9..b16598716b 100644--- a/packages/sdk/src/persist-queue.ts+++ b/packages/sdk/src/persist-queue.ts@@ -12,7 +12,7 @@ import type { Composition, PersistErrorEvent } from "./types.js";import type { PersistAdapter } from "./adapters/types.js";export interface PersistQueueModule {- /** Force an immediate write (e.g. before app close). */+ /** Drain pending writes and adapter storage before app close. */flush(): Promise<void>;dispose(): void;}@@ -20,7 +20,7 @@ export interface PersistQueueModule {export interface PersistQueueOptions {/** Adapter path to write to. Default: "composition.html" */path?: string;- /** Called when adapter.write() rejects. */+ /** Called when adapter.write() or adapter.flush() rejects. */onError?: (e: PersistErrorEvent) => void;}@@ -63,12 +63,22 @@ export function createPersistQueue(});return {- async flush(): Promise<void> {+ flush(): Promise<void> {+ if (disposed) return writeChain;if (pendingWrite !== null) {clearTimeout(pendingWrite);pendingWrite = null;+ void doWrite();}- await doWrite();+ writeChain = writeChain.then(async () => {+ try {+ await adapter.flush();+ } catch (err) {+ const message = err instanceof Error ? err.message : String(err);+ opts.onError?.({ error: { message, cause: err } });+ }+ });+ return writeChain;},dispose(): void {diff --git a/packages/sdk/src/smoke.test.ts b/packages/sdk/src/smoke.test.tsindex 9292826165..6b2a0e6837 100644--- a/packages/sdk/src/smoke.test.ts+++ b/packages/sdk/src/smoke.test.ts@@ -9,7 +9,7 @@* If it breaks, the SDK's public contract has changed.*/-import { describe, it, expect, vi } from "vitest";+import { describe, it, expect, vi, afterEach } from "vitest";import {openComposition,ORIGIN_APPLY_PATCHES,@@ -221,6 +221,142 @@ describe("undo / redo", () => {// ─── persist adapter ─────────────────────────────────────────────────────────describe("persist adapter", () => {+ function deferredSave() {+ const adapter = createMemoryAdapter();+ let release = () => {};+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ return { adapter, write: adapter.write.bind(adapter), gate, release: () => release() };+ }++ afterEach(() => {+ vi.useRealTimers();+ });++ it("flushes storage without writing a new version when no edit is pending", async () => {+ const adapter = createMemoryAdapter();+ const writeSpy = vi.spyOn(adapter, "write");+ const flushSpy = vi.spyOn(adapter, "flush");+ const comp = await openComposition(BASE_HTML, { persist: adapter });++ await comp.flush();+ expect(writeSpy).not.toHaveBeenCalled();+ expect(flushSpy).toHaveBeenCalledOnce();+ expect(await adapter.listVersions("composition.html")).toEqual([]);+ comp.dispose();+ });++ it("does not duplicate a saved edit on repeated flushes", async () => {+ const adapter = createMemoryAdapter();+ const writeSpy = vi.spyOn(adapter, "write");+ const comp = await openComposition(BASE_HTML, { persist: adapter });+ comp.setText("hf-title", "Saved once");++ await comp.flush();+ await comp.flush();+ await comp.flush();+ expect(writeSpy).toHaveBeenCalledOnce();+ expect(await adapter.listVersions("composition.html")).toHaveLength(1);+ comp.dispose();+ });++ it("commits an adapter's buffered save before flush resolves", async () => {+ const adapter = createMemoryAdapter();+ const write = adapter.write.bind(adapter);+ const pending: Array<{ path: string; content: string }> = [];+ vi.spyOn(adapter, "write").mockImplementation(async (path, content) => {+ pending.push({ path, content });+ });+ const flushSpy = vi.spyOn(adapter, "flush").mockImplementation(async () => {+ for (const save of pending.splice(0)) await write(save.path, save.content);+ });+ const comp = await openComposition(BASE_HTML, { persist: adapter });+ comp.setText("hf-title", "Durably saved");++ await comp.flush();+ expect(flushSpy).toHaveBeenCalledOnce();+ expect(pending).toEqual([]);+ expect(await adapter.read("composition.html")).toContain("Durably saved");+ comp.dispose();+ });++ it("waits for an in-flight autosave without queuing another copy", async () => {+ vi.useFakeTimers();+ const { adapter, write, gate, release } = deferredSave();+ const writeSpy = vi.spyOn(adapter, "write").mockImplementation(async (path, content) => {+ await gate;+ await write(path, content);+ });+ const flushSpy = vi.spyOn(adapter, "flush");+ const comp = await openComposition(BASE_HTML, { persist: adapter });+ comp.setText("hf-title", "In flight");+ await vi.advanceTimersByTimeAsync(0);++ let settled = false;+ const flushing = comp.flush().then(() => {+ settled = true;+ });+ await Promise.resolve();+ expect(settled).toBe(false);+ expect(flushSpy).not.toHaveBeenCalled();+ release();+ await flushing;+ expect(writeSpy).toHaveBeenCalledOnce();+ expect(flushSpy).toHaveBeenCalledOnce();+ expect(await adapter.read("composition.html")).toContain("In flight");+ comp.dispose();+ });++ it("keeps adapter flushes and later saves in order", async () => {+ vi.useFakeTimers();+ const { adapter, write, gate, release } = deferredSave();+ const events: string[] = [];+ vi.spyOn(adapter, "write").mockImplementation(async (path, content) => {+ events.push(content.includes("First edit") ? "write:first" : "write:second");+ await write(path, content);+ });+ vi.spyOn(adapter, "flush").mockImplementationOnce(async () => {+ events.push("flush:start");+ await gate;+ events.push("flush:end");+ });+ const comp = await openComposition(BASE_HTML, { persist: adapter });+ comp.setText("hf-title", "First edit");+ const first = comp.flush();+ await vi.advanceTimersByTimeAsync(0);+ expect(events).toEqual(["write:first", "flush:start"]);++ comp.setText("hf-title", "Second edit");+ const second = comp.flush();+ await vi.advanceTimersByTimeAsync(0);+ expect(events).toEqual(["write:first", "flush:start"]);+ release();+ await Promise.all([first, second]);+ expect(events).toEqual(["write:first", "flush:start", "flush:end", "write:second"]);+ expect(await adapter.read("composition.html")).toContain("Second edit");+ comp.dispose();+ });++ it("reports an adapter flush failure and permits the next save", async () => {+ const adapter = createMemoryAdapter();+ vi.spyOn(adapter, "flush").mockRejectedValueOnce(new Error("storage unavailable"));+ const comp = await openComposition(BASE_HTML, { persist: adapter });+ const onError = vi.fn();+ comp.on("persist:error", onError);+ comp.setText("hf-title", "First save");++ await expect(comp.flush()).resolves.toBeUndefined();+ expect(onError).toHaveBeenCalledWith({+ error: { message: "storage unavailable", cause: expect.any(Error) },+ });+ comp.setText("hf-title", "Recovered save");+ await comp.flush();+ expect(await adapter.read("composition.html")).toContain("Recovered save");+ expect(onError).toHaveBeenCalledOnce();+ comp.dispose();+ });+it("writes serialized HTML to the adapter on mutation", async () => {const adapter = createMemoryAdapter();const writeSpy = vi.spyOn(adapter, "write");