lecodes-sdk 2.4.10 → 2.5.1

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.4.10",
+  "version": "2.5.1",
   "files": [
     "src",
     "dist",

package/src/bridges/2d.d.ts

@@ -50,8 +50,9 @@ declare global {
     addEntityToScene(sceneId: i32, entityId: i32): void
     /** @c c2dRemoveEntityFromScene */
     removeEntityFromScene(sceneId: i32, entityId: i32): void
-    /** @c c2dSetLayerYSort */
-    setLayerYSort(sceneId: i32, layer: i32, enabled: boolean): void
+    /** Y-sort: among entities of one renderPriority and one z, the one lower on screen (smaller world Y)
+     *  draws on top — top-down depth. One flag per scene. @c c2dSetYSort */
+    setYSort(sceneId: i32, enabled: boolean): void
 
     /** @c c2dCameraSetPosition */
     cameraSetPosition(sceneId: i32, x: f32, y: f32): void
@@ -76,10 +77,14 @@ declare global {
     setRotation(entityId: i32, deg: f32): void
     /** @c c2dSetScale */
     setScale(entityId: i32, sx: f32, sy: f32): void
-    /** @c c2dSetLayer */
-    setLayer(entityId: i32, layer: i32): void
-    /** @c c2dSetZ */
+    /** Coarse draw order 0 (first) … 7 (last), default 4 — the 3D Mesh.renderPriority. Within one
+     *  priority `z` orders, then Y-sort. @c c2dSetRenderPriority */
+    setRenderPriority(entityId: i32, priority: i32): void
+    /** Draw order within a renderPriority (higher = on top). @c c2dSetZ */
     setZ(entityId: i32, z: f32): void
+    /** The node's Material2D as the three ints the renderer batches by: blend 0 alpha / 1 additive;
+     *  filter 0 renderer default / 1 nearest / 2 linear; wrap 0 clamp / 1 repeat. @c c2dSetMaterial */
+    setMaterial(entityId: i32, blend: i32, filter: i32, wrap: i32): void
     /** @c c2dSetVisible */
     setVisible(entityId: i32, visible: boolean): void
     /** @c c2dGetPosition @out 2 */
@@ -131,6 +136,9 @@ declare global {
     destroyTexture(texId: i32): void
     /** @c c2dSetDefaultFilter */
     setDefaultFilter(linear: boolean): void
+    /** The engine's 1x1 white texture — a sprite without art is a solid rect of its tint, and vector
+     *  fills draw through it in the sprite batch. Created on first use. @c c2dWhiteTexture */
+    whiteTexture(): i32
 
     // Textures from a _creatorCanvas surface (RGBA8, already rasterized — no decode, so synchronous).
     // See ./canvas.d.ts.
@@ -155,6 +163,58 @@ declare global {
     /** @c c2dSetTile */
     setTile(tilemapId: i32, x: i32, y: i32, index: i32): void
 
+    // Paths (Path2D): vector strokes and fills in the entity's local frame, drawn through the white
+    // texture so they batch with sprites. pts = x,y pairs; count = points.
+    /** Turns the entity into a path (as setSprite makes a sprite) and sets its outer ring. @c c2dSetPath */
+    setPath(entityId: i32, pts: Float32Array, count: i32, closed: boolean): void
+    /** @c c2dPathClearHoles */
+    pathClearHoles(entityId: i32): void
+    /** A hole ring (fills only). @c c2dPathAddHole */
+    pathAddHole(entityId: i32, pts: Float32Array, count: i32): void
+    /** width <= 0 = no stroke; widthPx = logical screen px (constant while zooming) else world units;
+     *  join 0 miter / 1 round / 2 bevel; cap 0 butt / 1 round / 2 square. @c c2dSetPathStroke */
+    setPathStroke(entityId: i32, width: f32, widthPx: boolean, join: i32, cap: i32, r: f32, g: f32, b: f32, a: f32): void
+    /** @c c2dSetPathFill */
+    setPathFill(entityId: i32, enabled: boolean, r: f32, g: f32, b: f32, a: f32): void
+    /** The stroke's outline: a band of `width` (the stroke's units) around it, drawn in the engine's UNDER
+     *  pass — at one z every node's outline lies under every node's body, so roads merge at junctions.
+     *  0 = none. @c c2dSetPathOutline */
+    setPathOutline(entityId: i32, width: f32, r: f32, g: f32, b: f32, a: f32): void
+    /** The 1-px anti-alias fringe, on by default (off for crisp pixel-art lines). @c c2dSetPathAntialias */
+    setPathAntialias(entityId: i32, enabled: boolean): void
+
+    // Text (Text2D): fonts parsed natively (TTF/OTF bytes from a host fetch buffer), glyphs rasterized
+    // as signed distance fields into one atlas per font — one atlas for every size.
+    /** @custom */
+    createFont(systemId: bytes, onComplete: (fontId: number) => void, onReject: (e: any) => void): void
+    /** @c c2dDestroyFont */
+    destroyFont(fontId: i32): void
+    /** Turns the entity into a text (as setSprite makes a sprite). size = em height in world units, or in
+     *  logical screen px when sizePx (constant on screen while zooming). The block is anchored by
+     *  setSpriteAnchor. @c c2dSetText */
+    setText(entityId: i32, fontId: i32, text: string, size: f32, sizePx: boolean): void
+    /** align 0 left / 1 center / 2 right; maxWidth in `size` units (0 = no wrap); lineHeight a multiplier
+     *  of the font's own (0 = the font's); letterSpacing in em. @c c2dSetTextStyle */
+    setTextStyle(entityId: i32, align: i32, maxWidth: f32, lineHeight: f32, letterSpacing: f32): void
+    /** @c c2dSetTextColor */
+    setTextColor(entityId: i32, r: f32, g: f32, b: f32, a: f32): void
+    /** A halo, width in em (0 = none, up to ~0.15). @c c2dSetTextOutline */
+    setTextOutline(entityId: i32, width: f32, r: f32, g: f32, b: f32, a: f32): void
+    /** The laid-out block [width, height] in `size` units. @c c2dGetTextSize @out 2 */
+    getTextSize(entityId: i32): Float32Array
+
+    // Particles (Particles2D): one creator-particles system per entity — the 3D engine's simulation and
+    // its config records (sdk/src/core/particlesConfig.ts), drawn through the 2D batcher.
+    /** Turns the entity into a particle system (as setSprite makes a sprite): the sheet texture (0 = solid
+     *  squares of the particle colour) and its flipbook grid; maxParticles 0 = the default (1000). @c c2dSetParticles */
+    setParticles(entityId: i32, textureId: i32, sheetCols: i32, sheetRows: i32, maxParticles: i32): void
+    /** The config records, [tag, payloadLen, ...payload] — the same buffer `_creator.setParticleSystemConfig` takes. @c c2dParticlesConfig */
+    particlesConfig(entityId: i32, data: Float32Array): void
+    /** A burst at the emitter's current place. @c c2dParticlesSpawn */
+    particlesSpawn(entityId: i32, count: f32): void
+    /** @c c2dParticlesAlive */
+    particlesAlive(entityId: i32): i32
+
     /** @c c2dBulkSetPositions */
     bulkSetPositions(ids: Uint32Array, xy: Float32Array, count: i32): void
 

package/src/bridges/gl.d.ts

@@ -14,14 +14,17 @@ export type PickBone = { name: string, weight: f32 }
  *  `bones` = its JOINTS_0 / WEIGHTS_0 pairs with weight > 0 (empty = unweighted). */
 export type PickVertex = { index: u32, bind: [f32, f32, f32], world: [f32, f32, f32], bones: PickBone[] }
 /** The closest triangle under a screen point (`pickTriangle`). `node` = the mesh node's own entity (0
- *  when the host has none), `lightmapOrdinal` = the primitive's index over the file's meshes (the bake's record
- *  `<key>@<ordinal>`), `uv1` (the lightmap uv the GPU reads: the bake's packed one when loaded) only when the primitive
- *  carries one. */
+ *  when the host has none), `lightmapOrdinal` = the primitive's index over the file's walked nodes' primitives (the bake's
+ *  record `<key>@<ordinal>`; a LOD twin's = its base's), `uv1` (the lightmap uv the GPU reads: the bake's packed one when loaded) only when the primitive
+ *  carries one, `lightmapTexture` + `lightmapST` = the rect the primitive draws with (lightmapApply's: the light page's
+ *  texture id, 0 = none, and [sx, sy, ox, oy]) - what `Lightmap.probe` reads under the static level cache, where a
+ *  static has no JS node to ask. */
 export type TrianglePick = {
   entity: u32, node: u32, nodeName: string, lightmapOrdinal: u32,
   mesh: string, primitive: u32, material: string,
   triangle: u32, backface: boolean, distance: f32,
   point: [f32, f32, f32], bary: [f32, f32, f32], uv1?: [f32, f32],
+  lightmapTexture: u32, lightmapST?: [f32, f32, f32, f32],
   skin: string, vertices: PickVertex[],
 }
 
@@ -297,6 +300,20 @@ declare global {
      *  with the source's own buffers and material instances. Returns the renderables made (0 = nothing scattered).
      *  Absent on a host without it: Scatter then clones the model per placement. @count count=placements/5 */
     createGlbScatter?(entityId: u32, sourceId: u32, placements: Float32Array, cell: f32, castShadows: boolean): u32
+    /** The static level cache (gl/Statics.ts ↔ creator-gl/src/statics.cpp). `staticsWrite` puts the snapshot's bytes
+     *  at an absolute path (the `lecodes static` run; a host without a file system leaves it out). `staticsBegin`
+     *  takes the fetched cache for the level under `roots` (the covered subtrees' entities, in the snapshot's order)
+     *  in `sceneId` and builds its body-only placements
+     *  (returns the kind count, 0 = not a cache); `staticsBuildKind` clones `templateEntity` at every placement of
+     *  that kind, binding the bake's records to `pages` (light, aux per page, interleaved) and creating the static
+     *  bodies; `staticsEnd` reports and frees. Absent on a host without it: the level builds the slow way.
+     *  @count size=data */
+    staticsWrite?(path: string, data: Uint8Array): boolean
+    /** @count rootCount=roots */
+    staticsBegin?(sceneId: u32, roots: Uint32Array, cache: bytes): u32
+    /** @count count=pages */
+    staticsBuildKind?(kind: u32, templateEntity: u32, pages: Uint32Array): u32
+    staticsEnd?(): u32
     setCulling(entityId: u32, culling: boolean): void
     /** Filament RenderableManager::setPriority — the coarse draw order, 0..7 (Mesh.renderPriority).
      *  Optional: an older host leaves everything at the default 4. */
@@ -696,9 +713,9 @@ declare global {
      *  `Shape.fit()` measures. Optional: absent on hosts predating the binding. @out 6 */
     computeBoundingBox?(entityId: u32): Float32Array
     /** DEBUG pick: the closest TRIANGLE under a screen point (logical px) among the loaded GLB instances —
-     *  entityId = one Model's root, 0 = every instance — CPU-skinned with the joints' CURRENT pose, both
-     *  faces. null on a miss. One full CPU skin per call — click-rate only. Optional: a debug tool, hosts
-     *  may lack it. */
+     *  entityId = one Model's root, 0 = every instance IN THE SCENE and drawn (a hidden LOD level, an
+     *  off-scene template are skipped) — CPU-skinned with the joints' CURRENT pose, both faces. null on a
+     *  miss. One full CPU skin per call — click-rate only. Optional: a debug tool, hosts may lack it. */
     pickTriangle?(entityId: u32, screenX: f32, screenY: f32): TrianglePick | null
     setColliderFromMesh(entityId: u32, meshEntityId: u32, form: i32): void
     setColliderBox(entityId: u32, centerX: f64, centerY: f64, centerZ: f64, sizeX: f64, sizeY: f64, sizeZ: f64): void
@@ -744,8 +761,11 @@ declare global {
                   transmit?: string, tracer?: u32, denoiser?: u32, thinTexels?: f32, objectSlab?: f32, cubeKeys?: string, cubeIds?: Uint32Array): boolean
     /** Lightmap consumption: the next createGlb takes lightmap.filamat (the material behind that instance id) for its
      *  OPAQUE materials and the masked twin for its MASK materials instead of the ubershader, and keeps TEXCOORD_1;
-     *  BLEND (glass) materials always keep the ubershader. 0xFFFFFFFF clears. The same call arms the foliage tier. @custom */
-    setNextGlbLightmapped?(materialInstanceId: u32, maskedMaterialInstanceId?: u32): void
+     *  BLEND (glass) materials always keep the ubershader. 0xFFFFFFFF clears. The same call arms the foliage tier;
+     *  `impostorMaterialInstanceId` (a tree's: foliage-impostor.filamat) goes to the MASK material whose glTF extras carry
+     *  `lecodes.impostor` = [A, cx, cy, cz, r, E] — the impostor lecodes-assets bakes as a tree's last LOD level —
+     *  in place of the masked twin (omitted / 0xFFFFFFFF = none). @custom */
+    setNextGlbLightmapped?(materialInstanceId: u32, maskedMaterialInstanceId?: u32, impostorMaterialInstanceId?: u32): void
     /** The level-wide scale every lightmap-material instance shares (present and future): lux per encoded 1.0 of the
      *  light atlas — the .bake's `lightScale` times whatever multiplier a debug knob wants. `emissiveNits` = the bake's
      *  radiance of emission 1.0 (the .bake's `emissiveNits`): over 0 the statics' glow is drawn scene-referred with it -
@@ -770,7 +790,7 @@ declare global {
                        lox: f32, loy: f32, loz: f32, sx: f32, sy: f32, sz: f32): u32
     /** Bind the light page + the aux page + a RECORD's rect (uv1 * [sx, sy] + [ox, oy]) and move the renderables it went on
      *  to light channel 1 alone — a baked static takes nothing from the real-time sun and lamps (channel 0). The bake's
-     *  unit is the mesh: a GLB instance is one record per primitive (`<key>@<ordinal>` in the .bake); `ordinal` >= 0 binds
+     *  unit is the node's mesh: a GLB instance is one record per node primitive (`<key>@<ordinal>` in the .bake); `ordinal` >= 0 binds
      *  that primitive (its index over the file's meshes) of every node that draws it, on a material instance of its own;
      *  -1 (the default) = every lightmap-material primitive of the entity (a Mesh entity, a terrain). Returns how many
      *  material instances took it (0 = not loaded lightmapped). */
@@ -815,8 +835,8 @@ declare global {
     setLightChannel?(entityId: u32, channel: u32, enable: boolean): void
     /** Shadow flags on every renderable of a GLB instance (Mesh has setCastShadows/setReceiveShadows). */
     setGlbShadows?(entityId: u32, cast: boolean, receive: boolean): void
-    /** Foliage — the vegetation tier (`foliage.filamat` / `foliage-masked.filamat`, armed per model
-     *  through setNextGlbLightmapped; the engine knows the tier by its `benders` parameter). Level-wide WIND FIELD (the
+    /** Foliage — the vegetation tier (the bark `foliage` + the cards `foliage-cards` / `grass`, a tree's far
+     *  impostor `foliage-impostor`, armed per model through setNextGlbLightmapped; the engine knows the tier by its `benders` parameter). Level-wide WIND FIELD (the
      *  model of Unity HDRP's Wind.hlsl, 2026-09-23): direction on the ground (normalised by the host), speed m/s,
      *  turbulence 0..2 = the random share of the speed, gust 0..1 = the gust field's strength, gustSpeed m/s = how fast
      *  the gust pattern travels. The per-material drag / stiffness / lean / shiver profile comes from the GLB's material
@@ -830,10 +850,9 @@ declare global {
      *  leaf card takes (bark always all of it), skyAo 0..1 = how far the baked sky visibility darkens the ambient.
      *  Level-wide, present and future instances. */
     foliageSetLeaf?(shiver: f32, translucency: f32, leafShadow: f32, skyAo: f32): void
-    /** The look of the cards (2026-09-23): canopy 0..1 = the card's shading normal from its own plane to the crown's hull
-     *  normal (hides the flat quads), normalMap = the cards' normal-map strength, edgeFade = a card seen edge-on dissolves
-     *  over this much of |N·V|, coverage = alpha × (1 + coverage × mip level) so a distant crown keeps its density. */
-    foliageSetLook?(canopy: f32, normalMap: f32, edgeFade: f32, coverage: f32): void
+    /** The look of the cards: coverage = alpha × (1 + coverage × mip level) so a distant crown keeps its density as its
+     *  atlas mips away. */
+    foliageSetLook?(coverage: f32): void
     /** An entity whose live world position bends the vegetation within `radius` metres; <= 0 removes it. The host
      *  writes the 8 benders nearest the camera to the shader each frame. */
     foliageSetBender?(entityId: u32, radius: f32): void

package/src/compile/bakeMacro.ts

@@ -224,6 +224,9 @@ export const expandBakeMacros = async (
       if (manifest.probes) fields.push(`probes: ${ref1(manifest.probes)}`)
       if (manifest.volume) fields.push(`volume: ${ref1(manifest.volume)}`)
       if (manifest.uv1) fields.push(`uv1: ${ref1(manifest.uv1)}`)
+      // the static level cache beside the bake (gl/Statics.ts): staged when `lecodes static` has written it
+      const statics = target.replace(/\.bake$/, ".static")
+      if (exists(statics)) fields.push(`statics: asset(${JSON.stringify(statics)})`)
     } else {
       fields.unshift("data: null")
       fields.push("light: []", "aux: []")

package/src/compile/compileProject.ts

@@ -9,6 +9,7 @@ import { detectEntry } from "./detectEntry"
 import { buildHeader } from "./header"
 import { inlineSourceMapComment, offsetSourceMap } from "./sourcemap"
 import { ClientPublishError, clientPublishes, stubServerEntries } from "./serverSplit"
+import { checkClientEnvReads, ENV_VALUES_PATH, publicEnvOf } from "./envCompile"
 import { CODE_EXT } from "./assetMacro"
 import { escapeTemplate } from "./assetIconMacro"
 
@@ -76,6 +77,11 @@ export type CompileOptions = {
    *  files never reach the client bundle either way; with no URL, calling an endpoint fails with
    *  "server not deployed". */
   serverUrl?: string
+  /** The project's keys (`NAME: value` — the project's .env, or Settings → Keys): the `PUBLIC_*` ones are
+   *  baked into the bundle as `env.PUBLIC_*` (envCompile.ts), the rest never reach it. App code reading a
+   *  key that is not `PUBLIC_*` fails the compile (`ClientEnvError`); a `PUBLIC_*` key read but not given
+   *  is a warning. Absent = no keys: every app read throws at run time. */
+  env?: Record<string, string>
   /** The TEXT of a resource entry by its root path (`/assets/lightmap/level.bake`) — how `bake()` reads the manifest
    *  it names at compile time (the CLI: the file on disk). Without one, or null for a file, that bake() compiles to an
    *  unbaked level (a warning says so). */
@@ -86,7 +92,11 @@ export type CompileOptions = {
  *  preview inlines it) plus the entrypoint the compile used. `code` carries the metadata header
  *  unless `header: false`; `map` is already shifted past that header. `bakes` = the `bake()` targets
  *  the entry reaches (bakeMacro.ts). */
-export type CompileResult = { code: string, map: string | null, entry: string, bakes: BundleBake[] }
+export type CompileResult = {
+  code: string, map: string | null, entry: string, bakes: BundleBake[],
+  /** The keys app code reads (`env.PUBLIC_*`, envCompile.ts), sorted — what a settings page lists before any is set. */
+  envReads: string[]
+}
 
 /** The basename a local resource would be looked up by. */
 export const localAssetBase = (path: string): string => path.split(/[\\/]/).pop() ?? path
@@ -130,7 +140,8 @@ export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: strin
         // The host resolves the asset by name at runtime (reads the local file → systemId); the
         // "id:" prefix is the host's local-resource URL scheme (parsed by the UI + 2D texture paths).
         const name = localNames.get(e.path) ?? localAssetBase(e.path)
-        files[e.path] = `export default ("id:" + ${localAssetId(JSON.stringify(name))})`
+        // `__localAsset` (runtime/fetch.ts) records url ↔ name: the id is this run's, the name is stable
+        files[e.path] = `export default __localAsset("id:" + ${localAssetId(JSON.stringify(name))}, ${JSON.stringify(name)})`
       } else {
         files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`
       }
@@ -258,7 +269,16 @@ export const compileProjectWithMap = async (opts: CompileOptions): Promise<Compi
     throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
   }
 
+  // The project's keys: app code reads PUBLIC_* only (a secret's name there is an error), and the bundle
+  // carries the PUBLIC_* values as the compiled-in env-values module (envCompile.ts).
+  const envReads = checkClientEnvReads(opts.entries)
+  const publicEnv = publicEnvOf(opts.env ?? {})
+  const unset = [...envReads].filter(name => !(name in publicEnv)).sort()
+  if (unset.length && opts.onWarning) {
+    opts.onWarning(`The app reads env.${unset.join(", env.")} and ${unset.length === 1 ? "it is" : "they are"} not set — add ${unset.length === 1 ? "it" : "them"} to the project's .env (NAME=value) or to Settings → Keys; a read throws until then`)
+  }
   const files = entriesToFiles(entries, opts)
+  files[ENV_VALUES_PATH] = `export const values = ${JSON.stringify(publicEnv)}\n`
   const { code, map, bakes } = await bundleProjectWithMap(
     entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true, undefined, opts.readResource,
   )
@@ -269,11 +289,12 @@ export const compileProjectWithMap = async (opts: CompileOptions): Promise<Compi
       opts.onWarning(`The app uses ${missing.map(id => `"${id}"`).join(", ")} and app.json does not list ${missing.length === 1 ? "it" : "them"}: a plugin that is not listed is not there — in a shell built from this project and in the browser alike. Add to app.json: "plugins": { ${missing.map(id => `"${id}": "*"`).join(", ")} }`)
     }
   }
-  if (opts.header === false) return { code, map, entry, bakes }
+  const reads = [...envReads].sort()
+  if (opts.header === false) return { code, map, entry, bakes, envReads: reads }
   const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader, plugins })
   // Shift the map down past the header (prepended before the code).
   const headerLines = (header.match(/\n/g) ?? []).length
-  return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry, bakes }
+  return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry, bakes, envReads: reads }
 }
 
 /** The bundle as ONE string, the map inlined at its end (the shipped/preview form). */

package/src/compile/envCompile.ts

@@ -0,0 +1,74 @@
+/**
+ * The project's keys in the APP bundle (src/core/env.ts): what the compile bakes in, what it refuses,
+ * and the check that no secret's VALUE made it into a bundle.
+ *
+ * - `publicEnvOf`: of the project's keys, the `PUBLIC_*` ones — the only values the client bundle gets
+ *   (compileProject.ts writes them at ENV_VALUES_PATH, replacing src/runtime/envValues.ts).
+ * - `checkClientEnvReads`: app code (every code file that is not `*.server.ts`) may read `env.PUBLIC_*`
+ *   only; `env.STRIPE_KEY` there is a compile error naming the file — the bundle is public. A `PUBLIC_*`
+ *   name read but not set is a warning (the read throws at run time, src/core/env.ts).
+ * - `findEnvLeaks`: a secret pasted as a literal (`fetch(url, { headers: { key: "sk_live_…" } })`) is
+ *   what `env` cannot prevent — so where the values are known (the CLI's .env, the platform's keys)
+ *   the finished bundle text is searched for each non-public value, raw and JSON-escaped. Values
+ *   shorter than `minLength` (8) are too short to search for without false hits and are skipped.
+ */
+
+import { CODE_EXT } from "./assetMacro"
+import type { CompileEntry } from "./compileProject"
+import { isServerPath, scanEnvReads, serverModuleId } from "./serverSplit"
+import { isPublicEnvName } from "../core/env"
+
+/** The SDK's env-values placeholder (src/runtime/envValues.ts), overridden in the file map with the real ones. */
+export const ENV_VALUES_PATH = "/__sdk/runtime/envValues.ts"
+
+export const publicEnvOf = (env: Record<string, string>): Record<string, string> =>
+  Object.fromEntries(Object.entries(env).filter(([name]) => isPublicEnvName(name)).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))
+
+export class ClientEnvError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`a key that is not PUBLIC_* is a secret, and the app's bundle is public — read it in a *.server.ts file and call an endpoint, or name it PUBLIC_… if the app may carry it:\n  ${problems.join("\n  ")}`)
+    this.name = "ClientEnvError"
+    this.problems = problems
+  }
+}
+
+const isClientCode = (e: CompileEntry) =>
+  e.type === "text" && CODE_EXT.test(e.path) && !isServerPath(e.path) && !/^(\.\/|\/)?design\//.test(e.path.split("\\").join("/"))
+
+/** The `env` names app code reads, by file. Throws `ClientEnvError` on a name that is not `PUBLIC_*`. */
+export const checkClientEnvReads = (entries: CompileEntry[]): Set<string> => {
+  const reads = new Set<string>()
+  const problems: string[] = []
+  for (const e of entries) {
+    if (!isClientCode(e)) continue
+    for (const name of scanEnvReads(e.text ?? "")) {
+      if (isPublicEnvName(name)) reads.add(name)
+      else problems.push(`${serverModuleId(e.path)}: env.${name}`)
+    }
+  }
+  if (problems.length) throw new ClientEnvError(problems)
+  return reads
+}
+
+const escapeForSearch = (value: string) => JSON.stringify(value).slice(1, -1)
+
+/** The names of the keys whose value is in `text`, raw or JSON-escaped (`PUBLIC_*` ones are not secrets). */
+export const findEnvLeaks = (text: string, env: Record<string, string>, opts: { minLength?: number } = {}): string[] => {
+  const min = opts.minLength ?? 8
+  const out: string[] = []
+  for (const [name, value] of Object.entries(env)) {
+    if (isPublicEnvName(name) || value.length < min) continue
+    if (text.includes(value) || text.includes(escapeForSearch(value))) out.push(name)
+  }
+  return out.sort()
+}
+
+export class EnvLeakError extends Error {
+  readonly keys: string[]
+  constructor(keys: string[], where: string) {
+    super(`the value of ${keys.join(", ")} is in ${where} — a secret pasted into app code or an asset? The app's bundle is public: read a secret as env.${keys[0]} in a *.server.ts file and call an endpoint`)
+    this.name = "EnvLeakError"
+    this.keys = keys
+  }
+}

