Skip to content

Open source CapCut alternative.

TypeScript
16.2 KB
Raw Blame
"use client";

/**
 * Library items a document points at instead of copying.
 *
 * Most of what comes off the Library is copied when it is used: a clip's bytes
 * become the project's own, and the shelf and the project go their separate
 * ways. Some kinds are pointed at instead — a font is named by every title set
 * in it, and the file stays on the shelf where every project can reach it.
 * Those links are what this module keeps honest, for fonts today and for
 * whatever is linked rather than copied next.
 *
 * Three rules hold for every linked kind:
 *
 * - **Identity is the bytes.** A linked item is keyed by a hash of its content,
 *   not by the shelf row holding it, so the same file on two shelves is one
 *   item and one id. That is what lets a project change residency without a
 *   word of it being rewritten.
 * - **New ones land where everything can read them.** The cloud shelf, when
 *   there is room and the item is small enough that where it sits is not a real
 *   choice — a render job reads no other shelf.
 * - **They travel with the project.** A project moving to the cloud takes the
 *   linked items it depends on with it.
 */

import { readSnapshot, writeSnapshot } from "../cache";
import { contentKey } from "../contentKey";
import {
  fetchLibrary,
  moveLibraryItem,
  uploadToLibrary,
  type LibraryAsset,
} from "../library";
import { activeResidency, backendFor, type Residency } from "../residency";
import type { ProjectDoc } from "../types";

/** One shelf row carrying a linked item's bytes. */
export interface LinkedCopy {
  assetId: string;
  residency: Residency;
  fileName: string;
  name: string;
}

/** A linked item as its menu knows it: one thing, however many shelves hold it. */
export interface LinkedItem {
  /** Content key — see the module note. */
  key: string;
  prefix: string;
  label: string;
  copies: LinkedCopy[];
}

/**
 * A kind of library item documents link to. Registered once at module load by
 * the feature that owns it.
 */
export interface LinkedKind {
  /** Id prefix a document writes, e.g. "font" for `font:<key>`. */
  prefix: string;
  /** The library asset type carrying it. */
  type: LibraryAsset["type"];
  /** A kind keyed off its shelf row: the page that shelved the file wrote its
   * content key onto the row (`LibraryAsset.contentKey`), so a sync lists it
   * without reading a byte. Its bytes are read when something uses it. A row
   * without a key is left out of the listing. */
  lazy?: true;
  /** The ids of this kind a document is set in, so a project move can carry
   * them. */
  extract: (doc: ProjectDoc) => string[];
  /** Put one item's bytes to use in this process — installing a font face,
   * say. Throwing leaves the item out of the listing. */
  use?: (key: string, label: string, bytes: ArrayBuffer) => Promise<void>;
  /** Keys that have left the shelf, so the feature can drop them. */
  drop?: (keys: string[]) => void;
  /** Carry a renamed item's new name to the feature already using it. */
  relabel?: (key: string, label: string) => void;
  /** Folder a new one is filed into when the shelf has one by that name. */
  homeFolder?: string;
  /** Whether a dropped OS file is one of these. */
  matches: (file: File) => boolean;
  /** What a file picker offers for this kind, archives included. */
  accept?: string;
  /** Files inside an archive of this kind, or `null` when the file is not one.
   * A font arrives as a zip from every foundry that publishes one, and a
   * template or a sticker pack will arrive the same way. */
  unpack?: (file: File) => Promise<File[] | null>;
}

const kinds = new Map<string, LinkedKind>();

export function registerLinkedKind(kind: LinkedKind): void {
  kinds.set(kind.prefix, kind);
}

export const linkId = (prefix: string, key: string) => `${prefix}:${key}`;

/** Whether the Library lends this kind of item rather than copying it — what
 * tells an upload to reach for a shelf every surface can read, and a delete to
 * take it out of the menus that offer it. */
export const isLinkedType = (type: LibraryAsset["type"]): boolean =>
  [...kinds.values()].some((k) => k.type === type);

/** Whether a dropped OS file is a linked kind. */
export const isLinkedFile = (file: File): boolean =>
  [...kinds.values()].some((k) => k.matches(file));

