lecodes-sdk 2.4.10 → 2.5.0

package/src/runtime/fetch.ts

@@ -62,6 +62,24 @@ export const fetch = (url: string, options: FetchOptions = {}): Promise<FetchRes
 export const fetchLocal = (path: string): FetchResponse =>
   new FetchResponseImpl({ id: _creatorFetch.local(path) }, 200)   // the host's buffer: not owned
 
+// A local `asset()` compiles to `__localAsset("id:" + _creatorFetch.local(<name>), <name>)` (sdk/src/compile/
+// compileProject.ts): the "id:" url is the host's buffer id, assigned in the order the bundle asks, so it names the
+// asset for THIS run only; the staged NAME is what stays the same across compiles. The pair is kept so a cache
+// written by one run (gl/Statics.ts) can name an asset to the next.
+const localAssetNames = new Map<string, string>()
+const localAssetUrls = new Map<string, string>()
+/** @internal */
+export const __localAsset = (url: string, name: string): string => {
+  localAssetNames.set(url, name)
+  localAssetUrls.set(name, url)
+  return url
+}
+/** @internal The stable name of an asset url: its staged name for a local asset, the url itself otherwise (a server
+ *  build's urls are paths, stable on their own). */
+export const assetNameOf = (url: string): string => localAssetNames.get(url) ?? url
+/** @internal The url of a stable asset name in this run (the inverse of `assetNameOf`). */
+export const assetUrlOf = (name: string): string => localAssetUrls.get(name) ?? name
+
 /** A handle to a picked / fetched file (see openFilePicker). */
 export class File {
   /** @internal The host buffer (not owned — see the header). Same key `FetchResponse` carries, so

package/src/scene/defineScene.ts

@@ -49,10 +49,11 @@ import { CAMERA_DEFAULTS } from "../gl/Camera"
 import { CameraPlace } from "../gl/CameraPlace"
 import { Node } from "../gl/Node"
 import { Mesh } from "../gl/Mesh"
-import { Model } from "../gl/Model"
+import { Model, foliageKindOf, type FoliageKind } from "../gl/Model"
 import { Physics } from "../gl/physics/Physics"
 import { CharacterController } from "../gl/physics/CharacterController"
-import { Lightmap, type LightmapDef } from "../gl/Lightmap"
+import { Lightmap, type LightmapDef, type LightmapPrepared } from "../gl/Lightmap"
+import { coveredRoots, defsDigest, bakeDigest, findNode, open as staticsOpen, build as staticsBuild, snapshot as staticsSnapshot, staticsConfig, toolRun, type CoveredRoot, type OpenedCache } from "../gl/Statics"
 import { Foliage, type FoliageOptions } from "../gl/Foliage"
 import { NavMesh } from "../gl/nav/NavMesh"
 import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain"
@@ -191,19 +192,23 @@ export type SceneNodeDef = {
    *  the GLB instance, so `castShadows: false` on a first-person viewmodel covers the whole gun. */
   castShadows?: boolean
   receiveShadows?: boolean
-  /** Baked lighting (a scene with `env.lightmap`): is this model/mesh node a lightmap STATIC — a
-   *  receiver and an occluder in the bake, real-time shadow casting off once the bake applies?
-   *  Default: static unless a `Physics` aspect moves the node (`dynamic` — Physics' default — or
-   *  `kinematic`). Set it only to override that rule; prefab subtrees inherit the verdict.
-   *  `'cube'` = a static whose every mesh bakes as AMBIENT CUBES instead of atlas texels — an occluder (its shadow and
+  /** Is this node STATIC — part of the level that never moves once loaded? A static is what the bake sees (a
+   *  receiver and an occluder, real-time shadow casting off once the bake applies) and what the level cache
+   *  snapshots after the first load. Default: static unless a `Physics` aspect moves the node (`dynamic` —
+   *  Physics' default — or `kinematic`). `false` = built live, lit in real time, never cached. Set it only to
+   *  override that rule; prefab subtrees inherit the verdict. */
+  static?: boolean
+  /** `'cube'` = a static whose every mesh bakes as AMBIENT CUBES instead of atlas texels — an occluder (its shadow and
    *  bounce stay in the bake) lit where it stands, the way the bake treats small and thin props on its own: a pipe run, a
    *  fence, a prop whose lightmap seams show. A prefab marked `'cube'` bakes its statics that way too. By name for a whole
    *  kit: the `cube` option of `env.lightmap`'s `bake()`. */
-  lightmap?: boolean | "cube"
+  lightmap?: "cube"
   /** `model` nodes: vegetation — load through the FOLIAGE tier (wind, touch bending, per-copy tint; see
-   *  `Foliage`). `{ fade: [start, end] }` also thins the cards out over that distance range (m) and drops the
-   *  copy past `end` — for ground cover. The fade is per ASSET: every node of the same GLB shares it. */
-  foliage?: boolean | { fade?: [number, number] }
+   *  `Foliage`). `'tree'` (= `true`): a crown, lit by the sky and the real-time sun; `'grass'`: ground cover, lit by
+   *  the terrain's baked light under it (`Model.load`'s `foliage`). The object form names the kind and may add
+   *  `fade: [start, end]`: the cards thin out over that distance range (m) and the copy drops past `end` — for
+   *  ground cover. The fade is per ASSET: every node of the same GLB shares it. */
+  foliage?: boolean | "tree" | "grass" | { kind?: "tree" | "grass", fade?: [number, number] }
   /** Navigation (a scene with `env.navmesh`, see navmesh.md): every STATIC body is walkable by
    *  default. `false` leaves this one out of the bake; `'unwalkable'` cuts its footprint out
    *  (nobody stands on or crosses it). */
