castle-web-cli 0.4.176 → 0.4.178

package/kits/physics-2d/editors/deckFont.js

@@ -1,18 +1,24 @@
-// Writing the deck's font: the generated module, and keeping it honest.
+// Writing the deck's fonts: the generated module, and keeping it honest.
 //
-// `theme.style` records WHICH face; `fonts.generated.js` carries its bytes into
-// the bundle (engine/fonts.js explains why it takes two files). The picker
-// writes both together, so they agree the moment a font is chosen.
+// `theme.style` records the PRIMARY face; `fonts.generated.js` carries bytes
+// for that face plus any `Text.font` values used in the deck (engine/fonts.js).
+// The Theme picker writes both together for the primary; the Text inspector
+// rewrites the module when a per-actor face is chosen.
 //
 // They can still drift -- someone edits `theme.style` in the code editor, or
 // takes a scene file from another deck. `syncDeckFontModule` is the repair, run
-// once per edit-mode panel load: it compares what the module carries against
-// what the record asks for and rewrites the module when they disagree. Play
-// mode never repairs, and never needs to: a published deck's module was on disk
-// when `save-deck` bundled it.
+// once per edit-mode panel load.
 
 import * as castleSdk from 'castle-web-sdk';
-import { DECK_FONT_MODULE, generatedFontName, themeFontName } from '../engine/fonts';
+import {
+  DECK_FONT_MODULE,
+  collectTextFontsFromFiles,
+  fontsGeneratedSource,
+  generatedFontName,
+  generatedFontNames,
+  orderedDeckFonts,
+  themeFontName,
+} from '../engine/fonts';
 import { initialFiles } from '../engine/files';
 import { parseThemeData, THEME_STYLE_PATH } from '../engine/palettes';
 
@@ -22,67 +28,71 @@ import { parseThemeData, THEME_STYLE_PATH } from '../engine/palettes';
 // nothing, which renders the same and just leaves a stale file behind.
 const deleteFile = castleSdk.deleteFile ?? null;
 