package/src/compile/fontMacro.ts

@@ -8,8 +8,9 @@
 //   font("./fonts/Brand.ttf")                     // project file → real family from its name table
 //
 // Registry ids resolve against the vendored snapshot (fontRegistry.ts). Two source modes:
-//   cdn    — faces stay remote: the generated code bakes registry URLs, picking woff2/ttf via the
-//            host's `_creatorTree.fontFormat` (absent → ttf). Platform/server-backed compiles.
+//   cdn    — faces stay remote: the generated code bakes the registry URL BASE (ending in "."); the
+//            runtime's `__registerFont` appends the host's `_creatorTree.fontFormat` (absent → ttf)
+//            for the UI tree and always ttf for 2D text (Font2D). Platform/server-backed compiles.
 //   vendor — the caller downloads faces into the project (assets/fonts/ + fonts.lock.json) and
 //            hands back their entry paths; faces then ride the normal asset pipeline (dev URLs,
 //            `id:` + fetchLocal, lecodesfile://) — fully offline, and local faces register
@@ -19,6 +20,10 @@
 // read from the font itself (sfnt.ts). Registration is idempotent per (family, weight, style) —
 // hosts dedupe — so several files declaring the same font cost nothing.
 //
+// The generated module calls the bundle global `__registerFont(family, url, weight, italic)`
+// (ui/fonts.ts), never `_creatorTree.registerFont` directly: it registers the face with the UI tree
+// AND records its TTF URL, so `Font2D.load("Manrope")` resolves the same identifier UI text takes.
+//
 // A file that DECLARES its own `font` identifier (function/const/import) is skipped entirely —
 // real scoping wins, the macro only exists where the global would.
 