/** What every linked kind takes, for a file input's `accept` — or one kind's,
 * for a picker that offers only that. */
export const linkedAccept = (prefix?: string): string =>
  [...kinds.values()]
    .filter((k) => !prefix || k.prefix === prefix)
    .flatMap((k) => (k.accept ? [k.accept] : []))
    .join(",");

/** The library asset type a dropped OS file would shelve as, when a linked
 * kind claims it. */
export const linkedTypeOfFile = (file: File): LibraryAsset["type"] | null =>
  [...kinds.values()].find((k) => k.matches(file))?.type ?? null;

/**
 * A dropped batch with its archives opened.
 *
 * What a user has in hand is what the download gave them, and for a font that
 * is a zip. Opening it here means every intake point — the Library page, the
 * editor's panel, the font menu — takes the file as it arrived. A file no kind
 * claims passes through untouched.
 */
export async function expandLinkedFiles(files: File[]): Promise<File[]> {
  const out: File[] = [];
  for (const file of files) {
    let opened: File[] | null = null;
    for (const kind of kinds.values()) {
      opened = (await kind.unpack?.(file).catch(() => null)) ?? null;
      if (opened) break;
    }
    out.push(...(opened ?? [file]));
  }
  return out;
}

/** Items small enough that which shelf holds them is not a real choice. Past
 * this, a new item stays on the shelf the user is working from, because moving
 * real weight into someone's cloud quota is their call to make. */
export const LINKED_CARRY_MAX_BYTES = 10 * 1024 ** 2;

let items: LinkedItem[] = [];
const byAsset = new Map<string, LinkedItem>();
/** Keys already in use in this process, per kind. */
const used = new Map<string, Promise<void>>();
/** The name each item in use was last put to use under. */
const labels = new Map<string, string>();
const listeners = new Set<() => void>();

/** One array per kind, held until the listing changes: a subscriber reads this
 * on every render and a fresh array each time would never settle. */
const perKind = new Map<string, LinkedItem[]>();

export const listLinked = (prefix: string): LinkedItem[] => {
  const held = perKind.get(prefix);
  if (held) return held;
  const made = items.filter((i) => i.prefix === prefix);
  perKind.set(prefix, made);
  return made;
};

/** The link id a Library card should render itself as. */
export const linkIdForAsset = (assetId: string): string | null => {
  const hit = byAsset.get(assetId);
  return hit ? linkId(hit.prefix, hit.key) : null;
};

export function onLinkedChanged(cb: () => void): () => void {
  listeners.add(cb);
  return () => listeners.delete(cb);
}

function publish(next: LinkedItem[]): void {
  items = next;
  perKind.clear();
  byAsset.clear();
  for (const i of next) for (const c of i.copies) byAsset.set(c.assetId, i);
  for (const cb of listeners) cb();
}

export { contentKey };

const bytesKey = (assetId: string) => `linked/${assetId}`;

/** The bytes for one shelf item: off the shelf when it answers, else the copy
 * kept from the last time it did. Something that has been used once keeps
 * working when the shelf holding it is out of reach.
 *
 * Read through the shelf's own backend rather than its URL: a render job
 * carries its auth in headers the page gets from a cookie, and the browser
 * shelf answers in the page rather than over the network. */
export async function linkedBytes(
  a: Pick<LibraryAsset, "id" | "fileName" | "residency">,
): Promise<ArrayBuffer> {
  try {
    const res = await backendFor(a.residency).fetch(
      `/api/cut/library/media/${encodeURIComponent(a.fileName)}`,
    );
    if (!res.ok) throw new Error("linked item fetch failed");
    const bytes = await res.arrayBuffer();
    writeSnapshot(bytesKey(a.id), bytes);
    return bytes;
  } catch (e) {
    const hit = await readSnapshot<ArrayBuffer>(bytesKey(a.id));
    if (hit) return hit.value;
    throw e;
  }
}