@@ -417,9 +422,9 @@ const movesByPhysics = (def: SceneNodeDef): boolean =>
     ((e.ctor as unknown) === Physics && ((e.props as { motion?: string } | undefined)?.motion ?? "dynamic") !== "static")
     || (e.ctor as unknown) === CharacterController)
 
-/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule).
- *  Children of a mover are movers too — buildNodes carries that down, this is the node's own verdict. */
-export const isLightmapStatic = (def: SceneNodeDef): boolean => def.lightmap !== undefined ? def.lightmap !== false : !movesByPhysics(def)
+/** The static verdict for one node def (the editor's "Static" switch shows the same rule). Children of a
+ *  mover are movers too — buildNodes carries that down, this is the node's own verdict. */
+export const isStatic = (def: SceneNodeDef): boolean => def.static !== undefined ? def.static : !movesByPhysics(def)
 
 /** A terrain node: from its file or a fresh flat grid; textures load before the node appears (like a
  *  mesh's material). Stamps and holes apply later in buildNodes, once every target node exists. */
@@ -443,23 +448,39 @@ const createTerrain = async (def: TerrainNodeDef, lightmap: boolean): Promise<No
 // cannot leak into the next node that leaves the flag alone.
 const modelTemplates = new Map<string, Promise<Model>>()
 
