@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/fonts.ts

@@ -0,0 +1,656 @@
+// FONT PICKS, PLANNED. Pure functions over a document, the Google catalog and
+// the workspace font list: the files each target text layer needs for a pick
+// (its face set), the weight and style it then draws at, the stage preview of
+// a pick, what the Typography rows offer for a selection, and the families a
+// Project already holds. The store's verbs (`applyFont`, `setFontWeight`,
+// `setFontStyle`, `previewFont`, `selfHostFont`, `followFontWeights`) fetch
+// and write what these plan, in one edit.
+//
+// The catalog and its subset ranges are lazy chunks, so every function here
+// takes them already loaded, and answers "loading" where it needs one it was
+// not given.
+import { drawsMachineFont, fontStack, primaryFontFamily } from "@dailies-studio/shot/doc";
+import type { Doc3D, Layer3D, ShotAsset } from "@dailies-studio/shot/doc";
+import {
+  appliesVariableFile,
+  catalogEntryOf,
+  catalogFileOf,
+  categoryFallback,
+  faceWeight,
+  findGoogleFont,
+  googleFacePlan,
+  googleFaceSet,
+  googleFontFileName,
+  googleStyle,
+  nearestWeight,
+  subsetsForText,
+} from "../fonts/googleFonts.js";
+import type { GoogleFace, GoogleFontEntry, GoogleFontRanges, GoogleFontStyle } from "../fonts/googleFonts.js";
+import { workspaceFontUrl } from "../api.js";
+import type { WorkspaceFont } from "../api.js";
+import type { ShotFontPreview, ShotFontPreviewFace } from "../bridgeTypes.js";
+import { storedName } from "./storyboardModel.js";
+
+export type TextLayer = Extract<Layer3D, { kind: "text" }>;
+
+/** What the picker hands the store: one family for the selected text. */
+export type FontPick =
+  /** A Google catalog family: its files are copied from jsDelivr, or reused. */
+  | { kind: "google"; entry: GoogleFontEntry }
+  /** A workspace family: its rows in the workspace font list. */
+  | { kind: "workspace"; family: string; fonts: readonly WorkspaceFont[] }
+  /** A family whose files the Project already holds: nothing is fetched. */
+  | { kind: "project"; family: string; fallback: string; faces: readonly ProjectFace[] };
+
+/** One face of a family the Project holds: the asset ids a layer takes. */
+export interface ProjectFace {
+  fontAsset: string;
+  fontSubsets?: readonly string[];
+  /** A static face's weight. Absent for a variable face, or when unknown. */
+  weight?: number;
+  /** A variable face's `wght` range. */
+  axis?: readonly [number, number];
+  /** Absent when unknown. */
+  italic?: boolean;
+}
+
+/** One file of a face set that may have to be fetched. */
+export interface FaceFile {
+  /** Where the bytes download from; also what dedupes it across layers. */
+  url: string;
+  /** The name it is uploaded as. */
+  name: string;
+  /** Finds a copy the Project already holds, so nothing is fetched. */
+  reuse: (asset: ShotAsset) => boolean;
+  /** Absent for a combined or whole file. */
+  unicodeRange?: string;
+  /** Set for a workspace font, which downloads through its own route. */
+  workspace?: WorkspaceFont;
+  /** Bytes already in hand (an upload's own file): nothing is downloaded. */
+  file?: File | (() => Promise<File>);
+}
+
+/** A file of a face set: one to fetch or reuse, or a Project asset. */
+export type FaceSource = FaceFile | { asset: string };
+
+/** What one target text layer becomes. */
+export interface LayerFontPlan {
+  layerId: string;
+  /** The face set, `fontAsset` first. Empty keeps the layer's own files. */
+  files: readonly FaceSource[];
+  /** The `fontFamily` to write; null keeps the layer's. */
+  fontFamily: string | null;
+  /** The weight the face draws at, written to the layer. */
+  weight: number;
+  /** The style the face is, written to the layer (upright is no key). */
+  style: GoogleFontStyle;
+}
+
+/** What a font write came to. `message` says why for refused and failed,
+ *  and names the locked layers an applied write skipped. */
+export interface FontApplyOutcome {
+  status: "applied" | "refused" | "failed" | "superseded";
+  message?: string;
+}
+
+/** The Font field's in-flight apply (`ShotEditorState.fontApply`). */
+export interface FontApplyProgress {
+  /** The family being applied, as the Font field names it. While a
+   *  workspace upload runs, before the server has named the family, the
+   *  files: "1 font file", "3 font files". */
+  family: string;
+  /** Downloading the face set's files, or copying them into the Project. */
+  phase: "download" | "upload";
+  /** Bytes read across the face set's downloads. */
+  loaded: number;
+  /** Their whole size, or null while any download's size is unknown. */
+  total: number | null;
+  /** Why it failed, or null while it runs. `retryFontApply` runs the same
+   *  apply again on the same layers. */
+  failed: string | null;
+  /** The text layers the write lands on, captured at the call, so the Font
+   *  field shows it only while one of them is selected. */
+  layerIds: readonly string[];
+}
+
+/** A target text layer as an apply reads it at the call. */
+export interface FontTargetLayer {
+  id: string;
+  weight: number;
+  style: GoogleFontStyle;
+  content: string;
+}
+
+export const styleOf = (layer: TextLayer): GoogleFontStyle => layer.text.style.fontStyle ?? "normal";
+
+export const targetOf = (layer: TextLayer): FontTargetLayer => ({
+  id: layer.id,
+  weight: layer.text.style.weight,
+  style: styleOf(layer),
+  content: layer.text.content,
+});
+
+export { fontStack };
+
+const clamp = (value: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, value));
+
+/** What a file says about its face: the weight it holds, or its `wght`
+ *  range, and its slant. Each absent when unknown. */
+export interface FaceFacts {
+  weight?: number;
+  axis?: readonly [number, number];
+  italic?: boolean;
+}
+
+/**
+ * The face a layer that wants `weight` and `style` draws from a family's
+ * files, the browser's way: a file of that style when the family has one,
+ * then the CSS Fonts 4 nearest weight (`nearestWeight`), a variable file
+ * counting as every weight on its axis. Answers the drawn weight and style.
+ * Files that say nothing about themselves (no weight, axis or italic, such as
+ * a font uploaded before its name table was read) keep the layer's own.
+ */
+export function chooseFace<T>(
+  faces: readonly T[],
+  facts: (face: T) => FaceFacts,
+  weight: number,
+  style: GoogleFontStyle,
+): { face: T; weight: number; style: GoogleFontStyle } {
+  const known = faces.filter((face) => {
+    const f = facts(face);
+    return f.weight !== undefined || f.axis !== undefined || f.italic !== undefined;
+  });
+  if (known.length === 0) return { face: faces[0]!, weight, style };
+  const styled = known.filter((face) => (facts(face).italic === true) === (style === "italic"));
+  const pool = styled.length > 0 ? styled : known;
+  const drawn = pool.map((face) => {
+    const { axis, weight: own } = facts(face);
+    return axis === undefined ? (own ?? 400) : clamp(weight, axis[0], axis[1]);
+  });
+  const best = nearestWeight({ weights: drawn }, weight);
+  const face = pool[drawn.indexOf(best)]!;
+  return { face, weight: best, style: facts(face).italic === true ? "italic" : "normal" };
+}
+
+/** A workspace font's facts. A variable file's axis wins over its weight
+ *  class, which only names its default instance. */
+export function workspaceFacts(font: WorkspaceFont): FaceFacts {
+  return {
+    ...(font.wghtAxis !== undefined
+      ? { axis: [font.wghtAxis[0], font.wghtAxis[2]] as const }
+      : font.weight !== undefined
+        ? { weight: font.weight }
+        : {}),
+    ...(font.italic === undefined ? {} : { italic: font.italic }),
+  };
+}
+
+const projectFacts = (face: ProjectFace): FaceFacts => face;
+
+const googleFile = (face: GoogleFace): FaceFile => ({
+  url: face.url,
+  name: face.fileName,
+  // A catalog copy by its stored name, which says family, weight, style and
+  // subset (`catalogFileOf`).
+  reuse: (asset) => asset.kind === "font" && storedName(asset.path) === face.fileName,
+  ...(face.unicodeRange === undefined ? {} : { unicodeRange: face.unicodeRange }),
+});
+
+/**
+ * A Google family on each layer, keeping the layer's weight and style where
+ * the family can draw them (`googleFacePlan`, which the MCP `set_font` op
+ * plans with too): a static family takes the nearest weight's face set and
+ * writes that weight; a variable one takes its `wght` set and keeps the
+ * layer's weight clamped to the axis. A static-only family (CJK) never takes
+ * a variable file (`faceWeight`).
+ */
+export function planGooglePick(
+  entry: GoogleFontEntry,
+  ranges: GoogleFontRanges,
+  layers: readonly FontTargetLayer[],
+): LayerFontPlan[] {
+  const fontFamily = fontStack(entry.family, categoryFallback(entry.category));
+  const sets = new Map<string, FaceFile[]>();
+  return layers.map((layer) => {
+    const plan = googleFacePlan(entry, ranges, layer.weight, layer.style);
+    const key = `${plan.at}:${plan.style}`;
+    let files = sets.get(key);
+    if (files === undefined) {
+      files = plan.faces.map(googleFile);
+      sets.set(key, files);
+    }
+    return { layerId: layer.id, files, fontFamily, weight: plan.weight, style: plan.style };
+  });
+}
+
+/** Inter's upright variable face set from the chrome's own bundled files
+ *  (`BUNDLED_INTER_FILES`): the catalog's file names and ranges, so it is the
+ *  same copy a pick of Inter makes, and the bundle's urls. A subset the
+ *  bundle lacks is left out. */
+export function bundledInterFaceSet(
+  inter: GoogleFontEntry,
+  ranges: GoogleFontRanges,
+  bundled: Readonly<Record<string, string>>,
+): FaceFile[] {
+  return googleFaceSet(inter, ranges, "variable", "normal").flatMap((face) => {
+    const url = bundled[face.subset];
+    return url === undefined ? [] : [{ ...googleFile(face), url }];
+  });
+}
+
+/**
+ * Whether the Project font file at `path` holds the workspace font `font`'s
+ * bytes. Both stores name a file `<hash8>-<safe name>` (`workspaceFontId`,
+ * `storedAssetName`), and a Project upload of bytes it already holds answers
+ * the name it first stored them under, so a copy's path need not be the id.
+ */
+export const isCopyOf = (path: string, font: WorkspaceFont): boolean => path.slice(0, 9) === font.id.slice(0, 9);
+
+const workspaceFile = (font: WorkspaceFont): FaceFile => ({
+  url: workspaceFontUrl(font.id),
+  name: font.filename,
+  reuse: (asset) => asset.kind === "font" && isCopyOf(asset.path, font),
+  workspace: font,
+});
+
+/** A workspace family on each layer: the file of the layer's style (when the
+ *  family has one) nearest its weight, or a variable file covering it. */
+export function planWorkspacePick(
+  family: string,
+  fonts: readonly WorkspaceFont[],
+  layers: readonly FontTargetLayer[],
+): LayerFontPlan[] {
+  const fontFamily = fontStack(family);
+  return layers.map((layer) => {
+    const chosen = chooseFace(fonts, workspaceFacts, layer.weight, layer.style);
+    return { layerId: layer.id, files: [workspaceFile(chosen.face)], fontFamily, weight: chosen.weight, style: chosen.style };
+  });
+}
+
+/** A family the Project holds, on each layer, from its own files. */
+export function planProjectPick(
+  pick: Extract<FontPick, { kind: "project" }>,
+  layers: readonly FontTargetLayer[],
+): LayerFontPlan[] {
+  const fontFamily = fontStack(pick.family, pick.fallback);
+  return layers.map((layer) => {
+    const chosen = chooseFace(pick.faces, projectFacts, layer.weight, layer.style);
+    const files = [chosen.face.fontAsset, ...(chosen.face.fontSubsets ?? [])].map((asset) => ({ asset }));
+    return { layerId: layer.id, files, fontFamily, weight: chosen.weight, style: chosen.style };
+  });
+}
+
+/** The one dispatcher. A Google pick needs the subset ranges loaded. */
+export function planFontPick(
+  pick: FontPick,
+  layers: readonly FontTargetLayer[],
+  ranges: GoogleFontRanges | null,
+): LayerFontPlan[] {
+  switch (pick.kind) {
+    case "google":
+      if (ranges === null) throw new RangeError("A Google font is planned with the subset ranges loaded.");
+      return planGooglePick(pick.entry, ranges, layers);
+    case "workspace":
+      return planWorkspacePick(pick.family, pick.fonts, layers);
+    case "project":
+      return planProjectPick(pick, layers);
+  }
+}
+
+/** The family a pick puts on text, as the Font field names it. */
+export function pickFamily(pick: FontPick): string {
+  return pick.kind === "google" ? pick.entry.family : pick.family;
+}
+
+const assetUrl = (path: string): string => `/studio/assets/${encodeURIComponent(path)}`;
+
+/**
+ * The stage preview of a pick on `layers` (bridge v50). The face is the one
+ * the apply would give the FIRST layer (its weight and style rule), and only
+ * the layers the apply gives that same face show it: one preview family holds
+ * one face, which the stage would draw for any style a layer asks for, so a
+ * mixed selection's other layers keep their own font during the hover rather
+ * than show a face the apply will not give them. A Google family loads only
+ * the subsets those layers' text needs. Null with no layers.
+ */
+export function fontPreviewOf(
+  pick: FontPick,
+  containerId: string,
+  layers: readonly FontTargetLayer[],
+  ranges: GoogleFontRanges | null,
+  assets: Doc3D["assets"],
+): ShotFontPreview | null {
+  const first = layers[0];
+  if (first === undefined) return null;
+  const sameFace = (key: (layer: FontTargetLayer) => string): FontTargetLayer[] =>
+    layers.filter((layer) => key(layer) === key(first));
+  if (pick.kind === "google") {
+    if (ranges === null) throw new RangeError("A Google font is previewed with the subset ranges loaded.");
+    const { entry } = pick;
+    const style = googleStyle(entry, first.style);
+    const at = faceWeight(entry, first.weight);
+    const shown = sameFace((layer) => `${faceWeight(entry, layer.weight)}:${googleStyle(entry, layer.style)}`);
+    const wanted = subsetsForText(entry, ranges, shown.map((layer) => layer.content).join("\n"));
+    const axis = entry.axes?.["wght"];
+    return {
+      containerId,
+      layerIds: shown.map((layer) => layer.id),
+      family: entry.family,
+      fallback: categoryFallback(entry.category),
+      style,
+      weightRange: at === "variable" && axis !== undefined ? [axis[0], axis[1]] : [1, 1000],
+      faces: googleFaceSet(entry, ranges, at, style)
+        .filter((face) => wanted.includes(face.subset))
+        .map((face) => ({ url: face.url, ...(face.unicodeRange === undefined ? {} : { unicodeRange: face.unicodeRange }) })),
+    };
+  }
+  if (pick.kind === "workspace") {
+    const faceOf = (layer: FontTargetLayer) => chooseFace(pick.fonts, workspaceFacts, layer.weight, layer.style);
+    const chosen = faceOf(first);
+    const axis = workspaceFacts(chosen.face).axis;
+    return {
+      containerId,
+      layerIds: sameFace((layer) => {
+        const face = faceOf(layer);
+        return `${face.face.id}:${face.style}`;
+      }).map((layer) => layer.id),
+      family: pick.family,
+      fallback: "sans-serif",
+      style: chosen.style,
+      weightRange: axis === undefined ? [1, 1000] : axis,
+      faces: [{ url: workspaceFontUrl(chosen.face.id) }],
+    };
+  }
+  const faceOf = (layer: FontTargetLayer) => chooseFace(pick.faces, projectFacts, layer.weight, layer.style);
+  const chosen = faceOf(first);
+  const faces: ShotFontPreviewFace[] = [];
+  for (const id of [chosen.face.fontAsset, ...(chosen.face.fontSubsets ?? [])]) {
+    const asset = assets[id];
+    if (asset?.kind !== "font") continue;
+    faces.push({ url: assetUrl(asset.path), ...(asset.unicodeRange === undefined ? {} : { unicodeRange: asset.unicodeRange }) });
+  }
+  return {
+    containerId,
+    layerIds: sameFace((layer) => {
+      const face = faceOf(layer);
+      return `${face.face.fontAsset}:${face.style}`;
+    }).map((layer) => layer.id),
+    family: pick.family,
+    fallback: pick.fallback,
+    style: chosen.style,
+    weightRange: chosen.face.axis ?? [1, 1000],
+    faces,
+  };
+}
+
+// ── What the Typography rows offer ─────────────────────────────────────────
+
+/** What a text layer's family can draw, for the Weight and Italic rows and
+ *  the machine-font note. */
+export type LayerFontFacts =
+  /** Its file is a catalog copy, or it draws a machine font, and the catalog
+   *  was not handed in yet. */
+  | { kind: "loading" }
+  /** A Google family. `axis` is set when it applies `wght` files (a number
+   *  field clamped to it); else `weights` is the named list. */
+  | {
+      kind: "catalog";
+      family: string;
+      entry: GoogleFontEntry;
+      weights: readonly number[];
+      axis: readonly [number, number] | null;
+      italic: boolean;
+    }
+  /** A workspace family, `fonts` its rows. `axis` is the variable file's range
+   *  for the layer's style when the family has one. */
+  | {
+      kind: "workspace";
+      family: string;
+      fonts: readonly WorkspaceFont[];
+      weights: readonly number[];
+      axis: readonly [number, number] | null;
+      italic: boolean;
+    }
+  /** Another file (an upload, a copy the workspace list no longer has, or
+   *  the list not handed in): any weight, and italic as the file draws it. */
+  | { kind: "file"; family: string }
+  /** No file: the computer's font. `selfHost` is the catalog family "Self-host
+   *  <family>" applies (`selfHostFont`), or null ("Upload font file"). */
+  | { kind: "machine"; family: string; selfHost: GoogleFontEntry | null };
+
+/** The workspace family a font row belongs to: rows that share its family. */
+export const workspaceFamilyOf = (fonts: readonly WorkspaceFont[], font: WorkspaceFont): WorkspaceFont[] =>
+  fonts.filter((f) => f.family === font.family);
+
+/** The facts of one text layer. `catalog` and `workspace` are what is loaded,
+ *  or null. */
+export function fontFactsOf(
+  layer: TextLayer,
+  assets: Doc3D["assets"],
+  catalog: readonly GoogleFontEntry[] | null,
+  workspace: readonly WorkspaceFont[] | null,
+): LayerFontFacts {
+  const style = layer.text.style;
+  const family = primaryFontFamily(style.fontFamily);
+  if (drawsMachineFont(layer, assets)) {
+    return catalog === null ? { kind: "loading" } : { kind: "machine", family, selfHost: findGoogleFont(catalog, family) ?? null };
+  }
+  const asset = style.fontAsset === undefined ? undefined : assets[style.fontAsset];
+  if (asset === undefined) return { kind: "file", family };
+  const own = workspace?.find((font) => isCopyOf(asset.path, font));
+  if (own !== undefined && workspace !== null) {
+    const fonts = workspaceFamilyOf(workspace, own);
+    const italic = (style.fontStyle ?? "normal") === "italic";
+    // The weights of the layer's own style when the family has files in it:
+    // an italic cut only at 400 offers 400 on italic text, so the menu never
+    // names a weight the apply would draw from the upright file.
+    const inStyle = fonts.filter((f) => (f.italic === true) === italic);
+    const pool = inStyle.length > 0 ? inStyle : fonts;
+    const weights = [...new Set(pool.flatMap((f) => (f.wghtAxis === undefined && f.weight !== undefined ? [f.weight] : [])))];
+    const variable = pool.find((f) => f.wghtAxis !== undefined) ?? fonts.find((f) => f.wghtAxis !== undefined);
+    return {
+      kind: "workspace",
+      family: own.family,
+      fonts,
+      weights: weights.sort((a, b) => a - b),
+      axis: variable === undefined ? null : workspaceFacts(variable).axis!,
+      // Whether the apply draws italic (`chooseFace`): files that say nothing
+      // about their slant keep the layer's style, so they can.
+      italic: chooseFace(fonts, workspaceFacts, style.weight, "italic").style === "italic",
+    };
+  }
+  const file = catalogFileOf(asset.path);
+  if (file === null) return { kind: "file", family };
+  if (catalog === null) return { kind: "loading" };
+  const entry = catalogEntryOf(catalog, family, file);
+  if (entry === undefined) return { kind: "file", family };
+  const axis = entry.axes?.["wght"];
+  return {
+    kind: "catalog",
+    family: entry.family,
+    entry,
+    weights: entry.weights,
+    axis: appliesVariableFile(entry) && axis !== undefined ? [axis[0], axis[1]] : null,
+    italic: entry.styles.includes("italic"),
+  };
+}
+
+const fold = (family: string): string => family.toLowerCase().replace(/\s+/gu, " ").trim();
+
+/**
+ * The facts the Typography rows render for a selection: the selected text
+ * layers' family when they share one, `mixed` when they do not, `loading`
+ * while any of them waits on the catalog, null with no text layer selected.
+ */
+export function selectionFontFacts(
+  layers: readonly Layer3D[],
+  assets: Doc3D["assets"],
+  catalog: readonly GoogleFontEntry[] | null,
+  workspace: readonly WorkspaceFont[] | null,
+): LayerFontFacts | { kind: "mixed" } | null {
+  const facts = layers
+    .filter((layer): layer is TextLayer => layer.kind === "text")
+    .map((layer) => fontFactsOf(layer, assets, catalog, workspace));
+  const first = facts[0];
+  if (first === undefined) return null;
+  if (facts.some((f) => f.kind === "loading")) return { kind: "loading" };
+  const key = (f: LayerFontFacts): string => (f.kind === "loading" ? "" : `${f.kind}:${fold(f.family)}`);
+  return facts.every((f) => key(f) === key(first)) ? first : { kind: "mixed" };
+}
+
+// ── In this Project ────────────────────────────────────────────────────────
+
+/** One family the Project holds files for, listed once. */
+export interface ProjectFontFamily {
+  /** `family` case-folded: what makes two sources one row. */
+  key: string;
+  family: string;
+  /** Where its first files came from. */
+  source: "catalog" | "workspace" | "file";
+  /** Re-applies it from the Project's own files, with no fetch. */
+  pick: Extract<FontPick, { kind: "project" }>;
+}
+
+export interface ProjectFonts {
+  /** By family name. */
+  families: ProjectFontFamily[];
+  /** Families text layers name with no file (`drawsMachineFont`), by name,
+   *  leaving out one the Project also holds files for. */
+  machine: { key: string; family: string }[];
+}
+
+/** Every text layer in the document: each Shot's, then each component's. */
+function textLayersOf(doc: Doc3D): TextLayer[] {
+  return [...Object.values(doc.scenesById), ...Object.values(doc.components ?? {})].flatMap((home) =>
+    Object.values(home.layersById).filter((layer): layer is TextLayer => layer.kind === "text"),
+  );
+}
+
+/** A file name's stem as a family: `BrandSerif-Regular.woff2` reads
+ *  "BrandSerif Regular". */
+const stemFamily = (path: string): string =>
+  storedName(path).replace(/\.[^.]*$/u, "").replace(/[-_]+/gu, " ").trim() || "Font";
+
+/**
+ * The families a Project already holds files for, each once (case-folded):
+ * catalog copies grouped by their catalog family (one face per weight and
+ * style, its subsets together), workspace copies by the workspace list's
+ * family, then every other font asset by the brand row that names it, else
+ * its file stem. Each comes with the pick that re-applies it from those
+ * files. Without the catalog, a catalog copy's family is the one a text layer
+ * names for it, else its file name's.
+ */
+export function projectFontFamilies(
+  doc: Doc3D,
+  catalog: readonly GoogleFontEntry[] | null,
+  workspace: readonly WorkspaceFont[] | null,
+): ProjectFonts {
+  const assets = Object.values(doc.assets).filter((asset) => asset.kind === "font");
+  // Workspace fonts by the `<hash8>-` their copies share (`isCopyOf`).
+  const byHash = new Map((workspace ?? []).map((font) => [font.id.slice(0, 9), font]));
+  const workspaceOf = (asset: ShotAsset): WorkspaceFont | undefined => byHash.get(asset.path.slice(0, 9));
+  // The catalog by the file-name spelling of its family, read back through
+  // the same two helpers that write and parse a catalog file's name.
+  const bySafe = new Map(
+    (catalog ?? []).map((entry) => [catalogFileOf(googleFontFileName(entry, "variable"))!.safeFamily, entry]),
+  );
+  const layers = textLayersOf(doc);
+  const usedAs = new Map<string, string>();
+  for (const layer of layers) {
+    const id = layer.text.style.fontAsset;
+    if (id !== undefined && !usedAs.has(id)) usedAs.set(id, primaryFontFamily(layer.text.style.fontFamily));
+  }
+  const branded = new Map<string, string>();
+  for (const scope of [doc.resources, ...Object.values(doc.scenesById).map((scene) => scene.resources)]) {
+    for (const item of scope?.branding ?? []) {
+      if (item.type === "asset" && item.fontFamily !== undefined && !branded.has(item.asset)) {
+        branded.set(item.asset, primaryFontFamily(item.fontFamily) || item.fontFamily);
+      }
+    }
+  }
+  const rows = new Map<string, ProjectFontFamily & { faces: ProjectFace[] }>();
+  const add = (family: string, source: ProjectFontFamily["source"], fallback: string, face: ProjectFace): void => {
+    const key = fold(family);
+    let row = rows.get(key);
+    if (row === undefined) {
+      const faces: ProjectFace[] = [];
+      row = { key, family, source, faces, pick: { kind: "project", family, fallback, faces } };
+      rows.set(key, row);
+    }
+    row.faces.push(face);
+  };
+  // Catalog copies: one face per (family, weight, style), the default subset
+  // first.
+  const catalogFaces = new Map<string, { entry: GoogleFontEntry | undefined; family: string; files: ShotAsset[] }>();
+  const rest: ShotAsset[] = [];
+  for (const asset of assets) {
+    const file = workspaceOf(asset) !== undefined ? null : catalogFileOf(asset.path);
+    if (file === null) {
+      rest.push(asset);
+      continue;
+    }
+    const entry = bySafe.get(file.safeFamily);
+    const faceKey = `${file.safeFamily}:${file.weight}:${file.style}`;
+    const held = catalogFaces.get(faceKey);
+    if (held !== undefined) {
+      held.files.push(asset);
+      continue;
+    }
+    const family = entry?.family ?? usedAs.get(asset.id) ?? file.safeFamily.replace(/-/gu, " ");
+    catalogFaces.set(faceKey, { entry, family, files: [asset] });
+  }
+  for (const { entry, family, files } of catalogFaces.values()) {
+    const parsed = files.map((asset) => ({ asset, file: catalogFileOf(asset.path)! }));
+    const order = entry === undefined ? [] : [entry.defSubset, ...entry.subsets];
+    // The file with no subset suffix is the default subset's, catalog or not;
+    // a subset the catalog does not list goes last.
+    const rank = (subset: string | undefined): number => {
+      if (subset === undefined) return -1;
+      const at = order.indexOf(subset);
+      return at < 0 ? order.length : at;
+    };
+    parsed.sort((a, b) => rank(a.file.subset) - rank(b.file.subset));
+    const [head, ...others] = parsed;
+    const { weight, style } = head!.file;
+    const axis = entry?.axes?.["wght"];
+    add(family, "catalog", entry === undefined ? "sans-serif" : categoryFallback(entry.category), {
+      fontAsset: head!.asset.id,
+      ...(others.length === 0 ? {} : { fontSubsets: others.map((o) => o.asset.id) }),
+      ...(weight === "variable" ? { axis: axis === undefined ? ([1, 1000] as const) : ([axis[0], axis[1]] as const) } : { weight }),
+      italic: style === "italic",
+    });
+  }
+  for (const asset of rest) {
+    const font = workspaceOf(asset);
+    if (font !== undefined) add(font.family, "workspace", "sans-serif", { fontAsset: asset.id, ...workspaceFacts(font) });
+  }
+  for (const asset of rest) {
+    if (workspaceOf(asset) !== undefined) continue;
+    add(branded.get(asset.id) ?? stemFamily(asset.path), "file", "sans-serif", { fontAsset: asset.id });
+  }
+  const families = [...rows.values()]
+    .map(({ faces: _faces, ...row }) => row)
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  const machine = new Map<string, string>();
+  for (const layer of layers) {
+    if (!drawsMachineFont(layer, doc.assets)) continue;
+    const family = primaryFontFamily(layer.text.style.fontFamily);
+    const key = fold(family);
+    if (key.length > 0 && !rows.has(key) && !machine.has(key)) machine.set(key, family);
+  }
+  return {
+    families,
+    machine: [...machine].map(([key, family]) => ({ key, family })).sort((a, b) => (a.key < b.key ? -1 : 1)),
+  };
+}
+
+/** The other character-set files the Project holds for the face whose
+ *  default file is `assetId`, or undefined when it has none: what a write
+ *  that sets `fontAsset` to it sets as `fontSubsets`. */
+export function projectSubsetsOf(doc: Doc3D, assetId: string): readonly string[] | undefined {
+  for (const family of projectFontFamilies(doc, null, null).families) {
+    const face = family.pick.faces.find((f) => f.fontAsset === assetId);
+    if (face !== undefined) return face.fontSubsets;
+  }
+  return undefined;
+}