function put(
  kind: LinkedKind,
  key: string,
  label: string,
  bytes: ArrayBuffer | null,
): Promise<void> {
  const id = linkId(kind.prefix, key);
  let hit = used.get(id);
  if (labels.get(id) !== label) {
    if (hit) void hit.then(() => kind.relabel?.(key, label));
    labels.set(id, label);
  }
  if (hit) return hit;
  hit = (kind.use && bytes ? kind.use(key, label, bytes) : Promise.resolve()).catch(
    () => {
      // Bytes that will not load: drop the marker so a later pass retries, and
      // let whatever points at them fall back.
      used.delete(id);
    },
  );
  used.set(id, hit);
  return hit;
}

/**
 * Reconcile this process with the account's linked items: put new ones to use,
 * drop deleted ones, and publish the listing their menus draw.
 *
 * The editor calls this on open and after every upload or delete; a headless
 * run awaits it before drawing anything.
 */
export async function syncLinkedLibrary(): Promise<void> {
  if (kinds.size === 0) return;
  const types = new Set([...kinds.values()].map((k) => k.type));
  let shelf: LibraryAsset[];
  try {
    shelf = (await fetchLibrary()).assets.filter((a) => types.has(a.type));
  } catch {
    // No shelf reachable: keep whatever is already in use rather than tearing
    // the user's items out of a menu mid-session.
    return;
  }
  const kindFor = (a: LibraryAsset) =>
    [...kinds.values()].find((k) => k.type === a.type);
  // Read and key every shelf copy at once, then put them to use in a fixed
  // order: two shelves holding one item may have stored it under different
  // names, and a menu should not label it differently from one session to the
  // next. The cloud copy's name wins, since that is the one every surface reads.
  // A lazy kind is keyed off its row and read only when used.
  const read = await Promise.all(
    shelf.map(async (a) => {
      const kind = kindFor(a);
      if (!kind) return null;
      if (kind.lazy) return a.contentKey ? { a, kind, bytes: null, key: a.contentKey } : null;
      try {
        const bytes = await linkedBytes(a);
        return { a, kind, bytes, key: await contentKey(bytes) };
      } catch {
        return null; // That shelf isn't answering; another copy may still serve.
      }
    }),
  );
  const ordered = read
    .filter((r): r is NonNullable<typeof r> => r !== null)
    .sort(
      (x, y) =>
        Number(y.a.residency === "cloud") - Number(x.a.residency === "cloud") ||
        x.a.fileName.localeCompare(y.a.fileName),
    );
  const found = new Map<string, LinkedItem>();
  for (const { a, kind, bytes, key } of ordered) {
    const id = linkId(kind.prefix, key);
    const hit = found.get(id);
    // The first copy in the order names the item; a later one only stands
    // in for its bytes.
    const label = hit?.label ?? a.name;
    await put(kind, key, label, bytes);
    const copy: LinkedCopy = {
      assetId: a.id,
      residency: a.residency,
      fileName: a.fileName,
      name: a.name,
    };
    if (hit) hit.copies.push(copy);
    else
      found.set(id, {
        key,
        prefix: kind.prefix,
        label,
        copies: [copy],
      });
  }
  const stale = [...used.keys()].filter((id) => !found.has(id));
  if (stale.length) {
    for (const id of stale) {
      used.delete(id);
      labels.delete(id);
    }
    for (const kind of kinds.values()) {
      const mine = stale.filter((id) => id.startsWith(`${kind.prefix}:`));
      if (mine.length)
        kind.drop?.(mine.map((id) => id.slice(kind.prefix.length + 1)));
    }
  }
  publish([...found.values()]);
}

/** Drop the shelf copies of the linked assets among `assets` — what a
 * delete of them takes, whether the grid, a folder delete, or the assistant
 * runs it. */
export function forgetLinkedCopies(assets: readonly Pick<LibraryAsset, "id" | "type">[]): void {
  for (const a of assets) if (isLinkedType(a.type)) forgetLinkedCopy(a.id);
}

/** Drop one shelf copy the moment it is deleted, so the shelf and the menus
 * never disagree while the round trip settles. */