-const loadModel = (source: string, lightmap: boolean, foliage: boolean): Promise<Model> => {
-  const key = `${lightmap}\u0000${foliage ? "foliage" : ""}\u0000${source}`
+/** What one `load()` spent where — the `[load]` line instantiate prints (always on, like the host's
+ *  `[startup]`): a slow open names its stage. `glb` is the wall from the first template's fetch to the last
+ *  one's resolve (they overlap); `clone` / `aspects` are sums of synchronous work. */
+const loadStats = { glb: 0, glbFirst: 0, glbLast: 0, clones: 0, cloneMs: 0, aspectsMs: 0 }
+const resetLoadStats = (): void => { loadStats.glb = 0; loadStats.glbFirst = 0; loadStats.glbLast = 0; loadStats.clones = 0; loadStats.cloneMs = 0; loadStats.aspectsMs = 0 }
+
+const templateModel = (source: string, lightmap: boolean, foliage: FoliageKind): Promise<Model> => {
+  const key = `${lightmap}\u0000${foliage || ""}\u0000${source}`
   let template = modelTemplates.get(key)
   if (template === undefined) {
-    template = Model.load(source, { lightmap, foliage })
+    if (loadStats.glb++ === 0) loadStats.glbFirst = Date.now()
+    template = Model.load(source, { lightmap, foliage }).then((m) => { loadStats.glbLast = Date.now(); return m })
     modelTemplates.set(key, template)
     // a failed load must not poison the cache — the next node retries
     void template.catch(() => modelTemplates.delete(key))
   }
-  return template.then((t) => t.clone())
+  return template
 }
 
+const loadModel = (source: string, lightmap: boolean, foliage: FoliageKind): Promise<Model> =>
+  templateModel(source, lightmap, foliage).then((t) => {
+    const t0 = Date.now()
+    const c = t.clone()
+    loadStats.clones++
+    loadStats.cloneMs += Date.now() - t0
+    return c
+  })
+
 /** @internal */
 export const createSource = (path: string, def: SceneNodeDef, lightmap: boolean): Node | Promise<Node> => {
   const sources = [ def.mesh, def.model, def.light, def.make, def.prefab, def.camera, def.terrain ].filter((s) => s !== undefined).length
   if (sources > 1) throw new Error(`Scene node "${path}" declares more than one source (mesh/model/light/make/prefab/camera/terrain)`)
-  if (def.model !== undefined) return loadModel(def.model, lightmap, !!def.foliage)
+  if (def.model !== undefined) return loadModel(def.model, lightmap, foliageKindOf(def.foliage))
   if (def.mesh !== undefined) return createMesh(def.mesh, def.material)
   if (def.terrain !== undefined) return createTerrain(def.terrain, lightmap)
   if (def.light !== undefined) return createLight(path, def.light)
@@ -848,7 +869,7 @@ const prefabPartRows = (defs: Record<string, SceneNodeDef>, local: Record<string
 }
 
 /** @internal */
-export const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scene: Scene, stack: Set<SceneDef>, lm: LightmapCtx | null): Promise<void> => {
+export const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDef, scene: Scene, stack: Set<SceneDef>, lm: LightmapCtx | null, covered?: Map<string, CoveredRoot & { node?: Node }>): Promise<void> => {
   const pdef = (def.prefab as { def?: SceneDef } | undefined)?.def
   if (!pdef || typeof pdef !== "object") {
     console.error(`[scene] "${path}".prefab is not a scene handle (import the .scene file's default export)`)
@@ -862,7 +883,7 @@ export const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDe
   }
   const local: Record<string, Node> = {}
   const localRuns: EditorRun[] = []   // discarded: instance internals render, but aren't editor-tracked
-  await buildNodes(pdef.nodes ?? {}, wrapper, scene, local, localRuns, new Set(stack).add(pdef), lm)
+  await buildNodes(pdef.nodes ?? {}, wrapper, scene, local, localRuns, new Set(stack).add(pdef), lm, covered, `${path}/`)
   const rows = prefabPartRows(pdef.nodes ?? {}, local, "", 0)
   ;(wrapper as { _prefabParts?: ModelPartRow[] })._prefabParts = rows
   if (def.overrides) applyOverridesToRows(rows, def.overrides)
@@ -874,13 +895,13 @@ export const attachPrefab = async (wrapper: Node, path: string, def: SceneNodeDe
 const buildNodes = async (
   defs: Record<string, SceneNodeDef>, parent: Node | null, scene: Scene,
   nodes: Record<string, Node>, editorRuns: EditorRun[], stack: Set<SceneDef>,
-  lm: LightmapCtx | null = null,
+  lm: LightmapCtx | null = null, covered: Map<string, CoveredRoot & { node?: Node }> = new Map(), coveredPrefix = "",
 ): Promise<void> => {
   const pending: { path: string, node: Node, def: SceneNodeDef }[] = []
   const moverRoots: Node[] = []
 
   // `parentMoves`: a child of a mover moves with it (the body under the hero's capsule) — it never
-  // bakes, whatever its own def says short of an explicit `lightmap: true`
+  // bakes, whatever its own def says short of an explicit `static: true`
   const build = async (name: string, nd: SceneNodeDef, parentNode: Node | null, parentPath: string, parentMoves = false): Promise<void> => {
     // names are path segments — '/' would fork the path, ':' would ambiguate editor card keys
     if (name === "" || name.includes("/") || name.includes(":")) {
@@ -889,7 +910,19 @@ const buildNodes = async (
     // the path is derived from def keys BEFORE any await, so it is deterministic even though
     // Promise.all makes build completion (and record insertion) order nondeterministic
     const path = parentPath === "" ? name : `${parentPath}/${name}`
-    const lmStatic = lm !== null && (nd.lightmap !== undefined ? nd.lightmap !== false : !parentMoves && isLightmapStatic(nd))
+    // a subtree the static level cache rebuilds natively (gl/Statics.ts): one plain JS node, the clones under it
+    // (`coveredPrefix`: this build's full-path prefix — a prefab's internals are keyed from the level's root)
+    const cov = covered.size > 0 ? covered.get(coveredPrefix + path) : undefined
+    if (cov) {
+      const node = new Node()
+      if (parentNode) attachHost(parentNode, nd, path).add(node)
+      scene.add(node)
+      applyNode(node, name, nd)
+      cov.node = node
+      nodes[path] = node
+      return
+    }
+    const lmStatic = lm !== null && (nd.static !== undefined ? nd.static : !parentMoves && isStatic(nd))
     const lmCube = lmStatic && (nd.lightmap === "cube" || lm!.cube === true)
     // a mover in a level with a light volume reads the volume (models: the engine binds it; meshes: registered below)
     const node = await createSource(path, nd, lmStatic)
@@ -905,7 +938,7 @@ const buildNodes = async (
     if (lm !== null && !lmStatic && !parentMoves) moverRoots.push(node)
     if (EDITOR && isEditMode()) addEditorMarker(node, nd)
     // a prefab under a static wrapper bakes; under a mover its internals stay movers (volume-lit)
-    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/`, cube: lmCube } : null)
+    if (nd.prefab !== undefined) await attachPrefab(node, path, nd, scene, stack, lmStatic ? { prefix: `${lm!.prefix}${path}/`, cube: lmCube } : null, covered.size > 0 ? covered : undefined)
     pending.push({ path, node, def: nd })
     nodes[path] = node
     await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node, path, parentMoves || (lm !== null && !lmStatic))))
@@ -913,12 +946,14 @@ const buildNodes = async (
 
   await Promise.all(Object.entries(defs).map(([ name, nd ]) => build(name, nd, parent, "")))
   const makeWaits: Promise<void>[] = []
+  const tAspects = Date.now()
   for (const p of pending) {
     const aspectWait = attachAspects(p.node, p.path, p.def, nodes, scene, editorRuns)
     if (aspectWait) makeWaits.push(aspectWait)
     const wait = attachMake(p.node, p.path, p.def, nodes, scene, editorRuns)
     if (wait) makeWaits.push(wait)
   }
+  loadStats.aspectsMs += Date.now() - tAspects
   if (makeWaits.length > 0) await Promise.all(makeWaits)
 
   // terrain stamps + holes: every node of the file exists now (make() subtrees included), and a
@@ -973,7 +1008,29 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   // baked lighting is a play-mode concern; the level owns the registry (a rebuild starts clean)
   const lm: LightmapCtx | null = lightmap && !(EDITOR && isEditMode()) ? { prefix: "" } : null
   if (lm) Lightmap.clear()
-  await buildNodes(def.nodes ?? {}, null, scene, nodes, editorRuns, new Set([ def ]), lm)
+  resetLoadStats()
+  const tLoad = Date.now()
+  // THE STATIC LEVEL CACHE (gl/Statics.ts): with a fresh `<level>.static` beside the bake the covered subtree is
+  // rebuilt natively and the JS builds the rest. Under a tool run (a bake, the snapshot itself) and in the editor
+  // the level always builds the slow, complete way.
+  const staticsCfg = staticsConfig()
+  const roots = lm && lightmap && (staticsCfg || !toolRun()) ? coveredRoots(def.nodes, def) : []
+  let prepared: LightmapPrepared | null = null
+  let opened: OpenedCache | null = null
+  if (roots.length > 0 && lightmap?.statics && lm && !staticsCfg && !toolRun()) {
+    prepared = await Lightmap.prepare(scene, lightmap)   // the pages first: the engine binds the records as it clones
+    opened = await staticsOpen(lightmap.statics, defsDigest(roots, def), bakeDigest(prepared?.data ?? null))
+    if (opened && opened.roots !== roots.length) { console.warn(`[static] the cache covers ${opened.roots} subtree(s), the scene has ${roots.length} — building the level the slow way`); opened = null }
+  }
+  const covered = new Map<string, CoveredRoot & { node?: Node }>()
+  if (opened) for (const r of roots) covered.set(r.path, r)
+  await buildNodes(def.nodes ?? {}, null, scene, nodes, editorRuns, new Set([ def ]), lm, covered)
+  let cachedMade = 0
+  if (opened) {
+    const pages = prepared ? Lightmap.pageIds(prepared) : new Uint32Array(0)
+    cachedMade = await staticsBuild(opened, scene, roots.map((r) => covered.get(r.path)!.node!), pages, templateModel)
+  }
+  const nodesMs = Date.now() - tLoad
   if (navmesh && !(EDITOR && isEditMode())) registerNavOverrides(def.nodes, nodes)
 
   // a camera NODE wins over the top-level `camera:` block; in play mode it keeps driving the view
@@ -1004,12 +1061,35 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   }
 
   // the level is complete: apply the bake — or, under `lecodes lightmap bake`, run it
-  if (lm && lightmap) await Lightmap.load(scene, lightmap)
+  const tLm = Date.now()
+  if (lm && lightmap) { if (prepared) await Lightmap.apply(prepared); else await Lightmap.load(scene, lightmap) }
+  const lightmapMs = Date.now() - tLm
   // navigation: load the baked mesh — or, under `lecodes navmesh bake`, dump the level's collision
   // geometry for it (the static bodies exist by now; edit mode never loads it — v1)
+  const tNav = Date.now()
   if (navmesh && !(EDITOR && isEditMode())) {
     await NavMesh.load(scene, { data: navmesh.data, agent: navmesh.agent, areas: navmesh.areas })
   }
+  const navMs = Date.now() - tNav
+  const glbMs = loadStats.glb > 0 ? Math.max(0, loadStats.glbLast - loadStats.glbFirst) : 0
+  console.log(`[load] ${Date.now() - tLoad} ms: nodes ${nodesMs} (${Object.keys(nodes).length} top, glb ${loadStats.glb} in ${glbMs}, clones ${loadStats.clones} in ${loadStats.cloneMs}, aspects ${loadStats.aspectsMs}${cachedMade ? `, ${cachedMade} static placement(s) from the cache` : ""}), lightmap ${lightmapMs}, navmesh ${navMs}`)
+
+  // `lecodes static`: the level is complete and bound — snapshot the covered subtree beside the bake
+  if (staticsCfg && lightmap) {
+    const out = `${staticsCfg.root}/${lightmap.path.replace(/\.bake$/, ".static")}`
+    const live = roots.map((r) => ({ root: r, node: findNode(nodes, r.path) }))
+    const lost = live.filter((r) => !r.node)
+    if (roots.length === 0) console.error("[static] error: nothing to cache — the level has no static subtree (models and their colliders under plain nodes)")
+    else if (lost.length > 0) console.error(`[static] error: no live node for ${lost.map((r) => r.root.path).join(", ")}`)
+    else if (!_creator.staticsWrite) console.error("[static] error: this host cannot write the cache (build the desktop host)")
+    else {
+      const bake = Lightmap._bakeData()
+      const snap = staticsSnapshot(live as { root: CoveredRoot, node: Node }[], def, bake, defsDigest(roots, def))
+      if (_creator.staticsWrite(out, snap.bytes)) console.log(`[static] wrote ${out}: ${snap.placements} placement(s) of ${snap.kinds} kind(s), ${snap.records} bake record(s), ${(snap.bytes.length / 1024).toFixed(0)} KB${bake ? "" : " (no bake bound)"}`)
+      else console.error(`[static] error: could not write ${out}`)
+    }
+    console.log("[static] done")
+  }
 
   return { scene, nodes }
 }

package/src/server/env.ts

@@ -0,0 +1,25 @@
+/**
+ * `env` on the SERVER — every key of the project (src/core/env.ts says what `env` is). The values
+ * (Settings → Keys on le.codes, the project's `.env` on this machine) are handed to the bundle by the
+ * host that runs it (`setEnv`) through the `globalThis.__lecodesEnv` seam — a global on purpose,
+ * like `__lecodesRequest`: the bundle carries its own SDK copy, so the host can't pass a value by
+ * import. The compile lists the names the server code reads (serverSplit.ts `scanEnvReads`) so a
+ * deploy can warn before any call does.
+ */
+
+import { makeEnv, type Env } from "../core/env"
+export { ENV_NAME, PUBLIC_ENV_PREFIX, isPublicEnvName, EnvError, type Env } from "../core/env"
+
+const seam = globalThis as unknown as { __lecodesEnv?: Record<string, string> }
+
+/** Host hook (runner / local backend / tests): the values the bundle reads. `null` = none set. */
+export const setEnv = (values: Record<string, string> | null) => {
+  if (values) seam.__lecodesEnv = { ...values }
+  else delete seam.__lecodesEnv
+}
+
+/** @internal */
+export const currentEnv = (): Record<string, string> => seam.__lecodesEnv ?? {}
+
+/** The project's keys. A missing key throws `EnvError` on read. */
+export const env: Env = makeEnv(currentEnv)

package/src/server/host.ts

@@ -10,6 +10,8 @@ export {
 } from "./runtime"
 export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration, SeedOutcome } from "./runtime"
 export type { RequestContext } from "./context"
+export { setEnv, EnvError, ENV_NAME, PUBLIC_ENV_PREFIX, isPublicEnvName } from "./env"
+export type { Env } from "./env"
 export { createChannelHub } from "./channelHub"
 export type { ChannelHub, ChannelHubOptions, HubConnection, HubFanout } from "./channelHub"
 export type { ChannelGroup, ClientFrame, ServerFrame } from "../runtime/wire"
@@ -61,6 +63,9 @@ export type ServerDescription = {
   auth: { model: string | null }
   /** `app.json` name (when the compile embedded one). */
   appName?: string
+  /** The keys the server code reads (`env.NAME`, serverSplit.ts `scanEnvReads`): what a deploy checks
+   *  against the keys that are set, so a missing one is a warning before it is a failed call. */
+  env: string[]
 }
 
 const describeField = (f: Field<any, any>): FieldDescription => {
@@ -107,5 +112,6 @@ export const describeServer = (server: LoadedServer): ServerDescription => {
     pushChannels: [...server.pushChannels.keys()],
     auth: { model: db?.$auth?.model ?? null },
     appName: server.manifest.app?.name,
+    env: [...(server.manifest.env ?? [])],
   }
 }

package/src/server/inject.ts

@@ -3,12 +3,13 @@
  * chisel injects these into the server bundle exactly like ./inject.ts does for the client bundle;
  * nothing here may reach the client bundle. Keep this the ONLY file that exports server globals.
  *
- * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, pushChannel, request. Sign-in is
+ * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, pushChannel, request, env. Sign-in is
  * not a global: it is `db.auth` of a db made with `defineDb({...}).withAuth({ model })`.
  */
 
 export { t, model, defineDb, ref } from "./db"
 export { ApiError } from "./errors"
+export { env, type Env } from "./env"
 export { channel } from "./channel"
 export { pushChannel, type PushChannel, type PushMessage, type PushNotification, type PushTarget } from "./pushChannel"
 export { request } from "./context"

package/src/ui/fonts.ts

@@ -11,3 +11,49 @@ export async function registerFont (fontFamily: string, url: string, options: Fo
     _creatorTree.registerFont(fontFamily, url, options.weight ?? 400, options.style === "italic" ? 2 : 0, res, rej)
   })
 }
+
+// ---- the font() macro's faces --------------------------------------------------------------------
+// The `font("inter")` compile macro (compile/fontMacro.ts) emits one `__registerFont(...)` per face
+// into a generated `.__fonts.ts` module. That registers the face with the UI tree (in the host's
+// preferred container — woff2 on browsers) AND records its TTF URL here, so a `Font2D.load("Inter")`
+// (whose native parser reads TTF/OTF only, never woff2) takes the same identifier UI text takes.
+// The map is created on first use — no top-level side effect for chisel to drop.
+
+type FaceRecord = { family: string, weight: number, italic: boolean, url: string }
+
+let registeredFaces: Map<string, FaceRecord[]> | undefined   // lower-cased family → its faces
+const facesMap = (): Map<string, FaceRecord[]> => (registeredFaces ??= new Map())
+
+/** The macro's registration call (a bundle global, like `__rpc`). `url` is either a full URL (a
+ *  project / vendored entry) or a cdn base ending in "." — the format is appended here: the host's
+ *  for the UI tree, always ttf for 2D text. */
+export function __registerFont (family: string, url: string, weight: number, italic: boolean): void {
+  const base = url.endsWith(".")
+  const ttfUrl = base ? url + "ttf" : url
+  const key = family.toLowerCase()
+  const faces = facesMap().get(key) ?? []
+  const same = faces.find((f) => f.weight === weight && f.italic === italic)
+  if (same) same.url = ttfUrl
+  else faces.push({ family, weight, italic, url: ttfUrl })
+  facesMap().set(key, faces)
+  _creatorTree.registerFont(family, base ? url + (_creatorTree.fontFormat ?? "ttf") : url, weight, italic ? 2 : 0, () => {}, () => {})
+}
+
+/** @internal The TTF URL of a `font()`-registered face: the exact (weight, italic) face first, else
+ *  the nearest registered weight of that family in that style (a tie goes to the heavier), else
+ *  undefined. Family names match case-insensitively. */
+export function _fontUrlOf (family: string, weight = 400, italic = false): string | undefined {
+  const faces = registeredFaces?.get(family.toLowerCase())?.filter((f) => f.italic === italic)
+  if (!faces || faces.length === 0) return undefined
+  let best = faces[0]!
+  for (const f of faces) {
+    const d = Math.abs(f.weight - weight), bd = Math.abs(best.weight - weight)
+    if (d < bd || (d === bd && f.weight > best.weight)) best = f
+  }
+  return best.url
+}
+
+/** @internal The registered families (their declared spelling) — for "unknown family" errors. */
+export function _registeredFontFamilies (): string[] {
+  return registeredFaces ? [ ...registeredFaces.values() ].map((faces) => faces[0]!.family) : []
+}

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.4.10"
+export const SDK_VERSION = "2.5.0"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {