Open source CapCut alternative.
TypeScript
feat(site): cloud video caches as the byte ranges it reads [rebuild]
David Lecec8d6122a72
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.mdindex e5053106..946bf188 100644--- a/docs/guides/cut/README.md+++ b/docs/guides/cut/README.md@@ -74,7 +74,7 @@ Cloud projects store their doc in Postgres (versioned; a stale autosave 409s andA dropped file does not wait for that upload. Because a presign claims the stored name before any bytes move, and the browser can read the file it was handed, an import is measured, named, and placed on the timeline in the same moment it is dropped — playing from the local copy, filmstrip and all — while the bytes go out behind the editor. When this browser can hold a store, the dropped bytes are written into origin-private storage under the claimed name and pinned: the document references the asset at once, a tab closed mid-upload resumes the upload on the next open, and once the cloud confirms the object the pin clears and the local file becomes a read cache. A tab-scoped import — a browser with no store — keeps itself honest through the saved document instead: the import stays out of it, along with the clips that use it, until the upload lands, so a tab closed mid-upload leaves nothing to reopen broken. Export waits on the same line, since a render reads the saved document.-The cache runs the other way too: opening a cloud project prefetches every asset this browser is missing — one file at a time, nearest timeline use first — and each file that lands swaps the playing asset onto its local bytes, so scrubbing goes local as the queue drains and the next open plays entirely from disk. When the origin's storage quota runs short, the least recently opened projects' caches are dropped to make room; pinned uploads and browser-resident projects are never evicted, so losing a cache only costs a re-download.+The cache runs the other way too: opening a cloud project pulls in the assets this browser is missing, nearest timeline use first. Video caches as fixed-size chunks keyed to the stored object: playback serves the pieces it holds from disk and fetches the rest as byte ranges, so scrubbing warms the exact regions being worked, a half-fetched file keeps every chunk that landed, and the cache carries across the hourly re-signing of media links. Images and audio stream in whole and swap onto local bytes as they land. When the origin's storage quota runs short, chunked video goes first — a lost chunk costs one ranged re-fetch — then the least recently opened projects' whole-file caches; pinned uploads and browser-resident projects are never evicted.Storage a subscription paid for outlives the subscription for a while: when Pro ends and the account still holds more than the free tier, it keeps everything for thirty days, warned in the editor and on the projects home. After that the daily sweep brings it back under the cap — least-recently-updated projects first, then the oldest library assets, stopping the moment it fits — so what survives is the recent work, and an account already under the cap is never touched.diff --git a/site/src/cut/lib/backend/browser/opfs.ts b/site/src/cut/lib/backend/browser/opfs.tsindex 29ef080a..e8d3ea3d 100644--- a/site/src/cut/lib/backend/browser/opfs.ts+++ b/site/src/cut/lib/backend/browser/opfs.ts@@ -49,6 +49,9 @@ const userParts = () => [ROOT_DIR, "users", accountId()];const projectParts = (id: string) => [...userParts(), "projects", id];export const projectsDir = (create = false) => dirAt([...userParts(), "projects"], create);+/** The chunk cache (lib/chunkCache.ts): partial copies of cloud media, one+ * directory per object holding fixed-size byte chunks and a meta.json. */+export const chunksDir = (create = false) => dirAt([...userParts(), "chunks"], create);export const projectDir = (id: string, create = false) => dirAt(projectParts(id), create);export const mediaDir = (id: string, create = false) => dirAt([...projectParts(id), "media"], create);export const exportsDir = (id: string, create = false) =>diff --git a/site/src/cut/lib/chunkCache.test.ts b/site/src/cut/lib/chunkCache.test.tsnew file mode 100644index 00000000..e0b16862--- /dev/null+++ b/site/src/cut/lib/chunkCache.test.ts@@ -0,0 +1,101 @@+import { describe, expect, test } from "bun:test";+import {+ CHUNK_SIZE,+ chunkIdentity,+ chunkRuns,+ decodeResident,+ encodeResident,+} from "./chunkCache";++const signed = (path: string, query = "e=123&s=abc") =>+ `https://media.donkeycut.com${path}?${query}`;++describe("chunkIdentity", () => {+ test("keys on the decoded path and drops the auth query", () => {+ const a = chunkIdentity(signed("/cut/u1/projects/p1/media/clip%201.mp4", "e=1&s=x"));+ const b = chunkIdentity(signed("/cut/u1/projects/p1/media/clip%201.mp4", "e=2&s=y"));+ expect(a?.key).toBe("/cut/u1/projects/p1/media/clip 1.mp4");+ expect(a?.keyHash).toBe(b!.keyHash);+ expect(a?.versionTag).toBe(b!.versionTag);+ });++ test("two versions of one object share a key and split on directory", () => {+ const a = chunkIdentity(signed("/cut/u1/projects/p1/preview.mp4", "e=1&s=x&v=100"));+ const b = chunkIdentity(signed("/cut/u1/projects/p1/preview.mp4", "e=1&s=x&v=200"));+ expect(a?.keyHash).toBe(b!.keyHash);+ expect(a?.versionTag).not.toBe(b!.versionTag);+ });++ test("an unversioned URL still lands somewhere stable", () => {+ const a = chunkIdentity(signed("/cut/u1/library/a.mp4", "e=1&s=x"));+ const b = chunkIdentity(signed("/cut/u1/library/a.mp4", "e=9&s=z"));+ expect(a?.version).toBe("");+ expect(a?.versionTag).toBe(b!.versionTag);+ });++ test("answers null off the media origin", () => {+ expect(chunkIdentity("https://example.com/cut/u1/library/a.mp4?e=1&s=x")).toBe(null);+ expect(chunkIdentity("http://localhost:41417/api/cut/projects/p/media/a.mp4")).toBe(null);+ expect(chunkIdentity("blob:https://donkeycut.com/xyz")).toBe(null);+ expect(chunkIdentity("not a url")).toBe(null);+ });++ test("answers null for tree-token paths", () => {+ expect(chunkIdentity(signed("/_t/123/2/sig/cut/u1/hls/master.m3u8"))).toBe(null);+ });++ test("distinct keys land in distinct directories", () => {+ const a = chunkIdentity(signed("/cut/u1/projects/p1/media/a.mp4"));+ const b = chunkIdentity(signed("/cut/u1/projects/p1/media/b.mp4"));+ expect(a?.keyHash).not.toBe(b?.keyHash);+ expect(/^[0-9a-f]{16}$/.test(a?.keyHash ?? "")).toBe(true);+ expect(/^[0-9a-f]{8}$/.test(a?.versionTag ?? "")).toBe(true);+ });+});++describe("chunkRuns", () => {+ test("groups consecutive indices into runs", () => {+ expect(chunkRuns([0, 1, 2, 5, 6, 9], 8)).toEqual([+ [0, 2],+ [5, 6],+ [9, 9],+ ]);+ });++ test("splits a long stretch at the cap", () => {+ expect(chunkRuns([0, 1, 2, 3, 4], 2)).toEqual([+ [0, 1],+ [2, 3],+ [4, 4],+ ]);+ });++ test("empty in, empty out", () => {+ expect(chunkRuns([], 8)).toEqual([]);+ });+});++describe("resident bitmap", () => {+ test("round-trips a sparse set", () => {+ const set = new Set([0, 1, 7, 8, 63, 100, 2999]);+ expect(decodeResident(encodeResident(set, 3000), 3000)).toEqual(set);+ });++ test("stays small for a long file", () => {+ const every = Array.from({ length: 3000 }, (_, i) => i);+ // A 6GB source is 3000 chunks; the map has to be cheap enough to write+ // beside the chunks rather than rescanning the directory on every open.+ expect(encodeResident(every, 3000).length).toBeLessThan(600);+ });++ test("drops indices past the count and survives junk", () => {+ expect(decodeResident(encodeResident([0, 5, 99], 8), 8)).toEqual(new Set([0, 5]));+ expect(decodeResident("!!not base64!!", 16).size).toBe(0);+ expect(decodeResident("", 16).size).toBe(0);+ });+});++test("chunk size divides the byte math cleanly", () => {+ expect(CHUNK_SIZE).toBe(2 * 1024 * 1024);+ expect(Number.isInteger(CHUNK_SIZE)).toBe(true);+});diff --git a/site/src/cut/lib/chunkCache.ts b/site/src/cut/lib/chunkCache.tsnew file mode 100644index 00000000..9151a197--- /dev/null+++ b/site/src/cut/lib/chunkCache.ts@@ -0,0 +1,780 @@+"use client";++/**+ * Cloud media as resident byte ranges.+ *+ * A cloud video used to become local all at once: the prefetch streamed the+ * whole file into OPFS and playback rode signed URLs until the last byte+ * landed. This module makes residency a property of 2MB chunks. A decoder's+ * read serves resident chunks off disk, fetches the missing ones as ranged+ * requests, and writes what arrives — so the second scrub over a region is a+ * disk read, an interrupted prefetch keeps every chunk it landed, and a 6GB+ * source can be half here and half in R2.+ *+ * Identity survives token rotation but never survives a rewrite. A signed+ * media URL carries its key in the path and its auth in the query (`e`, `s`),+ * and the token window re-mints the query every hour+ * (server/cloud/mediaCdn.ts), so the key alone names the cache. The `v`+ * cache-version param moves whenever the bytes under a fixed key move, and it+ * names a directory *under* the key rather than joining the key's own hash:+ * two versions of one object must never share a directory, because both can+ * be open at once — a re-rendered proxy plays while the old decoder finishes+ * its frame — and interleaved writes would splice two files together.+ *+ * Fetches belong to the object, not to any one reader. Every open holds a+ * reference; requests in the air are cancelled when the last one goes, so+ * closing the editor stops the downloads while one decoder disposing mid-run+ * leaves another's bytes coming.+ *+ * Everything here is a cache. A quota refusal, a torn write, or a browser+ * with no OPFS costs the network read it always cost; a read that cannot+ * reach the network at all is the one failure that propagates, and the+ * preview's outage recovery owns that.+ */++import {+ chunksDir,+ readFileAt,+ readJson,+ supportsBrowserStore,+ writeFileAt,+} from "./backend/browser/opfs";+import { CUT_MEDIA_ORIGIN } from "./hosts";++export const CHUNK_SIZE = 2 * 1024 * 1024;+/** Longest single ranged request, in chunks, when a read needs a missing run. */+const MAX_RUN = 8;+/** Chunks per request when the background prefetch walks a file. */+const PREFETCH_RUN = 4;+const META = "meta.json";+/** How long one storage estimate stands in for the next. */+const ESTIMATE_TTL_MS = 15_000;+/** Free space kept under quota beyond what a write needs — the same margin+ * the whole-file cache holds (mediaSync.ts). */+const QUOTA_MARGIN = 512 * 1024 * 1024;+const FETCH_ATTEMPTS = 3;+/** After the store refuses a write, wait this long before asking again. A+ * refusal is a moment's verdict: an eviction elsewhere can free hundreds of+ * megabytes seconds later, and an object that latched off would never notice. */+const PERSIST_RETRY_MS = 30_000;+/** Chunks written between meta commits. The resident map is what saves a+ * reopened file from enumerating thousands of directory entries, and it is+ * safe to lag: a claim the disk can't back costs one refetch. */+const META_EVERY = 8;++/** What one signed URL resolves to in the store. */+export interface ChunkIdentity {+ /** Decoded R2 key path, e.g. `/cut/<uid>/projects/<id>/media/<file>`. */+ key: string;+ /** The URL's `v` cache-version param; a rewrite in place moves it. */+ version: string;+ /** Directory naming the key. Holds one child per version. */+ keyHash: string;+ /** Directory naming this version's chunks, under `keyHash`. */+ versionTag: string;+}++interface ChunkMeta {+ key: string;+ version: string;+ size: number;+ chunk: number;+ /** Last use, for eviction recency. */+ at: number;+ /** Resident chunk indices as a base64 bitmap, LSB-first per byte. */+ resident?: string;+}++interface ObjState {+ id: ChunkIdentity;+ /** The freshest signed URL seen for this object; rotation swaps it in. */+ url: string;+ dir: FileSystemDirectoryHandle | null;+ size: number;+ /** Chunk indices believed to be on disk. Optimistic: a claim the disk can't+ * back costs one refetch, so a lagging meta is safe. */+ resident: Set<number>;+ /** Chunk indices with a fetch in the air, shared across readers. */+ inflight: Map<number, Promise<Uint8Array>>;+ /** Live opens. Requests are cancelled when this reaches zero. */+ refs: number;+ /** Cancels this object's requests; replaced once it has fired. */+ ac: AbortController;+ /** When the store last refused a write; reads keep working uncached until+ * `PERSIST_RETRY_MS` has passed. */+ refusedAt: number;+ /** The size probe's bytes, serving chunk 0 until its write commits. */+ probe0: Uint8Array | null;+ /** Chunk writes since the last meta commit. */+ dirty: number;+ /** True once this object's directory has been taken out from under it. */+ dead: boolean;+}++/** Parse a URL into a chunk identity, or null for anything this cache does+ * not hold: other origins, and tree-token paths (HLS ladders play through+ * their own player buffering). */+export function chunkIdentity(url: string): ChunkIdentity | null {+ let u: URL;+ try {+ u = new URL(url);+ } catch {+ return null;+ }+ if (u.origin !== CUT_MEDIA_ORIGIN || u.pathname.startsWith("/_t/")) return null;+ const key = u.pathname+ .split("/")+ .map((s) => {+ try {+ return decodeURIComponent(s);+ } catch {+ return s;+ }+ })+ .join("/");+ const version = u.searchParams.get("v") ?? "";+ return { key, version, keyHash: hash16(key), versionTag: hash16(version).slice(0, 8) };+}++/** FNV-1a over the input, twice with different seeds, as a directory name. */+function hash16(s: string): string {+ const pass = (seed: number) => {+ let h = seed >>> 0;+ for (let i = 0; i < s.length; i++) {+ h ^= s.charCodeAt(i);+ h = Math.imul(h, 0x01000193) >>> 0;+ }+ return h.toString(16).padStart(8, "0");+ };+ return pass(0x811c9dc5) + pass(0x9747b28c);+}++/** Group sorted chunk indices into consecutive runs no longer than `cap`. */+export function chunkRuns(indices: number[], cap: number): [number, number][] {+ const runs: [number, number][] = [];+ for (const i of indices) {+ const last = runs[runs.length - 1];+ if (last && i === last[1] + 1 && last[1] - last[0] + 1 < cap) last[1] = i;+ else runs.push([i, i]);+ }+ return runs;+}++/** Resident indices as a base64 bitmap, and back. */+export function encodeResident(resident: Iterable<number>, total: number): string {+ const bytes = new Uint8Array(Math.ceil(total / 8));+ for (const i of resident) {+ if (i >= 0 && i < total) bytes[i >> 3] |= 1 << (i & 7);+ }+ let s = "";+ for (const b of bytes) s += String.fromCharCode(b);+ return btoa(s);+}++export function decodeResident(b64: string, total: number): Set<number> {+ const out = new Set<number>();+ let s: string;+ try {+ s = atob(b64);+ } catch {+ return out;+ }+ for (let i = 0; i < total; i++) {+ if ((s.charCodeAt(i >> 3) || 0) & (1 << (i & 7))) out.add(i);+ }+ return out;+}++const chunkCount = (size: number) => Math.ceil(size / CHUNK_SIZE);+const chunkLen = (idx: number, size: number) => Math.min(CHUNK_SIZE, size - idx * CHUNK_SIZE);++// --- open ---++const states = new Map<string, Promise<ObjState>>();+const stateKey = (id: ChunkIdentity) => `${id.keyHash}/${id.versionTag}`;++function openObject(id: ChunkIdentity, url: string): Promise<ObjState> {+ const k = stateKey(id);+ const prior = states.get(k);+ // A later open carries a fresher token; the state's fetches follow it.+ if (prior) return prior.then((s) => ((s.url = url), s));+ const p = doOpen(id, url).catch((err) => {+ states.delete(k);+ throw err;+ });+ states.set(k, p);+ return p;+}++async function doOpen(id: ChunkIdentity, url: string): Promise<ObjState> {+ const dir = await versionDir(id);+ const state: ObjState = {+ id,+ url,+ dir,+ size: 0,+ resident: new Set(),+ inflight: new Map(),+ refs: 0,+ ac: new AbortController(),+ refusedAt: 0,+ probe0: null,+ dirty: 0,+ dead: false,+ };+ const meta = await readJson<ChunkMeta>(dir, META);+ if (+ meta &&+ meta.key === id.key &&+ meta.version === id.version &&+ meta.chunk === CHUNK_SIZE &&+ Number.isInteger(meta.size) &&+ meta.size >= 0+ ) {+ state.size = meta.size;+ const total = chunkCount(meta.size);+ state.resident = meta.resident+ ? decodeResident(meta.resident, total)+ : await scanResident(dir, total);+ void commitMeta(state);+ return state;+ }+ // No usable meta: whatever is in there answers for bytes we can't vouch+ // for. Start clean.+ if (dir) await wipe(dir);+ const res = await fetchRange(url, 0, CHUNK_SIZE - 1);+ if (res.status === 206) {+ const total = /\/(\d+)\s*$/.exec(res.headers.get("content-range") ?? "")?.[1];+ if (!total) throw new Error("Cloud media answered a range with no total size.");+ state.size = Number(total);+ state.probe0 = await collect(res, 0, Math.min(CHUNK_SIZE, state.size) - 1, false);+ } else if (res.ok) {+ // The range was ignored. Content-Length is the whole file; take chunk 0+ // off the front and drop the rest rather than buffering a 6GB body.+ state.size = Number(res.headers.get("content-length") ?? 0);+ if (!state.size) throw new Error("Cloud media answered with no length.");+ state.probe0 = await collect(res, 0, Math.min(CHUNK_SIZE, state.size) - 1, true);+ } else {+ throw new Error(`Cloud media read failed (${res.status}).`);+ }+ void persistChunk(state, 0, state.probe0);+ void commitMeta(state);+ return state;+}++/** `chunks/<keyHash>/<versionTag>/`, with every other version of the same key+ * swept as it is opened. An object rewritten in place leaves its old chunks+ * behind exactly once, and the next open of the new bytes collects them. */+async function versionDir(id: ChunkIdentity): Promise<FileSystemDirectoryHandle | null> {+ if (!supportsBrowserStore()) return null;+ try {+ const root = await chunksDir(true);+ if (!root) return null;+ const parent = await root.getDirectoryHandle(id.keyHash, { create: true });+ const stale: string[] = [];+ for await (const [name, h] of parent) {+ if (h.kind === "directory" && name !== id.versionTag) stale.push(name);+ }+ for (const name of stale) {+ await parent.removeEntry(name, { recursive: true }).catch(() => {});+ // A reader still holding the old version reads on, from the network.+ const old = states.get(`${id.keyHash}/${name}`);+ if (old) {+ states.delete(`${id.keyHash}/${name}`);+ void old+ .then((s) => {+ s.dead = true;+ s.dir = null;+ s.resident.clear();+ })+ .catch(() => {});+ }+ }+ return await parent.getDirectoryHandle(id.versionTag, { create: true });+ } catch {+ return null;+ }+}++/** Recover residency by enumerating chunk files. The repair path only — a+ * meta with a resident map spares thousands of directory reads on open. */+async function scanResident(+ dir: FileSystemDirectoryHandle | null,+ total: number+): Promise<Set<number>> {+ const out = new Set<number>();+ if (!dir) return out;+ try {+ for await (const [name, h] of dir) {+ if (h.kind !== "file" || !/^\d+$/.test(name)) continue;+ const idx = Number(name);+ if (idx < total) out.add(idx);+ }+ } catch {+ out.clear();+ }+ return out;+}++async function commitMeta(state: ObjState): Promise<void> {+ if (!state.dir || state.dead) return;+ state.dirty = 0;+ const meta: ChunkMeta = {+ key: state.id.key,+ version: state.id.version,+ size: state.size,+ chunk: CHUNK_SIZE,+ at: Date.now(),+ resident: encodeResident(state.resident, chunkCount(state.size)),+ };+ try {+ await writeFileAt(state.dir, META, JSON.stringify(meta));+ } catch {+ // Residency and recency go stale; reads refetch and the object ages+ // toward eviction faster.+ }+}++async function wipe(dir: FileSystemDirectoryHandle): Promise<void> {+ const names: string[] = [];+ try {+ for await (const [name] of dir) names.push(name);+ } catch {+ return;+ }+ for (const name of names) await dir.removeEntry(name, { recursive: true }).catch(() => {});+}++// --- refcounting ---++function acquire(state: ObjState): void {+ if (state.refs === 0 && state.ac.signal.aborted) state.ac = new AbortController();+ state.refs++;+}++function release(state: ObjState): void {+ state.refs = Math.max(0, state.refs - 1);+ if (state.refs > 0) return;+ // Nothing is reading this object: stop what is still coming down, and let+ // the probe copy go. What landed on disk stays.+ state.ac.abort();+ state.probe0 = null;+ if (state.dirty) void commitMeta(state);+}++// --- reads ---++/** Wait out a backoff, or give up early when the object is torn down. */+function sleep(ms: number, signal: AbortSignal): Promise<void> {+ return new Promise((resolve) => {+ const t = setTimeout(done, ms);+ function done() {+ clearTimeout(t);+ signal.removeEventListener("abort", done);+ resolve();+ }+ signal.addEventListener("abort", done, { once: true });+ });+}++async function fetchRange(+ url: string,+ start: number,+ endInclusive: number,+ signal?: AbortSignal+): Promise<Response> {+ let delay = 400;+ for (let attempt = 1; ; attempt++) {+ if (signal?.aborted) throw new DOMException("Aborted", "AbortError");+ try {+ const res = await fetch(url, {+ headers: { Range: `bytes=${start}-${endInclusive}` },+ signal,+ });+ // 4xx is the URL's own verdict — an expired token re-mints upstream+ // (mediaLinks.ts), and retrying the same string here would stall that.+ if (res.ok || attempt >= FETCH_ATTEMPTS || (res.status >= 400 && res.status < 500)) return res;+ } catch (err) {+ if (signal?.aborted || attempt >= FETCH_ATTEMPTS) throw err;+ }+ await sleep(delay, signal ?? new AbortController().signal);+ delay *= 3;+ }+}++/** Read `[start, end]` out of a response body, holding only those bytes. When+ * `fromZero`, the body starts at byte 0 whatever was asked for, so the front+ * is streamed past and the rest is dropped without ever being buffered. */+async function collect(+ res: Response,+ start: number,+ endInclusive: number,+ fromZero: boolean+): Promise<Uint8Array> {+ const want = endInclusive - start + 1;+ const out = new Uint8Array(want);+ const reader = res.body?.getReader();+ if (!reader) {+ const all = new Uint8Array(await res.arrayBuffer());+ const from = fromZero ? start : 0;+ if (all.length < from + want) throw new Error("Cloud media returned a short range.");+ out.set(all.subarray(from, from + want));+ return out;+ }+ let pos = fromZero ? 0 : start; // absolute position of the next byte read+ let filled = 0;+ try {+ while (filled < want) {+ const { done, value } = await reader.read();+ if (done) break;+ const chunkStart = pos;+ pos += value.length;+ const from = Math.max(start, chunkStart);+ const to = Math.min(endInclusive + 1, pos);+ if (to > from) {+ out.set(value.subarray(from - chunkStart, to - chunkStart), from - start);+ filled += to - from;+ }+ }+ } finally {+ await reader.cancel().catch(() => {});+ }+ if (filled < want) throw new Error("Cloud media returned a short range.");+ return out;+}++/** Fetch one missing run, resolving each chunk to every reader waiting on it+ * and writing it to the store as it settles. */+function startRun(state: ObjState, first: number, last: number): Promise<Uint8Array>[] {+ const settles: { resolve: (b: Uint8Array) => void; reject: (e: unknown) => void }[] = [];+ const promises: Promise<Uint8Array>[] = [];+ for (let i = first; i <= last; i++) {+ let settle!: (typeof settles)[number];+ const p = new Promise<Uint8Array>((resolve, reject) => (settle = { resolve, reject }));+ // Nothing may reach an unhandled rejection: a run can outlive the read+ // that started it, and every consumer attaches its own handler.+ p.catch(() => {});+ settles.push(settle);+ promises.push(p);+ state.inflight.set(i, p);+ const drop = () => {+ if (state.inflight.get(i) === p) state.inflight.delete(i);+ };+ p.then(drop, drop);+ }+ void (async () => {+ try {+ const startB = first * CHUNK_SIZE;+ const endB = Math.min(state.size, (last + 1) * CHUNK_SIZE) - 1;+ const res = await fetchRange(state.url, startB, endB, state.ac.signal);+ if (!res.ok) throw new Error(`Cloud media read failed (${res.status}).`);+ const body = await collect(res, startB, endB, res.status !== 206);+ for (let i = first; i <= last; i++) {+ // A copy per chunk, so holding one chunk can't pin the whole run.+ const bytes = body.slice((i - first) * CHUNK_SIZE, (i - first + 1) * CHUNK_SIZE);+ settles[i - first].resolve(bytes);+ void persistChunk(state, i, bytes);+ }+ } catch (err) {+ for (const s of settles) s.reject(err);+ }+ })();+ return promises;+}++async function residentBytes(state: ObjState, idx: number): Promise<Uint8Array | null> {+ const file = await readFileAt(state.dir, String(idx));+ if (!file || file.size !== chunkLen(idx, state.size)) {+ state.resident.delete(idx);+ return null;+ }+ return new Uint8Array(await file.arrayBuffer());+}++/** Read `[start, end)`, serving resident chunks and fetching missing ones in+ * coalesced runs. Returns exactly `end - start` bytes or throws. */+async function readRange(state: ObjState, start: number, end: number): Promise<Uint8Array> {+ end = Math.min(end, state.size);+ const out = new Uint8Array(Math.max(0, end - start));+ if (!out.length) return out;+ const c0 = Math.floor(start / CHUNK_SIZE);+ const c1 = Math.floor((end - 1) / CHUNK_SIZE);+ const place = (idx: number, bytes: Uint8Array) => {+ const base = idx * CHUNK_SIZE;+ const from = Math.max(start, base);+ const to = Math.min(end, base + bytes.length);+ if (to > from) out.set(bytes.subarray(from - base, to - base), from - start);+ };+ // Plan first: pin the fetches already in the air, then open one run per+ // consecutive stretch that has to touch the network.+ const have = new Map<number, Promise<Uint8Array>>();+ const need: number[] = [];+ for (let i = c0; i <= c1; i++) {+ const flying = state.inflight.get(i);+ if (flying) have.set(i, flying);+ else if (!state.resident.has(i) && !(i === 0 && state.probe0)) need.push(i);+ }+ for (const [a, b] of chunkRuns(need, MAX_RUN)) {+ const runPromises = startRun(state, a, b);+ for (let i = a; i <= b; i++) have.set(i, runPromises[i - a]);+ }+ await Promise.all(+ Array.from({ length: c1 - c0 + 1 }, async (_, k) => {+ const idx = c0 + k;+ const planned = have.get(idx);+ if (planned) return place(idx, await planned);+ if (idx === 0 && state.probe0 && !state.resident.has(0)) return place(0, state.probe0);+ const disk = await residentBytes(state, idx);+ if (disk) return place(idx, disk);+ // The disk copy vanished under us (evicted mid-read); fetch it alone.+ const [refetch] = startRun(state, idx, idx);+ place(idx, await refetch);+ })+ );+ return out;+}++// --- persistence and room ---++function canPersist(state: ObjState): boolean {+ if (!state.dir || state.dead) return false;+ return !state.refusedAt || Date.now() - state.refusedAt >= PERSIST_RETRY_MS;+}++async function persistChunk(state: ObjState, idx: number, bytes: Uint8Array): Promise<void> {+ if (!canPersist(state)) return;+ if (!(await roomFor(bytes.length, state.id.keyHash))) {+ state.refusedAt = Date.now();+ return;+ }+ try {+ await writeFileAt(state.dir!, String(idx), new Blob([bytes as BlobPart]));+ state.resident.add(idx);+ if (idx === 0) state.probe0 = null;+ if (++state.dirty >= META_EVERY) void commitMeta(state);+ } catch {+ // A cache write only; the bytes were already served. The reservation goes+ // back so a run of failures can't talk the store into believing it's full.+ refund(bytes.length);+ }+}++let lastEstimate: { at: number; usage: number; quota: number } | null = null;++function refund(bytes: number): void {+ if (lastEstimate) lastEstimate.usage = Math.max(0, lastEstimate.usage - bytes);+}++async function roomFor(bytes: number, keepKeyHash: string): Promise<boolean> {+ try {+ if (!lastEstimate || Date.now() - lastEstimate.at > ESTIMATE_TTL_MS) {+ const est = await navigator.storage.estimate?.();+ if (!est?.quota) return true;+ lastEstimate = { at: Date.now(), usage: est.usage ?? 0, quota: est.quota };+ }+ } catch {+ return true;+ }+ const margin = Math.min(QUOTA_MARGIN, lastEstimate.quota * 0.1);+ let deficit = lastEstimate.usage + bytes + margin - lastEstimate.quota;+ if (deficit > 0) {+ const freed = await evictChunkBytes(deficit, keepKeyHash);+ refund(freed);+ deficit -= freed;+ }+ if (deficit > 0) return false;+ lastEstimate.usage += bytes;+ return true;+}++/** One cached version of one object, as eviction sees it. */+interface Candidate {+ keyHash: string;+ versionTag: string;+ at: number;+ bytes: number;+}++async function listCached(keepKeyHash?: string): Promise<Candidate[]> {+ const root = await chunksDir();+ if (!root) return [];+ const out: Candidate[] = [];+ try {+ for await (const [keyHash, h] of root) {+ if (h.kind !== "directory" || keyHash === keepKeyHash) continue;+ const parent = await root.getDirectoryHandle(keyHash).catch(() => null);+ if (!parent) continue;+ for await (const [versionTag, vh] of parent) {+ if (vh.kind !== "directory") continue;+ const dir = await parent.getDirectoryHandle(versionTag).catch(() => null);+ const meta = await readJson<ChunkMeta>(dir, META);+ out.push({+ keyHash,+ versionTag,+ at: meta?.at ?? 0,+ bytes: meta ? residentBytesOf(meta) : 0,+ });+ }+ }+ } catch {+ return out;+ }+ return out;+}++/** What a cached version actually occupies, from its own meta — the last+ * chunk is short, so counting every chunk at full size over-reports and+ * leaves `makeRoom` believing it freed room it did not. */+function residentBytesOf(meta: ChunkMeta): number {+ if (!meta.resident || !meta.size) return 0;+ let total = 0;+ for (const i of decodeResident(meta.resident, chunkCount(meta.size))) {+ total += Math.min(CHUNK_SIZE, meta.size - i * CHUNK_SIZE);+ }+ return total;+}++/** Free chunk-store bytes toward `deficit`, dropping least recently used+ * versions first. Returns the bytes freed. The whole-file cache's makeRoom+ * spends this store before its own — a chunk is the cheapest byte to lose. */+export async function evictChunkBytes(deficit: number, keepKeyHash?: string): Promise<number> {+ if (deficit <= 0 || !supportsBrowserStore()) return 0;+ const candidates = await listCached(keepKeyHash);+ candidates.sort((a, b) => a.at - b.at);+ let freed = 0;+ for (const c of candidates) {+ if (freed >= deficit) break;+ freed += await removeVersion(c.keyHash, c.versionTag, c.bytes);+ }+ return freed;+}++async function removeVersion(keyHash: string, versionTag: string, bytes: number): Promise<number> {+ const root = await chunksDir();+ if (!root) return 0;+ try {+ const parent = await root.getDirectoryHandle(keyHash);+ await parent.removeEntry(versionTag, { recursive: true });+ // An empty key directory is litter; the next estimate shouldn't walk it.+ let empty = true;+ for await (const entry of parent) {+ void entry;+ empty = false;+ break;+ }+ if (empty) await root.removeEntry(keyHash, { recursive: true }).catch(() => {});+ } catch {+ return 0;+ }+ const k = `${keyHash}/${versionTag}`;+ const live = states.get(k);+ if (live) {+ states.delete(k);+ // A live reader heals to the network on its next miss.+ void live+ .then((s) => {+ s.dead = true;+ s.dir = null;+ s.resident.clear();+ })+ .catch(() => {});+ }+ return bytes;+}++/** Drop every cached object whose key contains `part` — the local half of a+ * media or project delete. */+export async function dropChunksMatching(part: string): Promise<void> {+ if (!supportsBrowserStore()) return;+ const root = await chunksDir();+ if (!root) return;+ const doomed: Candidate[] = [];+ try {+ for await (const [keyHash, h] of root) {+ if (h.kind !== "directory") continue;+ const parent = await root.getDirectoryHandle(keyHash).catch(() => null);+ if (!parent) continue;+ for await (const [versionTag, vh] of parent) {+ if (vh.kind !== "directory") continue;+ const dir = await parent.getDirectoryHandle(versionTag).catch(() => null);+ const meta = await readJson<ChunkMeta>(dir, META);+ if (meta?.key.includes(part)) {+ doomed.push({ keyHash, versionTag, at: 0, bytes: residentBytesOf(meta) });+ }+ }+ }+ } catch {+ return;+ }+ for (const d of doomed) refund(await removeVersion(d.keyHash, d.versionTag, d.bytes));+}++// --- the seams ---++/** CustomSource callbacks over the chunk store for a signed cloud media URL,+ * or null when the URL is not cloud media or this browser holds no store —+ * the caller falls back to a plain URL source. `dispose` releases the object,+ * which cancels its requests once nothing else is reading it. */+export function chunkSourceOptions(url: string): {+ getSize: () => Promise<number>;+ read: (start: number, end: number) => Promise<Uint8Array>;+ dispose: () => void;+} | null {+ if (!supportsBrowserStore()) return null;+ const id = chunkIdentity(url);+ if (!id) return null;+ let opened: Promise<ObjState> | null = null;+ let disposed = false;+ const open = () =>+ (opened ??= openObject(id, url).then((s) => {+ if (disposed) throw new DOMException("Aborted", "AbortError");+ acquire(s);+ return s;+ }));+ return {+ getSize: async () => (await open()).size,+ read: async (start, end) => readRange(await open(), start, end),+ dispose: () => {+ if (disposed) return;+ disposed = true;+ void opened?.then(release).catch(() => {});+ },+ };+}++/** Walk a file's chunks into the store front to back, skipping what is+ * already resident or in the air. Stops on abort, on a store that has run out+ * of room, and on a network failure — every chunk that landed stays. */+export async function prefetchChunks(url: string, signal: AbortSignal): Promise<void> {+ if (!supportsBrowserStore() || signal.aborted) return;+ const id = chunkIdentity(url);+ if (!id) return;+ const state = await openObject(id, url);+ if (!state.dir) return;+ acquire(state);+ try {+ const total = chunkCount(state.size);+ for (let i = 0; i < total; i++) {+ if (signal.aborted || !canPersist(state)) return;+ if (state.resident.has(i) || state.inflight.has(i)) continue;+ let last = i;+ while (+ last - i + 1 < PREFETCH_RUN &&+ last + 1 < total &&+ !state.resident.has(last + 1) &&+ !state.inflight.has(last + 1)+ ) {+ last++;+ }+ try {+ await Promise.all(startRun(state, i, last));+ } catch {+ return; // a blip leaves this file partial; reads finish the rest on demand+ }+ i = last;+ }+ } finally {+ if (state.dirty) await commitMeta(state);+ release(state);+ }+}diff --git a/site/src/cut/lib/mediaRead.ts b/site/src/cut/lib/mediaRead.tsindex b2321c17..fc5b5186 100644--- a/site/src/cut/lib/mediaRead.ts+++ b/site/src/cut/lib/mediaRead.ts@@ -30,6 +30,7 @@ import {AudioBufferSink,BlobSource,CanvasSink,+ CustomSource,EncodedPacketSink,Input,UrlSource,@@ -40,6 +41,7 @@ import {type WrappedCanvas,} from "mediabunny";import { resolveRegisteredBlob } from "./backend/browser/registry";+import { chunkSourceOptions } from "./chunkCache";/** What a file turns out to be, read from its container. */export interface MediaProbe {@@ -73,15 +75,42 @@ export class UnreadableMediaError extends Error {}}+/** Ranged requests kept in the air for one URL.+ *+ * Widening only pays where a round trip is the cost. The local engine serves+ * files off this Mac's disk over HTTP/1.1, where a browser allows six+ * connections per origin in total — a handful of clips each asking for eight+ * would put the frame being drawn behind readahead for clips nobody is+ * looking at. So the local engine and any other plain-HTTP origin keep the+ * library's pair, and so does a link that says it is slow or metered. The+ * width is for multiplexed cloud media over a real network. */+function urlParallelism(url: string): number {+ if (!/^https:/i.test(url)) return 2;+ const conn =+ typeof navigator === "undefined"+ ? undefined+ : (navigator as { connection?: { saveData?: boolean; effectiveType?: string } }).connection;+ if (conn?.saveData || /(^|-)2g$|^3g$/.test(conn?.effectiveType ?? "")) return 2;+ return 8;+}+/** Open a file for reading. The caller owns it and must `dispose()` it. A URL* the browser store minted resolves to its backing File and reads as a blob —- * ranged fetches of blob URLs are unreliable across browsers. */+ * ranged fetches of blob URLs are unreliable across browsers. Signed cloud+ * media reads through the chunk cache (chunkCache.ts), so bytes touched once+ * are on disk for the next read of the same object. */export function openMedia(src: string | Blob): Input {const blob = typeof src === "string" ? resolveRegisteredBlob(src) ?? src : src;- return new Input({- formats: ALL_FORMATS,- source: typeof blob === "string" ? new UrlSource(blob) : new BlobSource(blob),- });+ let source;+ if (typeof blob === "string") {+ const chunked = chunkSourceOptions(blob);+ source = chunked+ ? new CustomSource({ ...chunked, prefetchProfile: "network", maxCacheSize: 64 * 2 ** 20 })+ : new UrlSource(blob, { parallelism: urlParallelism(blob) });+ } else {+ source = new BlobSource(blob);+ }+ return new Input({ formats: ALL_FORMATS, source });}/** Run `fn` against an open input and dispose it however that ends. */diff --git a/site/src/cut/lib/mediaSync.ts b/site/src/cut/lib/mediaSync.tsindex d529370e..d0f686f9 100644--- a/site/src/cut/lib/mediaSync.ts+++ b/site/src/cut/lib/mediaSync.ts@@ -38,6 +38,8 @@ import {type PendingUpload,} from "./backend/browser/opfs";import { registerBlobFile, registeredUrl, revokeRegistered } from "./backend/browser/registry";+import { dropChunksMatching, evictChunkBytes, prefetchChunks } from "./chunkCache";+import type { AssetType } from "./types";const mediaPath = (projectId: string, fileName: string) =>`/api/cut/projects/${projectId}/media/${encodeURIComponent(fileName)}`;@@ -165,11 +167,12 @@ export async function localMediaUrl(projectId: string, fileName: string): Promisreturn file ? registerBlobFile(path, file) : null;}-/** A media delete's local half: the file, its blob URL, and its pin. */+/** A media delete's local half: the file, its chunks, its blob URL, its pin. */export async function dropLocalMedia(projectId: string, fileName: string): Promise<void> {if (!supportsBrowserStore()) return;revokeRegistered(mediaPath(projectId, fileName));await deleteMedia(projectId, fileName).catch(() => {});+ void dropChunksMatching(`/projects/${projectId}/media/${fileName}`);await clearPendingUpload(projectId, fileName);}@@ -178,6 +181,7 @@ export async function dropLocalProjectCopy(projectId: string): Promise<void> {if (!supportsBrowserStore()) return;if (prefetch?.projectId === projectId) prefetch.ctrl.abort();revokeRegistered(`/api/cut/projects/${projectId}/`);+ void dropChunksMatching(`/projects/${projectId}/`);await deleteProject(projectId).catch(() => {});try {await updateIndex((idx) => {@@ -195,16 +199,19 @@ type PrefetchRun = { projectId: string; ctrl: AbortController };let prefetch: PrefetchRun | null = null;/** Prefetch a cloud project's missing media into the store, one file at a- * time in the order given. Every file reports back through `onDone` exactly- * once — its blob URL when the bytes landed, null when the run gave up on it- * — so the caller can swap playing assets onto local bytes mid-session and- * retire per-file loading state either way. Starting a prefetch cancels any- * earlier one — the queue follows the open project — and records the open for- * eviction recency. Fire-and-forget; a failed or refused write costs nothing- * but the cache. */+ * time in the order given. Video fills the chunk cache (chunkCache.ts): the+ * asset keeps its signed URL, playback reads resident chunks off disk, and an+ * interrupted walk keeps every chunk it landed. Other files stream in whole+ * and swap onto blob URLs, so an <img> paints local bytes offline. Every file+ * reports back through `onDone` exactly once — its blob URL when whole bytes+ * landed, null otherwise — so the caller can swap playing assets mid-session+ * and retire per-file loading state either way. Starting a prefetch cancels+ * any earlier one — the queue follows the open project — and records the open+ * for eviction recency. Fire-and-forget; a failed or refused write costs+ * nothing but the cache. */export function prefetchCloudMedia(projectId: string,- files: { fileName: string; url: string }[],+ files: { fileName: string; url: string; type?: AssetType }[],onDone?: (fileName: string, blobUrl: string | null) => void): void {if (!supportsBrowserStore()) {@@ -221,10 +228,13 @@ export function prefetchCloudMedia(for (let i = 0; i < files.length; i++) {if (run.ctrl.signal.aborted) return;const f = files[i];- const r = await cacheOne(projectId, f.fileName, f.url, run.ctrl.signal).catch(- // Offline mid-stream: the abort discarded the partial write.- () => ({ go: true, url: null as string | null })- );+ const r =+ f.type === "video"+ ? await cacheVideoChunks(f.url, run.ctrl.signal)+ : await cacheOne(projectId, f.fileName, f.url, run.ctrl.signal).catch(+ // Offline mid-stream: the abort discarded the partial write.+ () => ({ go: true, url: null as string | null })+ );if (run.ctrl.signal.aborted) return;onDone?.(f.fileName, r.url);if (!r.go) {@@ -236,6 +246,17 @@ export function prefetchCloudMedia(})();}+/** Walk a video's chunks into the chunk cache. The asset plays through its+ * signed URL either way, so any failure just leaves the file partial —+ * on-demand reads finish it — and the queue always goes on. */+async function cacheVideoChunks(+ url: string,+ signal: AbortSignal+): Promise<{ go: boolean; url: string | null }> {+ await prefetchChunks(url, signal).catch(() => {});+ return { go: !signal.aborted, url: null };+}+/** Stream one file into the store. `go: false` means storage is out of room* even after eviction, which ends the whole run. */async function cacheOne(@@ -295,6 +316,10 @@ async function makeRoom(keepId: string, bytes: number): Promise<void> {const margin = Math.min(QUOTA_MARGIN, est.quota * 0.1);let deficit = (est.usage ?? 0) + bytes + margin - est.quota;if (deficit <= 0) return;+ // The chunk cache is the cheapest byte to lose — losing one costs a ranged+ // re-fetch, where losing a whole-file copy costs the file — so it goes first.+ deficit -= await evictChunkBytes(deficit);+ if (deficit <= 0) return;const idx = await readIndex();const pinned = new Set(idx.pendingUploads.map((p) => `${p.projectId}/${p.fileName}`));const candidates: { id: string; openedAt: number }[] = [];diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.tsindex 25505214..41d2270d 100644--- a/site/src/cut/lib/store.ts+++ b/site/src/cut/lib/store.ts@@ -1610,17 +1610,26 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {const queue = missing.flatMap((a) => {const url = signed.urls.get(a.fileName);- return url ? [{ fileName: a.fileName, url }] : [];+ return url ? [{ fileName: a.fileName, url, type: a.type }] : [];}).sort((x, y) =>(firstUse.get(x.fileName) ?? Infinity) - (firstUse.get(y.fileName) ?? Infinity));- set({ loadingMedia: new Set(queue.map((f) => f.fileName)) });+ // Video reads through the chunk cache and plays from its first+ // chunk, so only whole-file fetches show as loading.+ set({+ loadingMedia: new Set(+ queue.filter((f) => f.type !== "video").map((f) => f.fileName)+ ),+ });prefetchCloudMedia(id, queue, (fileName, url) => {const st = get();if (st.projectId !== id) return;if (url) st.applyMediaUrls(new Map([[fileName, url]]));+ // Video was never in the set; re-seating it would hand every+ // subscriber a new Set identity for no change.+ if (!st.loadingMedia.has(fileName)) return;set((s) => {const next = new Set(s.loadingMedia);next.delete(fileName);