@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/exportWorker.ts

@@ -0,0 +1,9 @@
+// The shot stage's encode worker file: spawned by tier1Export.ts, served
+// through the project's Vite with mediabunny pinned to the studio's copy
+// (cli/src/pins.ts) — the same treatment the motion harness's worker gets.
+// The whole worker lives in @dailies-studio/shot/tier1; this file exists
+// because a Worker needs a URL of its own.
+import { bootExportWorker } from "@dailies-studio/shot/tier1/workerEntry";
+import type { WorkerScope } from "@dailies-studio/shot/tier1";
+
+bootExportWorker(self as unknown as WorkerScope);

package/src/stage/feed.ts

@@ -26,11 +26,60 @@
 // COORDINATES ARE PANE-LOCAL CSS px, from the pane's top-left. `paneAt` returns
 // exactly that pairing, so the caller passes through what it was handed and
 // there is no second place where a pane origin gets subtracted.
-import type { Camera, Matrix4, Ray } from "three";
-import type { GestureKind, ResizeHandle } from "@dailies-studio/shot/doc";
+import type { Camera, Matrix4, Ray, Vector3 } from "three";
+import type { CameraGate, GestureKind, ResizeHandle } from "@dailies-studio/shot/doc";
 import type { StagePane } from "./panes.js";
 import type { GizmoGrab } from "./gizmoMath.js";
 import type { LayerFrame, ScreenQuad, WorldQuad } from "./project.js";
+import type { ShotPeerSelection } from "../bridgeTypes.js";
+import type { ScreenMotionPath } from "./motionPathStage.js";
+import type { Vec3 } from "@dailies-studio/engine";
+
+/** Another person's selected layer in one pane (bridge v43). `tag` on the
+ *  first of their layers only; `ring` when this author selected it too, so
+ *  theirs draws around ours instead of under it (page 21). */
+export interface PeerQuad {
+  quad: ScreenQuad;
+  name: string;
+  color: string;
+  tag: boolean;
+  ring: boolean;
+}
+
+/** Other people's selections projected into one pane. */
+export function projectPeers(
+  peers: readonly ShotPeerSelection[],
+  quadFor: (pane: StagePane, layerId: string) => ScreenQuad | null,
+  pane: StagePane,
+  mine: readonly string[],
+): PeerQuad[] {
+  if (peers.length === 0) return [];
+  const own = new Set(mine);
+  const out: PeerQuad[] = [];
+  for (const peer of peers) {
+    let tag = true;
+    for (const id of peer.ids) {
+      const quad = quadFor(pane, id);
+      if (quad === null) continue;
+      out.push({ quad, name: peer.name, color: peer.color, tag, ring: own.has(id) });
+      tag = false;
+    }
+  }
+  return out;
+}
+
+/** A failed layer's outline in one pane, and the name its placeholder says. */
+export interface FailedQuad {
+  quad: ScreenQuad;
+  label: string;
+}
+
+/** A selected mask's outline in one pane (gap 7). `round` for an ellipse
+ *  mask, whose outline is the ellipse inscribed in its quad. */
+export interface MaskQuad {
+  quad: ScreenQuad;
+  round: boolean;
+}
 
 /** What a press on the current selection turned out to be. */
 export interface Grab {
@@ -87,9 +136,16 @@ export interface StageFeed {
    * the graph's SHAPE — the matrices inside it are live references, so motion
    * needs no invalidation and neither does a seek that only moves things. What
    * it cannot see is membership, and membership changes for a reason no
-   * document value predicts: a GLB or an instance module resolves and suspense
-   * commits a subtree that was not there a frame ago. This counter is that
-   * event, and it is what lets the walk be memoised across an orbit.
+   * document value predicts: a GLB resolves and suspense commits a subtree that
+   * was not there a frame ago. This counter is that event, and it is what lets
+   * the walk be memoised across an orbit.
+   *
+   * It moves on a layer group mounting or going (`onLayerGraph`) and on a
+   * model reporting (`pushMeshStats`), and on NOTHING ELSE: not on a cut,
+   * which only re-parents a resident Shot's group, and not on what a code
+   * component renders under its mounted layer (its module landing, its own
+   * Suspense, a child it draws on a prop). A walk that needs those (the
+   * inside-out shells) walks per draw.
    */
   sceneEpoch: number;
   /**
@@ -104,6 +160,13 @@ export interface StageFeed {
    * quad re-renders one SVG and zero canvases.
    */
   onOverlay: (() => void) | null;
+  /** True while the pen holds points. Its preview is projected through
+   *  `paneAt` at render time, so the in-canvas half then also calls
+   *  `onOverlay` when the frame pane's camera moves (`cameraPose`, the last
+   *  projection and view matrices it saw), with no pointer move to cause it:
+   *  the Shot camera, or inside a definition its working camera. */
+  penLive: boolean;
+  cameraPose: number[] | null;
   /** The CURRENT selection, in the order both quad arrays are parallel to. One
    *  list for both panes: the selection is one selection, only its projection
    *  differs. */
@@ -113,6 +176,8 @@ export interface StageFeed {
    *  overlay drawn from last layout's numbers is worse than no overlay. */
   quadsCamera: ScreenQuad[];
   quadsWorking: ScreenQuad[];
+  /** Non-rendering spline drivers remain visible as working-pane guides. */
+  splineGuidesWorking: Array<{ id: string; pts: readonly number[]; selected: boolean }>;
   /** Parallel to `ids`: is each selected layer locked? Written here rather than
    *  looked up by the overlay because `collectFrames` is the one place that
    *  already knows, and a second lookup could disagree with the `grabAt` that
@@ -150,6 +215,15 @@ export interface StageFeed {
    * raycasting, projection, `renderBins` — takes the base class already.
    */
   workingCamera: Camera | null;
+  /**
+   * Pose and return the working camera for the current committed view.
+   *
+   * The normal caller is StageTools' priority-0 frame callback. SplitRenderer
+   * also calls it from ClockDriver's compile barrier, before that callback has
+   * run, so the programs compiled for a new view are the ones its first draw
+   * will actually use.
+   */
+  prepareWorkingCamera: (() => Camera | null) | null;
   /** Ray-pick at a point in the pane's own CSS px. Front-most first, where
    *  "front-most" is paint order in the camera pane and nearest in the working
    *  one. Null until the canvas exists; empty for a pane that is not on
@@ -169,6 +243,71 @@ export interface StageFeed {
    * selects. A second walk here would be that bug.
    */
   hoverQuad: ((pane: StagePane, x: number, y: number) => ScreenQuad | null) | null;
+  /**
+   * The layer the CHROME is pointing at — a timeline row under the cursor — or
+   * null. Written imperatively by the bridge's `hoverLayer` sink, NEVER
+   * through React state: under `frameloop="never"` every stage commit is a GL
+   * draw, and a row-hover must cost one SVG leaf repaint and zero draws.
+   */
+  hintId: string | null;
+  /**
+   * `hintId`'s outline, projected per pane. Kept fresh two ways, and both are
+   * needed: the sink seeds it at write time (an idle stage runs no frame
+   * between the hover and the paint), and `StageTools`' frame run re-projects
+   * it (a camera move slides the outline with the layer).
+   */
+  hintCamera: ScreenQuad | null;
+  hintWorking: ScreenQuad | null;
+  /**
+   * The layers of the pieces the runtime isolated (pieceFailures.ts), and the
+   * one line the overlay says about them, or null with nothing failed. Written
+   * imperatively by StageApp's `onPieceFailures` sink, like `hintId`: a
+   * failure arrives from inside the apply pass, and a stage commit there would
+   * be a second GL draw for a line of SVG.
+   */
+  failedIds: readonly string[];
+  /** Each failed layer's Layers panel label, for the placeholder's line. */
+  failedLabels: ReadonlyMap<string, string>;
+  failureText: string | null;
+  /**
+   * `failedIds`' outlines, projected per pane by `StageTools`' frame run, so
+   * the placeholder follows its layer through a camera move. A layer the
+   * runtime left out entirely has no group to outline; the bar names it.
+   */
+  failedCamera: FailedQuad[];
+  failedWorking: FailedQuad[];
+  /**
+   * THE MASK OF A SELECTED MASK GROUP (gap 7, Paper page 25): the dashed
+   * outline of the matte that cuts what the author selected, per pane. A mask
+   * that is itself selected has its selection outline instead. Projected by
+   * `StageTools`' frame run from the selection and the document, so it needs
+   * no bridge message.
+   */
+  maskCamera: MaskQuad[];
+  maskWorking: MaskQuad[];
+  /**
+   * OTHER PEOPLE'S SELECTIONS (bridge v43), as the chrome pushed them, and
+   * their outlines projected per pane by the same frame run, so a peer's
+   * outline follows its layer through a camera move. Paint only.
+   */
+  peerSel: readonly ShotPeerSelection[];
+  peersCamera: PeerQuad[];
+  peersWorking: PeerQuad[];
+  /**
+   * The layer the open Studio comment is pinned to (bridge v45, S5), and its
+   * outline in the camera pane, projected by the same frame run that projects
+   * `failedIds`, so the dashed ring rides the layer. Written by StageApp; null with no
+   * open pin on a layer in view.
+   */
+  pinLayerId: string | null;
+  pinLayerCamera: ScreenQuad | null;
+  /**
+   * Project ONE layer's outline in a pane, by id. `hoverQuad`'s sibling —
+   * same closure family, registered by `StageTools` per frame run and
+   * pull-based, so it stays answerable while the stage is idle. The hover
+   * sink is its one caller.
+   */
+  quadForLayer: ((pane: StagePane, layerId: string) => ScreenQuad | null) | null;
   /** Marquee, in the same coordinates. */
   pickRect:
     | ((pane: StagePane, rect: { x0: number; y0: number; x1: number; y1: number }) => string[])
@@ -183,6 +322,13 @@ export interface StageFeed {
    *  no ray, and answering with the other pane's would silently drag the layer
    *  along a plane the author is not looking at. */
   rayAt: ((pane: StagePane, x: number, y: number) => Ray | null) | null;
+  /** `rayAt`'s inverse for the z = 0 design plane: a design point (centre
+   *  origin, y down) into the pane's own CSS px, through the camera that pane
+   *  renders. Null where `rayAt` is. */
+  paneAt: ((pane: StagePane, design: readonly [number, number]) => [number, number] | null) | null;
+  /** A WORLD point into the pane's own CSS px. No near-plane clip, so only for
+   *  points known to be in front of the camera (a dragged dot's guide). */
+  worldToPane: ((pane: StagePane, world: Vector3) => [number, number] | null) | null;
   /**
    * Did a press in the WORKING pane land on the shot camera's frustum gizmo,
    * and on which part?
@@ -191,32 +337,140 @@ export interface StageFeed {
    * frustum gizmo IS the camera pane's camera, drawn as an object. It cannot
    * appear inside the view it represents.
    */
-  frustumHit: ((x: number, y: number) => "body" | "apex" | null) | null;
+  frustumHit: ((x: number, y: number) => "body" | "frame" | null) | null;
+  /**
+   * Did a press in the WORKING pane land on a waypoint of the PATH MOVE under
+   * the playhead, and on which one?
+   *
+   * No pane argument and no shot id, for `frustumHit`'s reasons: the marks are
+   * drawn in the working pane alone, and the move they belong to is the one the
+   * camera is currently in — the same rule the frustum itself follows. Null when
+   * the playhead is not inside a path move, so a press falls straight through to
+   * the frustum and then to the orbit.
+   */
+  waypointHit: ((x: number, y: number) => number | null) | null;
+  /** Which waypoint the pointer is over, or null. `hoverFrustum`'s twin,
+   *  written by the pointer lane and read in the frame loop. */
+  hoverWaypoint: number | null;
+  /**
+   * The selected layers' motion paths (gap 3), per pane, projected by
+   * `StageTools` in the frame pass. Empty when the `motionPaths` pref is off
+   * or the stage is playing, watching, exporting or in another gesture.
+   */
+  motionPathsCamera: readonly ScreenMotionPath[];
+  motionPathsWorking: readonly ScreenMotionPath[];
+  /** The motion path key dot under a point in a pane, or null. Registered by
+   *  `StageTools` beside the paths it answers for. */
+  pathKeyHit: ((pane: StagePane, x: number, y: number) => PathKeyRef | null) | null;
+  /** The selected dot's Bezier handle tip under a point (schema v40), or null.
+   *  Asked before `pathKeyHit`: a handle drawn over a dot is the one shown. */
+  pathHandleHit: ((pane: StagePane, x: number, y: number) => PathHandleRef | null) | null;
+  /** A key dot's world point and its layer's parent `matrixWorld` (copies),
+   *  for the drag's plane and its world-to-parent delta. Null when the key
+   *  is not drawn this frame. */
+  pathKeyAnchor: ((layerId: string, keyId: string) => PathKeyAnchor | null) | null;
+  /** The dot, or the selected dot's handle (with its `part`), the pointer is
+   *  over. Written by the pointer lane. */
+  hoverPathKey: PathKeyRef | PathHandleRef | null;
+  /** The dot or handle being dragged, so it keeps its hover ring under the cursor. */
+  activePathKey: PathKeyRef | PathHandleRef | null;
+  /** The dot last pressed: the one whose Bezier handles show. Stage-local,
+   *  cleared by the frame pass once that key is no longer drawn. */
+  selectedPathKey: PathKeyRef | null;
   /**
-   * Did a press in the WORKING pane land on one of the selection's three drag
-   * arms, and on which?
+   * Did a press in the WORKING pane land on one of the transform gizmo's
+   * handles, and on which?
    *
    * No pane argument, for `frustumHit`'s reason: the gizmo is drawn in the
    * working pane alone (the camera pane has resize handles, which the working
    * pane deliberately does not — see `grabAt`).
    *
-   * The answer carries the arm's ORIGIN AND DIRECTION as a snapshot rather
+   * The answer carries the handle's ORIGIN AND DIRECTION as a snapshot rather
    * than a live reference: the gizmo re-centres on the selection every frame,
    * and an axis line that moved with the layer being dragged along it would
    * chase its own translation.
    */
   gizmoHit: ((x: number, y: number) => GizmoGrab | null) | null;
   /**
-   * The arm the pointer is over, or null.
+   * The handle the pointer is over, or null.
    *
    * WRITTEN BY THE POINTER LANE, READ INSIDE THE FRAME LOOP, which is what
-   * keeps a hover off React entirely: `MoveGizmo` already runs at priority 0
-   * and re-colours a material there, so highlighting costs one uniform write
+   * keeps a hover off React entirely: `TransformGizmo` already runs at priority
+   * 0 and re-colours a material there, so highlighting costs one uniform write
    * per frame and zero renders. Blender's gizmos highlight under the cursor and
    * ours did not, which is the difference between "is this grabbable" being
    * obvious and being something the author finds out by trying.
    */
-  hoverArm: GizmoGrab["axis"] | null;
+  hoverHandle: GizmoGrab["handle"] | null;
+  /**
+   * The handle a drag is currently HELD BY, or null.
+   *
+   * Its twin above, on the other side of the press. Blender dims the rest of
+   * the widget once a transform is running, and the reason is not decoration:
+   * the handles are drawn on top of the thing being moved, so a full-strength
+   * gizmo is three more lines crossing exactly the geometry the author is
+   * trying to judge. Written by the pointer lane at the press and cleared at
+   * the release, read by the draw pass.
+   */
+  activeHandle: GizmoGrab["handle"] | null;
+  /**
+   * Which part of the shot camera's gizmo the pointer is over, or null.
+   *
+   * `hoverArm`'s twin, written and read the same way and for the same reason:
+   * the camera BODY and the framed rectangle's border are the two camera grips
+   * there are (both pan), and neither of them said anything back until the
+   * author pressed.
+   */
+  hoverFrustum: "body" | "frame" | null;
+  /**
+   * Is a component driving the render camera this frame, off the rig?
+   *
+   * Written by `FrustumGizmo`, which reads the camera after every writer, and
+   * read by `TransformGizmo` one frame later: a driven camera has no rig to
+   * hang arms on, and dragging the rig would move nothing the picture shows.
+   */
+  cameraDriven: boolean;
+  /**
+   * The driven camera's WORLD: where the component's content is and how big,
+   * in world units, or null while the document's rig draws. Written by
+   * `FrustumGizmo` (the claim's extent, or the live bounds it measured), read
+   * by the working pane's fitter so Home frames the component's world rather
+   * than an empty canvas thousands of units away.
+   */
+  cameraWorld: { centre: readonly [number, number, number]; extent: number } | null;
+  /**
+   * What a camera write would do at the playhead (bridge v29), mirrored from
+   * the chrome for the frame loops: the gizmo dims when it is not `free`, and
+   * the pointer lane refuses the press with the gate's own sentence rather
+   * than after the drag. Null when no document is open.
+   */
+  cameraGate: CameraGate | null;
+}
+
+/** One key on one layer's Position track. */
+export interface PathKeyRef {
+  layerId: string;
+  keyId: string;
+}
+
+/** One of a key's two Bezier handles (schema v40). */
+export interface PathHandleRef extends PathKeyRef {
+  part: "in" | "out";
+}
+
+export interface PathKeyAnchor {
+  world: Vector3;
+  parent: Matrix4;
+  /** The key's frame, in its track's own frames. */
+  frame: number;
+  /** Where the dot is drawn, parent-local design px (+y down). */
+  point: Vec3;
+  /** The keys either side of it, for ctrl's snap. */
+  neighbours: Vec3[];
+  /** Its Bezier handles as the sampler reads them, offsets from `point`.
+   *  Absent off the bezier arm and on the side no segment uses. */
+  spatialIn?: Vec3;
+  spatialOut?: Vec3;
 }
 
 export function createStageFeed(): StageFeed {
@@ -224,20 +478,57 @@ export function createStageFeed(): StageFeed {
     version: 0,
     sceneEpoch: 0,
     onOverlay: null,
+    penLive: false,
+    cameraPose: null,
     ids: [],
     quadsCamera: [],
     quadsWorking: [],
+    splineGuidesWorking: [],
     locked: [],
     union: null,
     frames: null,
     workingCamera: null,
+    prepareWorkingCamera: null,
     pick: null,
     hoverQuad: null,
+    hintId: null,
+    hintCamera: null,
+    hintWorking: null,
+    failedIds: [],
+    failedLabels: new Map(),
+    failureText: null,
+    failedCamera: [],
+    failedWorking: [],
+    maskCamera: [],
+    maskWorking: [],
+    peerSel: [],
+    peersCamera: [],
+    peersWorking: [],
+    pinLayerId: null,
+    pinLayerCamera: null,
+    quadForLayer: null,
     pickRect: null,
     grabAt: null,
     rayAt: null,
+    paneAt: null,
+    worldToPane: null,
     frustumHit: null,
+    waypointHit: null,
+    hoverWaypoint: null,
+    motionPathsCamera: [],
+    motionPathsWorking: [],
+    pathKeyHit: null,
+    pathHandleHit: null,
+    pathKeyAnchor: null,
+    hoverPathKey: null,
+    activePathKey: null,
+    selectedPathKey: null,
     gizmoHit: null,
-    hoverArm: null,
+    hoverHandle: null,
+    activeHandle: null,
+    hoverFrustum: null,
+    cameraDriven: false,
+    cameraWorld: null,
+    cameraGate: null,
   };
 }

package/src/stage/fontPreview.ts

@@ -0,0 +1,176 @@
+// THE FONT PREVIEW (bridge v50): the font picker's hovered or arrowed-to family
+// drawn on some text layers, without a document write.
+//
+// Two halves. `fontPreviewDoc` derives the document the RUNTIME draws, and only
+// the runtime: every other reader on the stage (picking, the overlays, the
+// inline editor, the auto-width measure the store writes, stills, coverage,
+// health and every export) keeps the real one. `createFontPreviewFaces` loads
+// the preview's files under ONE private family per preview, and adds them to
+// the page's font set only once they have loaded: a face still loading would
+// hold `document.fonts.ready`, which the runtime's own font claim awaits. A
+// face that fails reports nothing; the layers keep the fallback.
+import { browserFontPlatform } from "@dailies-studio/shot";
+import type { FontPlatform } from "@dailies-studio/shot";
+import { FONT_SUBSETS_MAX, quoteFontFamily, unicodeRangeProblem } from "@dailies-studio/shot/doc";
+import type { Doc3D, Layer3D, TextLayer3D } from "@dailies-studio/shot/doc";
+import type { ShotFontPreview, ShotFontPreviewFace } from "../bridgeTypes.js";
+
+/** The most files one preview loads: a whole face set (`fontAsset` plus
+ *  `FONT_SUBSETS_MAX` subsets). */
+export const MAX_FONT_PREVIEW_FACES = FONT_SUBSETS_MAX + 1;
+
+const FALLBACKS = new Set(["sans-serif", "serif", "monospace", "cursive"]);
+
+/** What the stage holds: the preview as sanitized, and the private family its
+ *  faces registered under once they landed. Null before that, and for good
+ *  when no face loads: the layers draw the display family and the fallback. */
+export interface StageFontPreview extends ShotFontPreview {
+  face: string | null;
+}
+
+/**
+ * A preview the stage can draw, or null for none. A boundary like
+ * `sanitizeSketchGuide`: the family becomes a CSS string in `ctx.font`, so it is
+ * one line of at most 100 characters; a fallback that is not one of the four
+ * generic families is `sans-serif`; a weight range off 1..1000 or backwards is
+ * `[1, 1000]`; a face with no url or a range `unicodeRangeProblem` refuses is
+ * dropped, and at most `MAX_FONT_PREVIEW_FACES` are kept. No container or no
+ * layer id is no preview.
+ */
+export function sanitizeFontPreview(raw: ShotFontPreview | null): ShotFontPreview | null {
+  if (raw === null || typeof raw !== "object") return null;
+  const { containerId, layerIds, family, fallback, style, weightRange, faces } = raw;
+  if (typeof containerId !== "string" || containerId.length === 0 || !Array.isArray(layerIds)) return null;
+  const ids = [...new Set((layerIds as unknown[]).filter((id): id is string => typeof id === "string" && id.length > 0))];
+  if (ids.length === 0) return null;
+  const weight = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 1 && n <= 1000;
+  const [min, max] = Array.isArray(weightRange) ? weightRange : [];
+  const kept = (Array.isArray(faces) ? faces : []).flatMap((face: Partial<ShotFontPreviewFace> | null): ShotFontPreviewFace[] => {
+    if (face === null || typeof face !== "object" || typeof face.url !== "string" || face.url.length === 0) return [];
+    if (face.unicodeRange === undefined) return [{ url: face.url }];
+    return unicodeRangeProblem(face.unicodeRange) === null ? [{ url: face.url, unicodeRange: face.unicodeRange }] : [];
+  });
+  return {
+    containerId,
+    layerIds: ids,
+    family: typeof family === "string" ? family.replace(/[\s\p{Cc}]+/gu, " ").trim().slice(0, 100) : "",
+    fallback: typeof fallback === "string" && FALLBACKS.has(fallback) ? fallback : "sans-serif",
+    style: style === "italic" ? "italic" : "normal",
+    weightRange: weight(min) && weight(max) && min <= max ? [min, max] : [1, 1000],
+    faces: kept.slice(0, MAX_FONT_PREVIEW_FACES),
+  };
+}
+
+/**
+ * The document the runtime draws while `preview` shows. In its container (a
+ * scene, else a definition), each listed text layer loses `fontAsset` and
+ * `fontSubsets` and draws the preview's private family (once its faces landed),
+ * then the display family, then the generic fallback, in the preview's style
+ * (upright is the key absent) and at its own weight, on the canvas engine (a
+ * glyph layer bakes `fontAsset`, and has none here). Naming the private family
+ * only once it landed is what re-rasters exactly these layers then: the style
+ * is part of a text raster's key.
+ *
+ * Every box keeps its stored size and place, auto-width ones included: picking
+ * and the overlays read layer frames off the runtime's scene graph, so a box
+ * moved here would move them off the real document. Every other object keeps
+ * its identity, `assets` included (the runtime's texture cache is keyed on
+ * it), and `doc` itself comes back when no listed id is a text layer of that
+ * container.
+ */
+export function fontPreviewDoc(doc: Doc3D, preview: StageFontPreview): Doc3D {
+  const scene = doc.scenesById[preview.containerId];
+  const def = scene === undefined ? doc.components?.[preview.containerId] : undefined;
+  const home = scene ?? def;
+  if (home === undefined) return doc;
+  const fontFamily = [preview.face, preview.family]
+    .filter((name): name is string => name !== null && name.length > 0)
+    .map(quoteFontFamily)
+    .concat(preview.fallback)
+    .join(", ");
+  let layersById: Record<string, Layer3D> | null = null;
+  for (const id of preview.layerIds) {
+    const layer = home.layersById[id];
+    if (layer?.kind !== "text") continue;
+    const { fontAsset: _asset, fontSubsets: _subsets, fontStyle: _slant, ...style } = layer.text.style;
+    const { engine: _engine, ...text } = layer.text;
+    const shown: TextLayer3D = {
+      ...layer,
+      text: { ...text, style: { ...style, fontFamily, ...(preview.style === "italic" ? { fontStyle: "italic" as const } : {}) } },
+    };
+    (layersById ??= { ...home.layersById })[id] = shown;
+  }
+  if (layersById === null) return doc;
+  return scene !== undefined
+    ? { ...doc, scenesById: { ...doc.scenesById, [preview.containerId]: { ...scene, layersById } } }
+    : { ...doc, components: { ...doc.components, [preview.containerId]: { ...def!, layersById } } };
+}
+
+type PreviewFace = ReturnType<FontPlatform["createFace"]>;
+
+export interface FontPreviewFaces {
+  /**
+   * Load `preview`'s faces under a new private family (`dailies-preview-<n>`),
+   * deleting the last preview's from the page's font set, or only delete them
+   * for null. The same files, style and weight range again keep the faces and
+   * family they have. Answers the family when this preview's faces are already
+   * in, else null; `onLanded` hears it once they land.
+   */
+  show(preview: ShotFontPreview | null): string | null;
+}
+
+/**
+ * The preview's faces. Each file loads on its own (`FontFace.load`) and joins
+ * the font set once every file has settled; the ones that failed are left out,
+ * and when none loads nothing happens at all. `onLanded` never hears a preview
+ * that was replaced or cleared meanwhile. `platformOf` is read only when a
+ * preview has faces to load (the test seam; a stage without the CSS Font
+ * Loading API answers null and draws the fallback).
+ */
+export function createFontPreviewFaces(
+  onLanded: (family: string) => void,
+  platformOf: () => FontPlatform | null = () => browserFontPlatform(),
+): FontPreviewFaces {
+  let made = 0;
+  let current: { key: string; family: string; fonts: FontPlatform["fonts"]; added: PreviewFace[]; landed: boolean } | null =
+    null;
+  return {
+    show(preview) {
+      const key = preview === null ? "" : JSON.stringify([preview.faces, preview.style, preview.weightRange]);
+      if (current !== null && current.key === key) return current.landed ? current.family : null;
+      if (current !== null) for (const face of current.added) current.fonts.delete(face);
+      current = null;
+      if (preview === null || preview.faces.length === 0) return null;
+      const platform = platformOf();
+      if (platform === null) return null;
+      made += 1;
+      const entry = { key, family: `dailies-preview-${made}`, fonts: platform.fonts, added: [] as PreviewFace[], landed: false };
+      current = entry;
+      const descriptors = { weight: `${preview.weightRange[0]} ${preview.weightRange[1]}`, style: preview.style };
+      let faces: PreviewFace[];
+      let loads: Promise<unknown>[];
+      try {
+        faces = preview.faces.map((face) =>
+          platform.createFace(
+            entry.family,
+            `url(${JSON.stringify(face.url)})`,
+            face.unicodeRange === undefined ? descriptors : { ...descriptors, unicodeRange: face.unicodeRange },
+          ),
+        );
+        loads = faces.map((face) => face.load());
+      } catch {
+        // Reports nothing, like a load that fails: the layers keep the fallback.
+        return null;
+      }
+      void Promise.allSettled(loads).then((settled) => {
+        if (current !== entry) return;
+        entry.added = faces.filter((_, index) => settled[index]!.status === "fulfilled");
+        if (entry.added.length === 0) return;
+        for (const face of entry.added) entry.fonts.add(face);
+        entry.landed = true;
+        onLanded(entry.family);
+      });
+      return null;
+    },
+  };
+}