-/** The whole content of `fonts.generated.js` for one face. */
-export function deckFontModuleSource(name) {
-  return `// Generated by the Theme editor. Do not edit -- picking a font rewrites it.
-//
-// \`theme.style\` records that this deck's font is ${name}; this module is what
-// puts ${name}'s bytes in the published bundle. It has to name the face in a
-// static import: reaching it through the name in \`theme.style\` instead would
-// inline all nine Castle faces into the deck, since no bundler can tell which
-// one a runtime lookup reads.
-export { install${name} as installDeckFont } from 'castle-web-fonts';
-export const deckFont = '${name}';
-`;
+/** The whole content of `fonts.generated.js` for a primary + extras. */
+export function deckFontModuleSource(name, extras = []) {
+  return fontsGeneratedSource(name, extras);
 }
 
-/** An empty module, for the SDK too old to delete a file. Renders as no deck
- * font, same as the file being absent. */
 function emptyModuleSource() {
-  return `// Generated by the Theme editor. Do not edit.
-//
-// This deck has no font of its own; text renders in the default sans stack.
-export const deckFont = null;
-`;
+  return fontsGeneratedSource(null, []);
 }
 
-/** Point the deck at `name`, or at no font when it is null. Writes the module
- * through the host's debounced saver, the same path every other editor edit
- * takes. */
+function textFontsFromDeck() {
+  return collectTextFontsFromFiles(initialFiles);
+}
+
+/** Point the deck at `name` as primary, or at no primary when null. Preserves
+ * faces Text actors already use. Writes through the host's debounced saver. */
 export function writeDeckFontModule(onChangeFile, name) {
+  const extras = textFontsFromDeck();
   if (name) {
-    onChangeFile(DECK_FONT_MODULE, deckFontModuleSource(name));
+    onChangeFile(DECK_FONT_MODULE, deckFontModuleSource(name, extras));
+    return;
+  }
+  // Primary cleared: keep Text-only faces if any, else remove / empty the module.
+  const remaining = orderedDeckFonts(null, extras);
+  if (remaining.length) {
+    onChangeFile(DECK_FONT_MODULE, deckFontModuleSource(remaining[0], remaining));
     return;
   }
   if (deleteFile) void deleteFile(DECK_FONT_MODULE);
   else onChangeFile(DECK_FONT_MODULE, emptyModuleSource());
 }
 
-/** Edit mode only: make `fonts.generated.js` say what `theme.style` asks for.
- *
- * Both sides are read from the build-time snapshot, so they are compared as the
- * running page actually has them -- the write lands, the panel reloads, and the
- * next load agrees. Returns what it did, for the log, or null when there was
- * nothing to do, which is every load but the one after a hand-edit.
+/** After a Text.font change: ensure that face (plus theme + other Text fonts)
+ * is in fonts.generated.js. `pendingFont` covers the value not yet on disk. */
+export function ensureTextFontsInModule(files, pendingFont) {
+  const primary = themeFontName(parseThemeData(files?.[THEME_STYLE_PATH])) ?? generatedFontName;
+  const extras = collectTextFontsFromFiles(files);
+  if (pendingFont) extras.push(pendingFont);
+  const next = orderedDeckFonts(primary, extras);
+  const prev = generatedFontNames;
+  if (next.length === prev.length && next.every((name, i) => name === prev[i])) {
+    if ((primary ?? null) === (generatedFontName ?? null)) return null;
+  }
+  const source = next.length
+    ? fontsGeneratedSource(primary ?? next[0], next)
+    : emptyModuleSource();
+  void castleSdk.writeFile(DECK_FONT_MODULE, source).catch(() => {});
+  return `Text fonts -- rewriting ${DECK_FONT_MODULE} (${next.join(', ') || 'none'})`;
+}
+
+/** Edit mode only: make `fonts.generated.js` match theme primary + Text fonts.
  *
- * It only ever WRITES, never deletes, and that is not a shortcut. Clearing the
- * font by hand is repaired with the empty module rather than by removing the
- * file, so the repair goes through the durable save queue like every other
- * write -- see below. Picking "None" in the editor still deletes the file
- * outright; that is a person clicking, with a connection that is up. */
+ * Both sides are read from the build-time snapshot. Returns what it did, or
+ * null when there was nothing to do. */
 export function syncDeckFontModule() {
   const wanted = themeFontName(parseThemeData(initialFiles[THEME_STYLE_PATH]));
-  if (wanted === generatedFontName) return null;
-  // Deliberately not awaited. `writeFile` is durable and its promise settles
-  // with the FIRST attempt -- which here is at module scope, usually before the
-  // dev-server socket is even open, so awaiting it reports "not yet" as a
-  // failure. The queue holds the text and writes it as soon as the connection
-  // is there.
-  void castleSdk.writeFile(
-    DECK_FONT_MODULE,
-    wanted ? deckFontModuleSource(wanted) : emptyModuleSource(),
-  ).catch(() => {});
-  return wanted
-    ? `${THEME_STYLE_PATH} asks for ${wanted} -- rewriting ${DECK_FONT_MODULE}`
+  const extras = textFontsFromDeck();
+  const next = orderedDeckFonts(wanted, extras);
+  const prev = generatedFontNames;
+  const primaryMatch = (wanted ?? null) === (generatedFontName ?? null);
+  const listMatch = next.length === prev.length && next.every((name, i) => name === prev[i]);
+  if (primaryMatch && listMatch) return null;
+  void castleSdk
+    .writeFile(DECK_FONT_MODULE, next.length ? fontsGeneratedSource(wanted ?? next[0], next) : emptyModuleSource())
+    .catch(() => {});
+  return next.length
+    ? `fonts -- rewriting ${DECK_FONT_MODULE} (primary ${wanted ?? next[0]}; ${next.join(', ')})`
     : `${THEME_STYLE_PATH} sets no font -- clearing ${DECK_FONT_MODULE}`;
 }

package/kits/physics-2d/editors/fontPreview.js

@@ -4,48 +4,16 @@
 // deck must never do: importing all nine would inline 495 KB into every
 // published deck, and the whole physics-2d bundle is under 900 KB.
 //
-// So the specimens are not imported, they are FETCHED. The dev server serves
-// the deck's `node_modules` as static files, and `castle-web-fonts` ships the
-// raw woff2 alongside its modules, so a plain URL reaches every face at no cost
-// to the bundle. That only works while editing locally — which is the only
-// place an editor runs, so nothing is lost. A face that doesn't arrive leaves
-// its card in the UI font, and the picker still picks.
+// So the specimens are not imported, they are FETCHED (see ensureOfficialFace).
+// That only works while editing locally — which is the only place an editor
+// runs, so nothing is lost. A face that doesn't arrive leaves its card in the
+// UI font, and the picker still picks.
 
 import { useEffect, useState } from 'react';
-import { OFFICIAL_FONTS } from '../engine/fonts';
+import { OFFICIAL_FONTS, ensureOfficialFace } from '../engine/fonts';
 
 const FACE_NAMES = OFFICIAL_FONTS.map((face) => face.name);
 
-const faceUrl = (name) => `/node_modules/castle-web-fonts/woff2/${name}.woff2`;
-
-// Module-scope so the panel's re-renders don't refetch, and so switching files
-// and back is instant. Values are promises resolving to true / false.
-const requests = new Map();
-
-function request(name) {
-  const pending = requests.get(name);
-  if (pending) return pending;
-  const load = loadFace(name);
-  requests.set(name, load);
-  return load;
-}
-
-async function loadFace(name) {
-  if (typeof FontFace === 'undefined') return false;
-  try {
-    // Registered under the face's real family name, so a card just asks for
-    // `font-family: Tektur`. When the deck's own font is already installed this
-    // adds a second face for that family from the identical bytes — which
-    // renders identically, and costs one entry in document.fonts.
-    const face = new FontFace(name, `url("${faceUrl(name)}") format("woff2")`);
-    await face.load();
-    document.fonts.add(face);
-    return true;
-  } catch {
-    return false; // no serve, or an install without the package: no specimen.
-  }
-}
-
 /** Load every Castle face's specimen and report which have arrived. Cards
  * re-render into their own face as each one lands. */
 export function usePreviewFaces() {
@@ -53,7 +21,7 @@ export function usePreviewFaces() {
   useEffect(() => {
     let live = true;
     for (const name of FACE_NAMES) {
-      void request(name).then((ok) => {
+      void ensureOfficialFace(name).then((ok) => {
         if (!ok || !live) return;
         setLoaded((current) => (current.has(name) ? current : new Set(current).add(name)));
       });

package/kits/physics-2d/editors/pixelInspector.jsx

@@ -1,8 +1,10 @@
-import React, { useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { createPortal } from 'react-dom';
+import React, { useRef, useState } from 'react';
 import { GRID_RENDERER, RESOLUTION_STEPS, VECTOR_RENDERER } from '../engine/pxart';
+import { PaletteGrid, PalettePager, PalettePopover } from '../engine/paletteField';
 import { cx, Icon, IconButton, Panel, styles } from '../engine/ui';
 
+export { NoneSwatch, PaletteGrid, PalettePager, PalettePopover, sameHex } from '../engine/paletteField';
+
 // Brush/erase diameters offered by the pixel editors' size sliders.
 export const BRUSH_SIZES = [1, 2, 3, 4, 6, 8, 12, 16, 24, 32];
 
@@ -223,86 +225,6 @@ function ResolutionSelect({ label, value, onChange, disabled = false }) {
   );
 }
 
-function sameHex(a, b) {
-  return !!a && !!b && a.toLowerCase() === b.toLowerCase();
-}
-
-function NoneSwatch({ selected, onSelect }) {
-  return (
-    <button
-      type="button"
-      className={cx(styles.swatch, selected && styles.swatchSelected)}
-      title="None"
-      aria-label="None"
-      style={{ position: 'relative', background: 'transparent' }}
-      onClick={onSelect}>
-      <span
-        aria-hidden
-        style={{
-          position: 'absolute',
-          inset: 4,
-          background:
-            'linear-gradient(to top right, transparent calc(50% - 1px), #e66 calc(50% - 1px), #e66 calc(50% + 1px), transparent calc(50% + 1px))',
-        }}
-      />
-    </button>
-  );
-}
-
-// Swatch strip shared by the docked sidebar and the compact popover.
-// `keys` paints a sprite's working palette; `hexes` paints a picker list.
-// `wrap` is the unlabeled sprite row; the named official page is an 8-col grid.
-export function PaletteGrid({
-  keys,
-  hexes,
-  palette,
-  activeKey,
-  activeHex,
-  onSelectKey,
-  onSelectHex,
-  allowNone = false,
-  noneSelected = false,
-  onSelectNone,
-  wrap = false,
-}) {
-  const items = hexes
-    ? hexes.map((hex) => ({ id: hex, hex, selected: sameHex(activeHex, hex), onClick: () => onSelectHex?.(hex) }))
-    : (keys ?? []).map((key) => ({
-        id: key,
-        hex: palette?.[key],
-        selected: activeKey === key || sameHex(activeHex, palette?.[key]),
-        onClick: () => onSelectKey?.(key),
-      }));
-  if (!allowNone && !items.length) return null;
-  return (
-    <div className={wrap ? styles.paletteSpriteRow : styles.palette}>
-      {allowNone ? <NoneSwatch selected={noneSelected} onSelect={onSelectNone} /> : null}
-      {items.map((item) => (
-        <button
-          key={item.id}
-          type="button"
-          className={cx(styles.swatch, item.selected && styles.swatchSelected)}
-          title={item.hex}
-          style={{ background: item.hex }}
-          onClick={item.onClick}
-        />
-      ))}
-    </div>
-  );
-}
-
-function PalettePager({ name, onPage }) {
-  return (
-    <div className={styles.palettePager}>
-      <span className={styles.palettePagerName}>{name}</span>
-      <div className={styles.palettePagerBtns}>
-        <IconButton icon="chevron-left" label="Previous palette" onClick={() => onPage(-1)} />
-        <IconButton icon="chevron-right" label="Next palette" onClick={() => onPage(1)} />
-      </div>
-    </div>
-  );
-}
-
 // Unlabeled sprite-color row (when the sprite has colors, or when fill/stroke
 // needs a none swatch) plus a paged official-palette grid. Paging only changes
 // which named page is shown — it does not write theme.style.
@@ -349,78 +271,6 @@ export function PaletteSections({
   );
 }
 
-// Anchored palette + eyedropper popover for compact/mobile paint-strip color tap.
-export function PalettePopover({ open, anchorRef, onClose, children }) {
-  const popoverRef = useRef(null);
-  const [position, setPosition] = useState({ top: 0, left: 0 });
-
-  useLayoutEffect(() => {
-    if (!open || !anchorRef.current) return;
-
-    function positionPopover() {
-      const anchor = anchorRef.current.getBoundingClientRect();
-      const rect = popoverRef.current?.getBoundingClientRect();
-      const margin = 8;
-      const width = rect?.width ?? 231;
-      const height = rect?.height ?? 320;
-      const maxLeft = Math.max(margin, window.innerWidth - width - margin);
-      const maxTop = Math.max(margin, window.innerHeight - height - margin);
-      const leftSide = anchor.left - width - margin;
-      const rightSide = anchor.right + margin;
-      // Prefer the side with room, then clamp a too-wide picker inside this
-      // iframe rather than sending it beyond either viewport edge.
-      const left =
-        leftSide >= margin
-          ? leftSide
-          : rightSide <= maxLeft
-            ? rightSide
-            : Math.min(maxLeft, Math.max(margin, anchor.left + anchor.width / 2 - width / 2));
-      const top = Math.min(maxTop, Math.max(margin, anchor.top));
-      setPosition({ top, left });
-    }
-
-    positionPopover();
-    window.addEventListener('resize', positionPopover);
-    window.addEventListener('scroll', positionPopover, true);
-    return () => {
-      window.removeEventListener('resize', positionPopover);
-      window.removeEventListener('scroll', positionPopover, true);
-    };
-  }, [open, anchorRef]);
-
-  useEffect(() => {
-    if (!open) return undefined;
-    function onKeyDown(event) {
-      if (event.key === 'Escape') onClose();
-    }
-    function onPointerDown(event) {
-      if (popoverRef.current?.contains(event.target) || anchorRef.current?.contains(event.target)) {
-        return;
-      }
-      onClose();
-    }
-    window.addEventListener('keydown', onKeyDown);
-    window.addEventListener('pointerdown', onPointerDown);
-    return () => {
-      window.removeEventListener('keydown', onKeyDown);
-      window.removeEventListener('pointerdown', onPointerDown);
-    };
-  }, [open, onClose, anchorRef]);
-
-  if (!open) return null;
-  return createPortal(
-    <div
-      ref={popoverRef}
-      className={styles.palettePopover}
-      style={{ top: position.top, left: position.left }}
-      role="dialog"
-      aria-label="Palette">
-      {children}
-    </div>,
-    document.body
-  );
-}
-
 // The shape tool's sub-mode picker, shared by the compact paint strip and the
 // wide-layout settings panel. `buttonClass` styles each glyph button for its
 // host strip; `radio` switches the a11y semantics to a radiogroup.

package/kits/physics-2d/engine/blueprint.js

@@ -696,6 +696,34 @@ export function newBlueprintFromActor(files, behaviors, sceneData, actorId) {
   return { sceneData: next, blueprintFile };
 }
 
+// "Fork blueprint": mint a NEW deck-owned blueprint whose template is a copy of
+// the selected one. Additive — existing instances keep pointing at the source.
+// An import's art is copied into the deck (same as creating from a kit preset)
+// so the fork is editable; a deck-owned source keeps sharing its art refs.
+export function forkBlueprint(files, blueprintPath) {
+  const template = getBlueprintTemplate(files, blueprintPath);
+  if (!template) return null;
+  const existingPaths = new Set(Object.keys(files ?? {}));
+  const existingNames = listBlueprints(files)
+    .filter((blueprint) => !isImportedPath(blueprint.path))
+    .map((blueprint) => blueprint.name);
+  const base = `${template.name || 'Blueprint'} (forked)`;
+  const name = mintNameFromBase(existingNames, base);
+  const path =
+    mintPathFromName(existingPaths, name, BLUEPRINTS_DIR, '.scene') ??
+    mintBlueprintPath([...existingPaths]);
+  const components = structuredClone(template.components ?? {});
+  let drawingFile = null;
+  if (isImportedPath(blueprintPath)) {
+    drawingFile = adoptBuiltinArt(files, components, existingPaths, name);
+  }
+  for (const props of Object.values(components ?? {})) reprojectRefsIn(props, files, path);
+  return {
+    blueprintFile: { path, name, components, text: formatBlueprintFileText(name, components) },
+    drawingFile,
+  };
+}
+
 // Every `scenes/*.scene` file's parsed data, for callers that need to scan
 // every scene in the deck (cascade delete, the instance-count badge/confirm).
 // Skips unparseable files rather than throwing -- a mid-edit scene with

package/kits/physics-2d/engine/fonts.js

@@ -1,20 +1,18 @@
-// The deck's font.
+// The deck's fonts.
 //
-// Two files hold it, and the split is the whole point:
+// Two files hold them, and the split is the whole point:
 //
-//   theme.style          { "font": "Piazzolla" }   the RECORD -- readable, hand-editable
-//   fonts.generated.js   a one-line re-export      the BYTES
+//   theme.style          { "font": "Piazzolla" }   the RECORD -- primary face
+//   fonts.generated.js   static re-exports         the BYTES
 //
 // `theme.style` is data the engine reads at RUNTIME, so a font name in it is
 // just a string, and turning a runtime string into font bytes means a lookup
 // keyed by that name -- which no bundler can narrow, so it would inline all
-// nine Castle faces (495 KB) into every physics-2d deck, whose whole bundle is
-// under 900 KB. The generated module names its face in a static import
-// instead, so exactly one face ships. See castle-web-fonts' README.
+// nine Castle faces (495 KB) into every physics-2d deck. The generated module
+// names each face in a static import instead, so only the faces in use ship.
 //
-// The two can drift when someone edits `theme.style` by hand. Edit mode heals
-// that (editors/deckFont.js); a published deck is always consistent, because
-// the module is on disk when `save-deck` bundles it.
+// Faces in use = the theme primary plus every `Text.font` on actors in the
+// deck's scenes/blueprints. Edit mode keeps the module honest (editors/deckFont.js).
 
 import { FACES, faceInfo } from 'castle-web-fonts';
 
@@ -34,11 +32,19 @@ export const DEFAULT_FONT_FAMILY = 'sans-serif';
 const generated = import.meta.glob('/fonts.generated.js', { eager: true });
 const deckFontModule = generated['/fonts.generated.js'];
 
-/** The face the generated module actually carries, or null when there is none.
- * This is what the deck RENDERS in, as against what `theme.style` asks for. */
+/** The face the generated module actually carries as primary, or null. */
 export const generatedFontName =
   typeof deckFontModule?.deckFont === 'string' ? deckFontModule.deckFont : null;
 
+/** Every face the generated module ships (primary + Text extras), ordered. */
+export const generatedFontNames = (() => {
+  const listed = deckFontModule?.deckFonts;
+  if (Array.isArray(listed) && listed.length) {
+    return listed.filter((name) => typeof name === 'string' && faceInfo(name));
+  }
+  return generatedFontName ? [generatedFontName] : [];
+})();
+
 /** A CSS `font-family` value that is always safe to use: the deck's face when
  * it has one, a plain sans stack when it doesn't. */
 export const deckFontFamily = generatedFontName ?? DEFAULT_FONT_FAMILY;
@@ -50,30 +56,126 @@ export function themeFontName(themeData) {
   return typeof raw === 'string' && faceInfo(raw) ? raw : null;
 }
 
+/** Resolve a Text.font prop to a CSS family: empty/unknown → deck primary. */
+export function resolveTextFont(font) {
+  if (typeof font === 'string' && font && faceInfo(font)) return font;
+  return deckFontFamily;
+}
+
+/** Unique official face names from every Text actor in scene/blueprint files. */
+export function collectTextFontsFromFiles(files) {
+  const found = new Set();
+  for (const [path, text] of Object.entries(files ?? {})) {
+    if (!path.endsWith('.scene') || typeof text !== 'string') continue;
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    for (const actor of data?.actors ?? []) {
+      const name = actor?.components?.Text?.font;
+      if (typeof name === 'string' && faceInfo(name)) found.add(name);
+    }
+  }
+  return [...found];
+}
+
+/** Ordered unique official faces: primary first, then extras. */
+export function orderedDeckFonts(primary, extras = []) {
+  const out = [];
+  const seen = new Set();
+  for (const name of [primary, ...extras]) {
+    if (!name || !faceInfo(name) || seen.has(name)) continue;
+    seen.add(name);
+    out.push(name);
+  }
+  return out;
+}
+
+/** Source for `fonts.generated.js` carrying exactly `fonts` (primary = deckFont). */
+export function fontsGeneratedSource(primary, fonts) {
+  const list = orderedDeckFonts(primary, fonts);
+  if (!list.length) {
+    return `// Generated by the Theme editor. Do not edit.
+//
+// This deck has no font of its own; text renders in the default sans stack.
+export const deckFont = null;
+export const deckFonts = [];
+export const installDeckFonts = [];
+`;
+  }
+  const primaryName = list.includes(primary) ? primary : list[0];
+  const imports = list.map((name) => `install${name}`).join(', ');
+  const installers = list.map((name) => `install${name}`).join(', ');
+  const namesLit = list.map((name) => `'${name}'`).join(', ');
+  return `// Generated by the Theme editor / Text font picker. Do not edit.
+//
+// \`theme.style\` records the deck's primary font as ${primaryName}; Text actors
+// may use additional faces. This module is what puts their bytes in the
+// published bundle — each face must be named in a static import so the bundler
+// can tree-shake the rest.
+import { ${imports} } from 'castle-web-fonts';
+export { install${primaryName} as installDeckFont };
+export const deckFont = '${primaryName}';
+export const deckFonts = [${namesLit}];
+export const installDeckFonts = [${installers}];
+`;
+}
+
 let ready = null;
 
 /** Resolve once every face this deck registered can be drawn with -- the deck
- * font, and any a behavior imported for itself.
+ * font(s) in fonts.generated.js, and any a behavior imported for itself.
  *
  * Wait for this before the first frame. Canvas 2D does not trigger a font load,
  * so a `draw` hook setting `ctx.font` before the face is ready silently falls
- * back to the default -- and never repaints when the font lands, so the deck
- * looks right after a warm reload and wrong on a cold first paint.
- *
- * `document.fonts.ready` is what covers the extras, and it is the only thing
- * that can: a deck wanting a display face beside the deck font imports it
- * itself, and nothing here knows its name. A behavior module's `installBore()`
- * runs while the module graph loads, which is before the player mounts, so that
- * load is already pending by the time this is first called.
+ * back to the default -- and never repaints when the font lands.
  *
  * Never rejects: a deck whose font failed to load should still play. */
 export function fontsReady() {
   if (!ready) {
-    const install = deckFontModule?.installDeckFont;
+    const list = deckFontModule?.installDeckFonts;
+    const installers = Array.isArray(list) && list.length
+      ? list
+      : deckFontModule?.installDeckFont
+        ? [deckFontModule.installDeckFont]
+        : [];
     ready = Promise.all([
-      install ? install() : null,
+      ...installers.map((install) => (typeof install === 'function' ? install() : null)),
       typeof document === 'undefined' ? null : document.fonts?.ready,
     ]).catch(() => null);
   }
   return ready;
 }
+
+// Edit-time loads for faces not yet in the eager `fonts.generated.js` module
+// (e.g. the author just picked Text.font). Same woff2 URLs the font picker
+// uses -- served from node_modules while editing, never inlined into a publish.
+const faceLoads = new Map();
+
+/** Install one Castle face into `document.fonts` so canvas text can use it
+ * without a panel reload. No-op for unknown / empty names. Idempotent. */
+export function ensureOfficialFace(name) {
+  if (!name || !faceInfo(name)) return Promise.resolve(false);
+  if (typeof FontFace === 'undefined' || typeof document === 'undefined') {
+    return Promise.resolve(false);
+  }
+  const pending = faceLoads.get(name);
+  if (pending) return pending;
+  const load = (async () => {
+    try {
+      const face = new FontFace(
+        name,
+        `url("/node_modules/castle-web-fonts/woff2/${name}.woff2") format("woff2")`
+      );
+      await face.load();
+      document.fonts.add(face);
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+  faceLoads.set(name, load);
+  return load;
+}