Skip to content

Open source CapCut alternative.

TypeScript

fix(site): save note edits locally before syncing

David Le5eb8ade454c3
diff --git a/site/src/cut/components/NotesView.tsx b/site/src/cut/components/NotesView.tsx
index d1f0e93c..dc30d0e7 100644
--- a/site/src/cut/components/NotesView.tsx
+++ b/site/src/cut/components/NotesView.tsx
@@ -27,6 +27,7 @@ import {
} from "@/cut/lib/notes";
import { homeHref, useCutBase } from "@/cut/lib/nav";
import { CUT_NOTES } from "@/cut/lib/chatRuntime";
+import { dropPendingNote, stageNote, type NoteWrite } from "@/cut/lib/noteOutbox";
import { notesKey, patchNotes, useNotes } from "@/cut/lib/queries";
import { cn } from "@/lib/utils";
import { setObjectDragImage } from "@/cut/lib/assetDrag";
@@ -140,6 +141,17 @@ const draftOf = (n: CutNote): NoteDraft => ({
saved: { title: n.title, body: n.body, colorIndex: n.colorIndex, labelIds: n.labelIds },
});
+/** The draft's content as a write sends it. */
+const noteWrite = (d: NoteDraft): NoteWrite => ({
+ ...(d.libraryLocation !== undefined ? { libraryLocation: d.libraryLocation } : {}),
+ id: d.id,
+ title: d.title.trim(),
+ body: d.body.trimEnd(),
+ colorIndex: d.colorIndex,
+ folderId: d.folderId,
+ labelIds: d.labelIds,
+});
+
/** Synced notes: written on the phone or here, merged by last writer wins.
* The phone reads these into its teleprompter, so a script drafted at the
* desk is on the camera by the time the phone is in hand. Notes file into
@@ -412,6 +424,14 @@ export function NotesView({ library, ref }: Props = {}) {
};
const change = (d: NoteDraft) => {
edit(d);
+ // Every keystroke is saved in this browser at once, so a tab closed
+ // before the autosave still has the edit; the autosave sends it. A folder
+ // still being written waits for the autosave, which settles it first; a
+ // label still being written stays off until its write lands.
+ const folderOut = !!d.folderId && folderWrites.current.has(d.folderId);
+ if (noteChanged(d) && !folderOut) {
+ stageNote({ ...noteWrite(d), labelIds: d.labelIds.filter((id) => !labelWrites.current.has(id)) });
+ }
holdAutosave();
autosave.current = setTimeout(() => {
autosave.current = null;
@@ -438,6 +458,10 @@ export function NotesView({ library, ref }: Props = {}) {
};
const removeNotes = (ids: string[]) => {
const gone = new Set(ids);
+ // A pending edit sent on page hide would bring the note back.
+ for (const id of ids) {
+ dropPendingNote(id);
+ }
patchNotes(client, (prev) => ({
...prev,
notes: prev.notes.filter((n) => !gone.has(n.id)),
diff --git a/site/src/cut/components/RequireSession.tsx b/site/src/cut/components/RequireSession.tsx
index ee658a08..77151cf1 100644
--- a/site/src/cut/components/RequireSession.tsx
+++ b/site/src/cut/components/RequireSession.tsx
@@ -15,6 +15,7 @@ import {
import { reportExposures, useAppLoaded } from "@/lib/analytics";
import { authClient } from "@/lib/auth-client";
import { useAccountConfig } from "@/queries/accountConfig";
+import { useNoteOutboxSync } from "@/cut/hooks/useNoteOutboxSync";
// Session gate for the whole Cut app surface. The landing CTAs already route
// signed-out clicks through /sign-in (useAppEntryHref); this covers direct
@@ -25,6 +26,7 @@ import { useAccountConfig } from "@/queries/accountConfig";
// until the id lands, because every engine URL carries it.
export function RequireSession({ children }: { children: ReactNode }) {
const { data: session, isPending, refetch } = authClient.useSession();
+ useNoteOutboxSync();
const signedOut = !isPending && !session;
const userId = session?.user.id;
diff --git a/site/src/cut/hooks/useNoteOutboxSync.ts b/site/src/cut/hooks/useNoteOutboxSync.ts
new file mode 100644
index 00000000..7057936d
--- /dev/null
+++ b/site/src/cut/hooks/useNoteOutboxSync.ts
@@ -0,0 +1,31 @@
+"use client";
+
+import { useEffect } from "react";
+import { onEngineUserConfirmed } from "@/cut/lib/api";
+import { flushNoteOutbox } from "@/cut/lib/noteOutbox";
+
+/** Send pending note edits when a send may now land or must go now: the
+ * browser back online, the session confirming its account, and the page
+ * hiding or closing (as keepalive requests). Mounted once for the whole app. */
+export function useNoteOutboxSync(): void {
+ useEffect(() => {
+ const flush = () => void flushNoteOutbox();
+ const unload = () => void flushNoteOutbox("unloading");
+ const hidden = () => {
+ if (document.visibilityState === "hidden") {
+ unload();
+ }
+ };
+
+ window.addEventListener("online", flush);
+ window.addEventListener("pagehide", unload);
+ document.addEventListener("visibilitychange", hidden);
+ const offConfirmed = onEngineUserConfirmed(flush);
+ return () => {
+ window.removeEventListener("online", flush);
+ window.removeEventListener("pagehide", unload);
+ document.removeEventListener("visibilitychange", hidden);
+ offConfirmed();
+ };
+ }, []);
+}
diff --git a/site/src/cut/lib/noteOutbox.test.ts b/site/src/cut/lib/noteOutbox.test.ts
new file mode 100644
index 00000000..76f77225
--- /dev/null
+++ b/site/src/cut/lib/noteOutbox.test.ts
@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { confirmEngineUser, setEngineUser } from "./api";
+import { bindCutMode, releaseCutMode } from "./backend";
+import { flushNoteOutbox } from "./noteOutbox";
+import { deleteNote, fetchNotes, saveNote, type CutNote } from "./notes";
+
+// A note edit is saved in this browser before it is sent, so a server that
+// is down or a tab that closes mid-edit never loses the words.
+
+const storage = new Map<string, string>();
+const originalFetch = globalThis.fetch;
+
+// What the stub server holds, and whether it is answering.
+let server = new Map<string, CutNote>();
+let up = true;
+let refuse = false;
+const puts: string[] = [];
+
+const pendingKeys = () => [...storage.keys()].filter((k) => k.startsWith("cut:note-outbox:"));
+const write = (id: string, body = "Draft") => ({ id, title: "Script", body, colorIndex: 0, folderId: null, labelIds: [] });
+
+beforeEach(() => {
+ storage.clear();
+ server = new Map();
+ up = true;
+ refuse = false;
+ puts.length = 0;
+ Object.assign(globalThis, {
+ localStorage: {
+ getItem: (key: string) => storage.get(key) ?? null,
+ setItem: (key: string, value: string) => void storage.set(key, value),
+ removeItem: (key: string) => void storage.delete(key),
+ get length() {
+ return storage.size;
+ },
+ key: (i: number) => [...storage.keys()][i] ?? null,
+ },
+ });
+ globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+ if (!up) {
+ throw new TypeError("Failed to fetch");
+ }
+ const url = new URL(String(input), "https://example.test");
+ const id = decodeURIComponent(url.pathname.split("/").pop() ?? "");
+ if (init?.method === "PUT") {
+ if (refuse) {
+ return new Response("", { status: 400 });
+ }
+ const body = JSON.parse(String(init.body)) as CutNote;
+ puts.push(body.body);
+ const held = server.get(id);
+ const kept = held && held.updatedAt > body.updatedAt ? held : { ...body, deletedAt: null, createdAt: 1 };
+ server.set(id, kept);
+ return Response.json(kept);
+ }
+ if (init?.method === "DELETE") {
+ server.delete(id);
+ return Response.json({ ok: true });
+ }
+ return Response.json({ notes: [...server.values()], folders: [], labels: [] });
+ }) as typeof fetch;
+ bindCutMode("cloud");
+});
+afterEach(() => {
+ globalThis.fetch = originalFetch;
+ releaseCutMode();
+});
+
+describe("a process with no account bound", () => {
+ test("sends straight through and keeps nothing behind", async () => {
+ const saved = await saveNote(write("n0", "From the worker"));
+ expect(saved.body).toBe("From the worker");
+ expect(pendingKeys()).toEqual([]);
+ });
+});
+
+describe("a signed-in browser", () => {
+ beforeEach(() => confirmEngineUser("owner"));
+
+ test("an edit made while the server is down is kept and synced later", async () => {
+ up = false;
+ const saved = await saveNote(write("n1", "Offline words"));
+ expect(saved.body).toBe("Offline words");
+
+ // Reopened before the server is back: the list still shows the edit.
+ up = true;
+ server.set("n1", { ...write("n1", "Old words"), updatedAt: 1, deletedAt: null, createdAt: 1 });
+ const listed = await fetchNotes();
+ expect(listed.notes.find((n) => n.id === "n1")?.body).toBe("Offline words");
+
+ await flushNoteOutbox();
+ expect(server.get("n1")?.body).toBe("Offline words");
+ expect(pendingKeys()).toEqual([]);
+ });
+
+ test("a newer edit from the phone wins over a pending one", async () => {
+ up = false;
+ await saveNote(write("n2", "Desk"));
+ up = true;
+ server.set("n2", { ...write("n2", "Phone"), updatedAt: Date.now() + 60_000, deletedAt: null, createdAt: 1 });
+ const listed = await fetchNotes();
+ expect(listed.notes.find((n) => n.id === "n2")?.body).toBe("Phone");
+ expect(pendingKeys()).toEqual([]);
+ });
+
+ test("a write the server refuses leaves the outbox and says so", async () => {
+ refuse = true;
+ await expect(saveNote(write("n3"))).rejects.toThrow("Could not save the note.");
+ expect(pendingKeys()).toEqual([]);
+ });
+
+ test("full storage still saves, and syncs from memory", async () => {
+ up = false;
+ const setItem = localStorage.setItem;
+ localStorage.setItem = () => {
+ throw new DOMException("full", "QuotaExceededError");
+ };
+ try {
+ expect((await saveNote(write("n6", "Kept in memory"))).body).toBe("Kept in memory");
+ } finally {
+ localStorage.setItem = setItem;
+ }
+ up = true;
+ await flushNoteOutbox();
+ expect(server.get("n6")?.body).toBe("Kept in memory");
+ });
+
+ test("deleting a note drops its pending edit", async () => {
+ up = false;
+ await saveNote(write("n4"));
+ up = true;
+ await deleteNote("n4");
+ await flushNoteOutbox();
+ expect(server.has("n4")).toBe(false);
+ expect(puts).toEqual([]);
+ });
+
+ test("an account the session has not confirmed sends nothing", async () => {
+ up = false;
+ await saveNote(write("n5", "Owner's words"));
+ up = true;
+ setEngineUser("visitor");
+ await flushNoteOutbox();
+ expect(puts).toEqual([]);
+ expect((await fetchNotes()).notes.some((n) => n.id === "n5")).toBe(false);
+
+ confirmEngineUser("owner");
+ await flushNoteOutbox();
+ expect(server.get("n5")?.body).toBe("Owner's words");
+ });
+});
diff --git a/site/src/cut/lib/noteOutbox.ts b/site/src/cut/lib/noteOutbox.ts
new file mode 100644
index 00000000..6327ecb8
--- /dev/null
+++ b/site/src/cut/lib/noteOutbox.ts
@@ -0,0 +1,262 @@
+"use client";
+
+/**
+ * Note edits are saved in this browser first and synced to the cloud after.
+ *
+ * Every edit lands in localStorage at once, synchronously, stamped with the
+ * moment it was made. A flush sends what is pending, and an entry leaves the
+ * outbox only once the server has answered for it. A failed send stays
+ * pending and is retried with backoff; the page also flushes when it comes
+ * back online, when the session confirms its account, and as a keepalive
+ * request when it is hidden (useNoteOutboxSync). Anything those miss syncs
+ * the next time the notes are listed.
+ *
+ * The stamp is the edit's own, so a write that syncs late still loses to a
+ * newer edit from the phone: the server keeps whichever stamp is newer.
+ * Entries are kept per account and sent only for the confirmed account, so
+ * two people sharing a browser never write each other's notes. A process with
+ * no account bound — the cloud worker, whose transport carries the user —
+ * keeps no outbox: its writes go straight to the server and fail when the
+ * server does.
+ */
+
+import { confirmedEngineUser, currentEngineUser } from "./api";
+import type { NoteLocation } from "./noteReference";
+import { backendFor } from "./residency";
+import type { CutNote } from "./notes";
+
+/** One note as a write sends it. */
+export interface NoteWrite {
+ libraryLocation?: NoteLocation | null;
+ id: string;
+ title: string;
+ body: string;
+ colorIndex: number;
+ folderId: string | null;
+ labelIds: string[];
+}
+
+interface Pending {
+ note: NoteWrite;
+ updatedAt: number;
+}
+
+/** How a send goes out: "unloading" rides a keepalive request so it can
+ * outlive a closing page. */
+export type SendMode = "now" | "unloading";
+
+const OUTBOX_PREFIX = "cut:note-outbox:";
+
+/** Waits between retries of a send the server did not take, longest last. */
+const RETRY_MS = [2_000, 10_000, 30_000, 120_000];
+
+/** A keepalive request carries at most 64 KB. */
+const KEEPALIVE_MAX_BYTES = 60_000;
+
+// Answers that mean the write may land later: signed out, a timeout, a rate
+// limit, or the server failing. Any other refusal is the write itself.
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_TIMEOUT = 408;
+const HTTP_TOO_MANY = 429;
+const HTTP_SERVER_ERROR = 500;
+const retryable = (status: number) =>
+ status === HTTP_UNAUTHORIZED || status === HTTP_TIMEOUT || status === HTTP_TOO_MANY || status >= HTTP_SERVER_ERROR;
+
+// One key per note, so a keystroke rewrites only the note being typed.
+const keyOf = (account: string, id: string) => `${OUTBOX_PREFIX}${account}:${id}`;
+
+// Entries whose storage write failed — storage full or blocked — held for
+// this session. A held entry is newer than whatever storage still has.
+const memory = new Map<string, Pending>();
+
+function readPending(account: string, id: string): Pending | undefined {
+ const key = keyOf(account, id);
+ const held = memory.get(key);
+ if (held) {
+ return held;
+ }
+ try {
+ const raw = localStorage.getItem(key);
+ return raw ? (JSON.parse(raw) as Pending) : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+function writePending(account: string, id: string, pending: Pending | null): void {
+ const key = keyOf(account, id);
+ memory.delete(key);
+ try {
+ if (pending) {
+ localStorage.setItem(key, JSON.stringify(pending));
+ } else {
+ localStorage.removeItem(key);
+ }
+ } catch {
+ if (pending) {
+ memory.set(key, pending);
+ }
+ }
+}
+
+function pendingIds(account: string): string[] {
+ const prefix = `${OUTBOX_PREFIX}${account}:`;
+ const keys = new Set([...memory.keys()].filter((k) => k.startsWith(prefix)));
+ try {
+ for (let i = 0; i < localStorage.length; i++) {
+ const key = localStorage.key(i);
+ if (key?.startsWith(prefix)) {
+ keys.add(key);
+ }
+ }
+ } catch {
+ // Blocked storage lists the held entries alone.
+ }
+ return [...keys].map((k) => k.slice(prefix.length));
+}
+
+/** A pending write as the list shows it until the server answers. */
+const localNote = (p: Pending, over?: CutNote): CutNote => ({
+ libraryLocation: over?.libraryLocation ?? null,
+ ...p.note,
+ updatedAt: p.updatedAt,
+ deletedAt: null,
+ createdAt: over?.createdAt ?? p.updatedAt,
+});
+
+/** Save a note's current content in this browser, stamped now. False when no
+ * account is bound, so there is no outbox to hold it. */
+export function stageNote(note: NoteWrite): boolean {
+ const account = currentEngineUser();
+ if (!account) {
+ return false;
+ }
+ writePending(account, note.id, { note, updatedAt: Date.now() });
+ return true;
+}
+
+/** Forget a note's pending write: the note was deleted. */
+export function dropPendingNote(id: string): void {
+ const account = currentEngineUser();
+ if (account) {
+ writePending(account, id, null);
+ }
+}
+
+/** The server's list with this browser's pending writes laid over it. A
+ * pending write the server already holds, or holds something newer than,
+ * leaves the outbox here. */
+export function withPendingNotes(serverNotes: CutNote[]): CutNote[] {
+ const account = currentEngineUser();
+ const ids = account ? pendingIds(account) : [];
+ if (!account || ids.length === 0) {
+ return serverNotes;
+ }
+
+ // Lay each pending write over the server's copy, or drop it when the
+ // server's copy is as new: e.g. an edit sent by keepalive as the tab closed.
+ const byId = new Map(serverNotes.map((n) => [n.id, n]));
+ let left = 0;
+ for (const id of ids) {
+ const pending = readPending(account, id);
+ if (!pending) {
+ continue;
+ }
+ const server = byId.get(id);
+ if (server && server.updatedAt >= pending.updatedAt) {
+ writePending(account, id, null);
+ continue;
+ }
+ byId.set(id, localNote(pending, server));
+ left++;
+ }
+ if (left > 0) {
+ void flushNoteOutbox();
+ }
+ return [...byId.values()].sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+type Sent = { kind: "landed"; note: CutNote } | { kind: "held" } | { kind: "refused" };
+
+async function send(note: NoteWrite, updatedAt: number, mode: SendMode): Promise<Sent> {
+ const body = JSON.stringify({ ...note, updatedAt });
+ const res = await backendFor("cloud")
+ .fetch(`/api/cut/notes/${encodeURIComponent(note.id)}`, {
+ method: "PUT",
+ headers: { "Content-Type": "application/json" },
+ body,
+ keepalive: mode === "unloading" && body.length < KEEPALIVE_MAX_BYTES,
+ })
+ .catch(() => null);
+ if (!res) {
+ return { kind: "held" };
+ }
+ if (res.ok) {
+ return { kind: "landed", note: (await res.json()) as CutNote };
+ }
+ return retryable(res.status) ? { kind: "held" } : { kind: "refused" };
+}
+
+/** Write a note with no outbox behind it: the server's answer, or an error. */
+export async function sendNoteNow(note: NoteWrite): Promise<CutNote> {
+ const sent = await send(note, Date.now(), "now");
+ if (sent.kind !== "landed") {
+ throw new Error("Could not save the note.");
+ }
+ return sent.note;
+}
+
+/** Send one note's pending write. Answers with the version the server kept,
+ * or with the pending write itself while it waits to sync. A write the server
+ * refuses outright leaves the outbox and throws. */
+export async function flushNote(id: string, mode: SendMode = "now"): Promise<CutNote | null> {
+ const account = currentEngineUser();
+ const pending = account ? readPending(account, id) : undefined;
+ if (!account || !pending) {
+ return null;
+ }
+ // Sent once the live session confirms this is still the account signed in.
+ if (account !== confirmedEngineUser()) {
+ return localNote(pending);
+ }
+
+ const sent = await send(pending.note, pending.updatedAt, mode);
+ if (sent.kind === "held") {
+ scheduleRetry();
+ return localNote(pending);
+ }
+
+ // Off the outbox only if no newer edit was staged while this one was out.
+ if (readPending(account, id)?.updatedAt === pending.updatedAt) {
+ writePending(account, id, null);
+ }
+ if (sent.kind === "refused") {
+ throw new Error("Could not save the note.");
+ }
+ retryStep = 0;
+ return sent.note;
+}
+
+/** Send every pending write for the signed-in account. */
+export async function flushNoteOutbox(mode: SendMode = "now"): Promise<void> {
+ const account = confirmedEngineUser();
+ if (!account) {
+ return;
+ }
+ await Promise.all(pendingIds(account).map((id) => flushNote(id, mode).catch(() => null)));
+}
+
+let retryTimer: ReturnType<typeof setTimeout> | null = null;
+let retryStep = 0;
+
+function scheduleRetry(): void {
+ if (retryTimer) {
+ return;
+ }
+ const wait = RETRY_MS[Math.min(retryStep, RETRY_MS.length - 1)];
+ retryStep++;
+ retryTimer = setTimeout(() => {
+ retryTimer = null;
+ void flushNoteOutbox();
+ }, wait);
+}
diff --git a/site/src/cut/lib/notes.ts b/site/src/cut/lib/notes.ts
index 84d7b767..e96b6905 100644
--- a/site/src/cut/lib/notes.ts
+++ b/site/src/cut/lib/notes.ts
@@ -14,6 +14,7 @@
import { noteReadSchema, noteSaveSchema, parseNoteLink, type NoteLocation } from "@/cut/lib/noteReference";
import { settleParents } from "./folderTree";
+import { dropPendingNote, flushNote, sendNoteNow, stageNote, withPendingNotes, type NoteWrite } from "./noteOutbox";
import { backendFor } from "./residency";
export { folderTrail, folderWithin, subtreeOf } from "./folderTree";
@@ -86,7 +87,7 @@ export async function fetchNotes(): Promise<NotesData> {
if (!res.ok) throw new Error("Could not load notes.");
const body = (await res.json()) as Partial<NotesData>;
return {
- notes: (body.notes ?? []).filter((n) => n.deletedAt === null),
+ notes: withPendingNotes(body.notes ?? []).filter((n) => n.deletedAt === null),
folders: settleParents(body.folders ?? []),
labels: body.labels ?? [],
};
@@ -111,26 +112,21 @@ export async function writeNoteFromTool(raw: unknown): Promise<CutNote> {
...(prior ? {} : { libraryLocation: null }), ...changes });
}
-/** Write one note. The server answers with the winning version — this write,
- * or a newer one from the phone. */
-export async function saveNote(note: {
- libraryLocation?: NoteLocation | null;
- id: string;
- title: string;
- body: string;
- colorIndex: number;
- folderId: string | null;
- labelIds: string[];
-}): Promise<CutNote> {
- const res = await notesFetch(
- `/api/cut/notes/${encodeURIComponent(note.id)}`,
- json({ ...note, updatedAt: Date.now() }),
- );
- if (!res.ok) throw new Error("Could not save the note.");
- return (await res.json()) as CutNote;
+/** Write one note: saved in this browser at once, then sent. The answer is
+ * the winning version — this write, or a newer one from the phone — or this
+ * write itself while it waits to sync. With no account bound there is no
+ * outbox, and the write goes straight to the server. */
+export async function saveNote(note: NoteWrite): Promise<CutNote> {
+ if (!stageNote(note)) {
+ return sendNoteNow(note);
+ }
+ const saved = await flushNote(note.id);
+ if (!saved) throw new Error("Could not save the note.");
+ return saved;
}
export async function deleteNote(id: string): Promise<void> {
+ dropPendingNote(id);
const res = await notesFetch(`/api/cut/notes/${encodeURIComponent(id)}`, {
method: "DELETE",
});