@@ -408,8 +413,8 @@ export const applyFontMacro = async (entries: FontMacroEntry[], opts: FontMacroO
     fw.entry.text = text
 
     const lines: string[] = [
-      "// Generated by the font() compile macro: registers this file's fonts. Imports hoist, so the",
-      "// faces are declared before the importing module's body runs. Hosts dedupe repeated faces.",
+      "// Generated by the font() compile macro: registers this file's fonts (UI tree + Font2D). Imports",
+      "// hoist, so the faces are declared before the importing module's body runs. Hosts dedupe repeats.",
     ]
     const faceImports = new Map<string, string>() // entry path → import ident
     const body: string[] = []
@@ -417,7 +422,7 @@ export const applyFontMacro = async (entries: FontMacroEntry[], opts: FontMacroO
       const ref = faces.get(key)!
       let urlExpr: string
       if (ref.source.kind === "cdn") {
-        urlExpr = `${JSON.stringify(ref.source.urlBase)} + (_creatorTree.fontFormat ?? "ttf")`
+        urlExpr = JSON.stringify(ref.source.urlBase)   // ends in "." — __registerFont appends the format
       } else {
         let ident = faceImports.get(ref.source.path)
         if (!ident) {
@@ -427,7 +432,7 @@ export const applyFontMacro = async (entries: FontMacroEntry[], opts: FontMacroO
         }
         urlExpr = ident
       }
-      body.push(`_creatorTree.registerFont(${JSON.stringify(ref.family)}, ${urlExpr}, ${ref.weight}, ${ref.italic ? 2 : 0}, () => {}, () => {})`)
+      body.push(`__registerFont(${JSON.stringify(ref.family)}, ${urlExpr}, ${ref.weight}, ${ref.italic})`)
     }
     for (const [family, ident] of idents) lines.push(`export const ${ident} = ${JSON.stringify(family)}`)
     lines.push(...body)

package/src/compile/index.ts

@@ -9,6 +9,7 @@ export {
   ClientPublishError,
   scanServerExports,
   scanServerModules,
+  scanEnvReads,
   stubServerEntries,
   serverStubSource,
   serverEntrySource,
@@ -21,6 +22,8 @@ export {
   type ServerManifest,
 } from "./serverSplit"
 export { deriveEndpointParams, EndpointTypeError, ServerHelperImportError, UnawaitedUserQueryError, WrongSideGlobalError, type DeriveResult } from "./serverTypes"
+export { checkClientEnvReads, ClientEnvError, ENV_VALUES_PATH, EnvLeakError, findEnvLeaks, publicEnvOf } from "./envCompile"
+export { ENV_NAME, PUBLIC_ENV_PREFIX, isPublicEnvName } from "../core/env"
 export {
   detectEntry,
   scanModulesFallback,
@@ -64,6 +67,9 @@ export {
   type ShaderParamValue,
 } from "./shaderSchema"
 export { offsetSourceMap, inlineSourceMapComment } from "./sourcemap"
+// the static level cache's file format (gl/staticsFormat.ts): `lecodes level build` / `lightmap bake` stitch a bake's
+// records into a cache without a host run
+export { decode as decodeStatics, encode as encodeStatics, stitch as stitchStatics, readHeader as readStaticsHeader, bakeDigest as staticsBakeDigest, type StaticsFile } from "../gl/staticsFormat"
 export { buildHeader, detectProjectKind, type HeaderOptions } from "./header"
 export {
   compileProject,

package/src/compile/resourceSlots.ts

@@ -18,6 +18,7 @@ export const resourceSlots = {
     registerFont: [ 1 ],
     fetchLocal: [ 0 ],
     "Texture2D.load": [ 0 ],
+    "Font2D.load": [ 0 ],
     "Texture.load": [ 0 ],
     "Model.load": [ 0 ],
     "AnimationClip.load": [ 0 ],

package/src/compile/serverSplit.ts

@@ -36,20 +36,39 @@ export type ServerExport = { name: string, kind: ServerExportKind }
 // ───────────────────────────── static export scan ─────────────────────────────
 
 /** Blank out comments and string/template contents (keeps line structure) so the regexes below don't
- *  trip on `export` inside a comment or a string. */
-export const blankCommentsAndStrings = (src: string): string => {
+ *  trip on `export` inside a comment or a string. `templateCode`: a template's `${…}` stays code
+ *  (`scanEnvReads`: a key read inside an interpolation is a read). */
+export const blankCommentsAndStrings = (src: string, opts: { templateCode?: boolean } = {}): string => {
   let out = ""
   let i = 0
   const n = src.length
+  /** templateCode: the brace depth inside each open `${`. */
+  const holes: number[] = []
+  /** A template's text from `i` to its closing backtick, or to a `${` that stays code (templateCode). */
+  const templateText = () => {
+    while (i < n && src[i] !== "`") {
+      if (src[i] === "\\") { out += "  "; i += 2; continue }
+      if (opts.templateCode && src[i] === "$" && src[i + 1] === "{") { out += "${"; i += 2; holes.push(0); return }
+      out += src[i] === "\n" ? "\n" : " "; i++
+    }
+    out += "`"; i++
+  }
   while (i < n) {
     const c = src[i], d = src[i + 1]
+    if (holes.length && c === "{") { holes[holes.length - 1]++; out += c; i++; continue }
+    if (holes.length && c === "}") {
+      out += c; i++
+      if (holes[holes.length - 1]-- === 0) { holes.pop(); templateText() }
+      continue
+    }
+    if (c === "`") { out += c; i++; templateText(); continue }
     if (c === "/" && d === "/") { while (i < n && src[i] !== "\n") { out += " "; i++ } continue }
     if (c === "/" && d === "*") {
       out += "  "; i += 2
       while (i < n && !(src[i] === "*" && src[i + 1] === "/")) { out += src[i] === "\n" ? "\n" : " "; i++ }
       out += "  "; i += 2; continue
     }
-    if (c === '"' || c === "'" || c === "`") {
+    if (c === '"' || c === "'") {
       const q = c
       out += q; i++
       while (i < n && src[i] !== q) {
@@ -112,6 +131,26 @@ export const scanServerExports = (source: string, path = "<server module>"): Ser
   return found.sort((a, b) => a.at - b.at).map(({ name, kind }) => ({ name, kind }))
 }
 
+// ───────────────────────────── env reads ─────────────────────────────
+
+/**
+ * The keys a server module reads: `env.NAME`, `env["NAME"]`, `env['NAME']` — by name, so a deploy can
+ * say which of them is not set before a call fails (`env` throws on a missing key, src/server/env.ts).
+ * A dynamic read (`env[name]`) is not seen and is checked at run time only. `process.env.X` and any
+ * other `.env.X` member chain is not a read of the global.
+ */
+export const scanEnvReads = (source: string): string[] => {
+  const out = new Set<string>()
+  const src = blankCommentsAndStrings(source, { templateCode: true })
+  for (const m of src.matchAll(/(?<![\w$.])env\s*\.\s*([A-Z][A-Z0-9_]*)\b/g)) out.add(m[1])
+  // the bracket form names the key in a string: find the sites on the blanked text, read the name off the original
+  for (const m of src.matchAll(/(?<![\w$.])env\s*\[\s*(["'])\s*\1\s*\]/g)) {
+    const inner = /\[\s*(["'])([A-Z][A-Z0-9_]*)\1\s*\]/.exec(source.slice(m.index!, m.index! + m[0].length))
+    if (inner) out.add(inner[2])
+  }
+  return [...out].sort()
+}
+
 // ───────────────────────────── client stubs ─────────────────────────────
 
 /** The client-side replacement of a `*.server.ts` module. `serverUrl` is baked in (draft/prod are
@@ -198,6 +237,8 @@ export type ServerManifest = {
   /** The `app.json` subset the server runtime reads (the app's name); the bundle itself gets it as the
    *  compiled-in `appConfig` module (APP_CONFIG_PATH). */
   app?: AppConfig
+  /** The keys the server files read by name (`scanEnvReads`), sorted, unique. */
+  env?: string[]
 }
 
 /** The synthetic entry: imports every export by name (chisel has no namespace imports) and registers
@@ -292,7 +333,9 @@ export const compileServerBundle = async (opts: CompileServerOptions): Promise<{
     for (const w of derived.warnings) console.warn(`warning: ${w}`)
     params = derived.params
   }
-  const manifest: ServerManifest = { modules: Object.fromEntries(Object.entries(modules).map(([p, ex]) => [serverModuleId(p), ex])), params, app: opts.app }
+  const envReads = new Set<string>()
+  for (const e of opts.entries) if (e.type === "text" && isServerPath(e.path)) for (const n of scanEnvReads(e.text ?? "")) envReads.add(n)
+  const manifest: ServerManifest = { modules: Object.fromEntries(Object.entries(modules).map(([p, ex]) => [serverModuleId(p), ex])), params, app: opts.app, env: [...envReads].sort() }
   if (opts.app) files[APP_CONFIG_PATH] = `export const app = ${JSON.stringify(opts.app)}\n`
   files[SERVER_ENTRY_PATH] = serverEntrySource(modules, manifest)
   const { code } = await bundleProjectWithMap(

package/src/core/env.ts

@@ -0,0 +1,47 @@
+/**
+ * The project's keys as code reads them: `env.NAME` — one word on both sides. Server code
+ * (`*.server.ts`, src/server/env.ts) reads every key; the app (src/runtime/env.ts) only the
+ * `PUBLIC_*` ones, baked into its bundle at compile time — a bundle is public, so a key the app
+ * carries is public by its name, and the compile refuses any other name in app code.
+ *
+ * A key is a `string`, never `string | undefined`: reading one that is not set THROWS `EnvError`,
+ * with the fix in the message. `"NAME" in env` tells without throwing; `Object.keys(env)` lists
+ * what is set. Only a key's shape throws: `then`, symbols, inspection hooks read as undefined, so
+ * `await env`, `console.log(env)` and JSON.stringify behave.
+ */
+
+export type Env = { readonly [name: string]: string }
+
+/** How a key is named — in `.env`, in Settings → Keys, in code. */
+export const ENV_NAME = /^[A-Z][A-Z0-9_]{0,63}$/
+/** A key the app may carry: the only names the client bundle gets. */
+export const PUBLIC_ENV_PREFIX = "PUBLIC_"
+export const isPublicEnvName = (name: string) => name.startsWith(PUBLIC_ENV_PREFIX)
+
+export class EnvError extends Error {
+  readonly key: string
+  constructor(key: string) {
+    super(`env.${key} is not set — add ${key} to the project's .env (on this machine) or to Settings → Keys (on le.codes)`)
+    this.name = "EnvError"
+    this.key = key
+  }
+}
+
+/** The `env` object over a source of values (read on every access: the server's are set by the host). */
+export const makeEnv = (read: () => Record<string, string>): Env => new Proxy({} as Env, {
+  get(_t, name) {
+    if (typeof name !== "string" || !ENV_NAME.test(name)) return undefined
+    const values = read()
+    if (!(name in values)) throw new EnvError(name)
+    return values[name]
+  },
+  has(_t, name) { return typeof name === "string" && name in read() },
+  ownKeys() { return Object.keys(read()) },
+  getOwnPropertyDescriptor(_t, name) {
+    const values = read()
+    if (typeof name !== "string" || !(name in values)) return undefined
+    return { value: values[name], enumerable: true, configurable: true, writable: false }
+  },
+  set() { throw new TypeError("env is read-only: keys are set in .env or Settings → Keys") },
+  deleteProperty() { throw new TypeError("env is read-only: keys are set in .env or Settings → Keys") },
+})