export function forgetLinkedCopy(assetId: string): void {
  const item = byAsset.get(assetId);
  if (!item) return;
  const next: LinkedItem[] = [];
  for (const i of items) {
    if (i !== item) {
      next.push(i);
      continue;
    }
    const copies = i.copies.filter((c) => c.assetId !== assetId);
    if (copies.length > 0) next.push({ ...i, copies });
    else {
      const id = linkId(i.prefix, i.key);
      used.delete(id);
      labels.delete(id);
      kinds.get(i.prefix)?.drop?.([i.key]);
    }
  }
  publish(next);
}

/**
 * Which shelf a new item belongs on, when nothing else has decided (something
 * dropped into a folder belongs to that folder's shelf).
 *
 * The cloud, whenever it is small enough and there is room. It is the only
 * shelf every surface can read — a render job reaches nothing else — and below
 * the carry limit where it sits is not a real choice. A large file, a full
 * account, or a cloud that isn't answering lands it on the shelf the user is
 * working from.
 *
 * Room, never tier: a free account has 250MB and a linked item is under one.
 */
export async function shelfForNewItem(bytes: number): Promise<Residency> {
  const here = activeResidency();
  if (here === "cloud") return "cloud";
  if (bytes > LINKED_CARRY_MAX_BYTES) return here;
  try {
    const res = await backendFor("cloud").fetch("/api/cut/usage");
    if (!res.ok) return here;
    const usage = (await res.json()) as {
      bytes: number;
      quotaBytes: number | null;
    };
    if (usage.quotaBytes === null) return "cloud";
    return usage.bytes + bytes <= usage.quotaBytes ? "cloud" : here;
  } catch {
    return here;
  }
}

/** Put a file on the shelf as a linked item of this kind and return its id. */
export async function uploadLinkedItem(
  prefix: string,
  file: File,
): Promise<string> {
  const kind = kinds.get(prefix);
  const residency = await shelfForNewItem(file.size);
  const asset = await uploadToLibrary(file, residency);
  if (kind?.homeFolder) {
    const home = await fetchLibrary()
      .then((d) =>
        d.folders.find(
          (f) => f.residency === residency && f.name === kind.homeFolder,
        ),
      )
      .catch(() => undefined);
    if (home)
      await moveLibraryItem(residency, asset.id, home.id).catch(() => {});
  }
  const key = await contentKey(await file.arrayBuffer());
  await syncLinkedLibrary();
  return linkId(prefix, key);
}

/** Shelve a dropped OS file as whichever linked kind claims it and return its
 * id — what a paste or a drop on the editor does with a font or a LUT. */
export async function uploadLinkedFile(file: File): Promise<string> {
  const kind = [...kinds.values()].find((k) => k.matches(file));
  if (!kind) throw new Error("That file is not something the Library links to.");
  return uploadLinkedItem(kind.prefix, file);
}

/** Every linked id a document is set in, across kinds. */
export function linkedIdsIn(doc: ProjectDoc): string[] {
  const ids = new Set<string>();
  for (const kind of kinds.values())
    for (const id of kind.extract(doc)) ids.add(id);
  return [...ids];
}

/**
 * Make sure the cloud shelf holds these linked items, copying any that live
 * only on a device. What a project needs when it moves to the cloud: a render
 * job reads the cloud shelf alone. The ids don't change — they are the bytes —
 * so the document that referenced them still does.
 */
export async function ensureLinkedOnCloud(
  ids: Iterable<string>,
): Promise<void> {
  const wanted = new Set(ids);
  if (wanted.size === 0) return;
  const missing = items.filter(
    (i) =>
      wanted.has(linkId(i.prefix, i.key)) &&
      !i.copies.some((c) => c.residency === "cloud"),
  );
  if (missing.length === 0) return;
  for (const item of missing) {
    const from = item.copies[0];
    if (!from) continue;
    try {
      const res = await backendFor(from.residency).fetch(
        `/api/cut/library/media/${encodeURIComponent(from.fileName)}`,
      );
      if (!res.ok) continue;
      await uploadToLibrary(
        new File([await res.blob()], from.fileName),
        "cloud",
      );
    } catch {
      // An unreachable shelf or a full account: whatever points at it falls
      // back in a job, and the move itself still goes through.
    }
  }
  await syncLinkedLibrary();
}