lecodes-sdk 1.0.0 → 1.1.0

package/src/compile/compileProject.ts

@@ -74,17 +74,47 @@ export type CompileOptions = {
  *  unless `header: false`; `map` is already shifted past that header. */
 export type CompileResult = { code: string, map: string | null, entry: string }
 
+/** The basename a local resource would be looked up by. */
+export const localAssetBase = (path: string): string => path.split(/[\\/]/).pop() ?? path
+
+/**
+ * Runtime lookup names for `localAssets` resources — what the bundle passes to `fetchLocal` and what
+ * a host caller must copy the file to.
+ *
+ * The basename, unless two project files SHARE one: then every sharer takes its whole root-relative
+ * path with the separators folded into `__`. A flat name space is fine until it isn't, and when it
+ * isn't the failure is silent and absurd — the files are staged into one directory, so the last one
+ * copied answers for every `asset()` that ends in that name. Which one wins depends on the scan
+ * order, i.e. on nothing. (2026-09-17: a viewer project carried two asset packs that each ship
+ * `SM_Sign_01..03.glb`; the school's floor-standing "CLEANING IN PROGRESS" A-frame was drawn inside
+ * the shooting range's wall, where a flat 4 mm plate belonged.)
+ */
+export const localAssetNames = (entries: readonly { path: string, type: string }[]): Map<string, string> => {
+  const seen = new Map<string, number>()
+  for (const e of entries) if (e.type === "resource") {
+    const b = localAssetBase(e.path)
+    seen.set(b, (seen.get(b) ?? 0) + 1)
+  }
+  const names = new Map<string, string>()
+  for (const e of entries) if (e.type === "resource") {
+    const b = localAssetBase(e.path)
+    names.set(e.path, (seen.get(b) ?? 0) > 1 ? e.path.replace(/^[./]+/, "").replace(/[\\/]/g, "__") : b)
+  }
+  return names
+}
+
 /** Turn compile entries into the bundler's module map — the per-kind rules of the deployable
  *  bundle (resource → URL export, shader → per-backend URL template, .svg → SvgSource, .json →
  *  data, code verbatim). Exported for callers that build a `libraries` map from entries. */
 export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: string, localAssets?: boolean }): Record<string, string> => {
   const files: Record<string, string> = {}
+  const localNames = localAssetNames(entries)
   for (const e of entries) {
     if (e.type === "resource") {
       if (opts.localAssets && !e.remote) {
         // 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 = e.path.split(/[\/]/).pop() ?? e.path
+        const name = localNames.get(e.path) ?? localAssetBase(e.path)
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(name)}))`
       } else {
         files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`

package/src/compile/detectEntry.ts

@@ -37,9 +37,14 @@ export type DetectedEntry = {
 export const ENTRY_CONVENTION = "/main.ts"
 
 const isCode = (path: string) => /\.[tj]s$/.test(path) && !path.endsWith(".d.ts")
-/** Never entries: editor plugins and server modules (docs/backend-plan.md — a `*.server.ts` nobody
- *  imports is still not the app; server files compile into their own bundle). */
-const isNonEntry = (path: string) => path.endsWith(".editor.ts") || /\.server\.[tj]s$/.test(path)
+/** Never entries: editor plugins, server modules (docs/backend-plan.md — a `*.server.ts` nobody
+ *  imports is still not the app; server files compile into their own bundle) and anything under
+ *  `design/` — the board's screens are import-graph roots by construction (nothing imports a screen
+ *  file; the board runs them), so without this a project whose app code is still to come had its
+ *  largest design screen picked as the app and failed deep inside it ("asset not found:
+ *  ../assets/figma/…"). A design-only project has no entry, and says so. */
+const isNonEntry = (path: string) =>
+  path.endsWith(".editor.ts") || /\.server\.[tj]s$/.test(path) || /^\/design\//.test(path)
 
 const normalize = (path: string): string => {
   const parts: string[] = []

package/src/compile/index.ts

@@ -65,6 +65,8 @@ export {
   compileProject,
   compileProjectWithMap,
   entriesToFiles,
+  localAssetNames,
+  localAssetBase,
   type CompileEntry,
   type CompileOptions,
   type CompileFileType,

package/src/compile/serverSplit.ts

@@ -210,11 +210,17 @@ export type CompileServerOptions = {
 export const compileServerBundle = async (opts: CompileServerOptions): Promise<{ code: string, manifest: ServerManifest } | null> => {
   const modules = scanServerModules(opts.entries)
   if (Object.keys(modules).length === 0) return null
+  // The server bundle sees the whole project map (a server module may import shared code), but the
+  // bundler's asset check runs over EVERY file in the map — so binaries and svgs must be present as
+  // stubs, or a client screen's `asset("./x.png")` fails the SERVER build ("asset not found", seen
+  // with a Figma-exported design next to app.server.ts). The board's `design/` files are never
+  // server code and stay out entirely.
   const files: MemoryFiles = {}
   for (const e of opts.entries) {
-    if (e.type !== "text") continue
-    if (e.path.toLowerCase().endsWith(".svg")) continue
-    files[normalizePath(e.path)] = e.text ?? ""
+    const path = normalizePath(e.path)
+    if (/^\/design\//.test(path)) continue
+    if (e.type !== "text" || path.toLowerCase().endsWith(".svg")) { files[path] = `export default ""`; continue }
+    files[path] = e.text ?? ""
   }
   let params = opts.params
   if (!params && opts.validate !== false) {

package/src/g2/Node2D.ts

@@ -16,6 +16,19 @@ import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { ensurePointerEvents } from "./touch"
 import { ensurePhysicsEvents } from "./loop"
+import type { Animation } from "../animate/tween/Animation"
+import { CLOCK_GAME, DOM_NODE2D, floatValue, vec2Value, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import { tweenBag } from "../animate/tween/Timeline"
+
+/** Animatable transform props of a 2D node; an array of values is a keyframe list. */
+export type Node2DTweenProps = {
+  x?: number | number[],
+  y?: number | number[],
+  position?: Vec2Like | Vec2Like[],
+  /** Degrees. */
+  rotation?: number | number[],
+  scale?: number | Vec2Like | (number | Vec2Like)[],
+}
 
 // re-exported so existing `import { Vec2 } from "./Node2D"` sites keep working; the canonical home is math/.
 export { Vec2, type Vec2Like }
@@ -135,6 +148,31 @@ export class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
     _creator2d.setScale(this.id, sx, sy)
   }
 
+  // --- keyframe animation (docs/timeline-plan.md) ---
+  /** Tween the transform — `node.animateTo({ x: 120, rotation: 90, duration: 400, easing: 'outBack' })`;
+   *  arrays are keyframes. Game clock unless `clock: 'ui'`. Returns the {@link Animation} handle. */
+  animateTo(props: Node2DTweenProps & TweenMeta): Animation {
+    return tweenBag(this, props as Record<string, unknown>, true)
+  }
+  /** Tween FROM the given values to the node's current transform. */
+  animateFrom(props: Node2DTweenProps & TweenMeta): Animation {
+    return tweenBag(this, props as Record<string, unknown>, false)
+  }
+  /** @internal keyframe-core target protocol */
+  readonly _tweenClock: number = CLOCK_GAME
+  /** @internal */
+  _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    switch (prop) {
+      case "x": return { domain: DOM_NODE2D, id, value: floatValue, commit: (v) => { this._x = v as number } }
+      case "y": return { domain: DOM_NODE2D, id, value: floatValue, commit: (v) => { this._y = v as number } }
+      case "position": return { domain: DOM_NODE2D, id, value: vec2Value, commit: (v) => { this._x = cx(v as Vec2Like); this._y = cy(v as Vec2Like) } }
+      case "rotation": return { domain: DOM_NODE2D, id, value: floatValue, commit: (v) => { this._rotation = v as number } }
+      case "scale": return { domain: DOM_NODE2D, id, value: vec2Value, commit: (v) => { const s = typeof v === "number" ? [v, v] : v as Vec2Like; this._sx = cx(s); this._sy = cy(s) } }
+      default: return null
+    }
+  }
+
   /** Draw layer (int). Higher layers render on top. */
   get layer(): number { return this._layer }
   set layer(v: number) { this._layer = v; _creator2d.setLayer(this.id, v) }

package/src/g2/Sprite.ts

@@ -5,8 +5,16 @@
 import { Color, type ColorInput } from "../core/color"
 import { Vec2, type Vec2Like } from "../math/vec"
 import { Canvas, isCanvas } from "../canvas/Canvas"
-import { Node2D } from "./Node2D"
+import { Node2D, type Node2DTweenProps } from "./Node2D"
 import type { Texture2D } from "./Texture2D"
+import { DOM_SPRITE2D, colorValue, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import type { Animation } from "../animate/tween/Animation"
+
+/** Animatable sprite props on top of the 2D transform. */
+export type SpriteTweenProps = Node2DTweenProps & {
+  opacity?: number | number[],
+  color?: ColorInput | ColorInput[],
+}
 
 /** Anything that can back a sprite: a texture, or a Canvas (baked to a texture on assign). */
 export type TextureSource = Texture2D | Canvas
@@ -76,6 +84,17 @@ export class Sprite extends Node2D {
     return this
   }
 
+  /** Tween `opacity` / `color` and the transform — see {@link Node2D.animateTo}. */
+  override animateTo(props: SpriteTweenProps & TweenMeta): Animation { return super.animateTo(props) }
+  override animateFrom(props: SpriteTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
+  /** @internal */
+  override _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    if (prop === "opacity") return { domain: DOM_SPRITE2D, id, value: floatValue, commit: (v) => { this._opacity = v as number } }
+    if (prop === "color") return { domain: DOM_SPRITE2D, id, value: (v) => colorValue(v, Color.toRgba01), commit: (v) => { this._color = v as ColorInput } }
+    return super._tweenChannel(prop)
+  }
+
   get color(): ColorInput { return this._color }
   set color(c: ColorInput) { this._color = c; const [ r, g, b ] = Color.toRgb01(c); _creator2d.setSpriteColor(this.id, r, g, b) }
 

package/src/gl/Camera.ts

@@ -3,8 +3,17 @@
 
 import { Vec3 } from "../math/vec"
 import { Aspect } from "../core/Aspect"
-import { Node } from "./Node"
+import { Node, type NodeTweenProps } from "./Node"
 import { Ray } from "./Ray"
+import { DOM_GL_CAMERA, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import type { Animation } from "../animate/tween/Animation"
+
+/** Animatable camera props on top of the node transform. */
+export type CameraTweenProps = NodeTweenProps & {
+  fov?: number | number[],
+  near?: number | number[],
+  far?: number | number[],
+}
 
 /** @internal `camera.follow(node)`: copies the node's world pose onto the camera every LATE frame
  *  (order 1000 — after every other aspect has moved things). One per camera; lives on the target. */
@@ -24,6 +33,24 @@ export const CAMERA_DEFAULTS = { fov: 60, near: 0.01, far: 1000 }
 
 export class Camera extends Node {
   private _sceneId = -1
+
+  /** Tween `fov` / `near` / `far` (a zoom, a dolly) and the transform — see {@link Node.animateTo}. */
+  override animateTo(props: CameraTweenProps & TweenMeta): Animation { return super.animateTo(props) }
+  override animateFrom(props: CameraTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
+  /** @internal The projection channels address the SCENE (one camera per scene on the host). */
+  override _tweenChannel(prop: string): TweenChannel | null {
+    if (prop === "fov" || prop === "near" || prop === "far") {
+      const id = () => (this._sceneId < 0 ? 0 : this._sceneId + 1)   // scene ids start at 0; 0 = unaddressable
+      const commit = (v: unknown) => {
+        if (prop === "fov") this._fov = v as number
+        else if (prop === "near") this._near = v as number
+        else this._far = v as number
+        this._projSet = true
+      }
+      return { domain: DOM_GL_CAMERA, id, value: floatValue, commit }
+    }
+    return super._tweenChannel(prop)
+  }
   /** Live projection matrix (updated by the host when the viewport/fov changes). */
   readonly projectionMatrix = new Float32Array(16)
 
@@ -57,6 +84,12 @@ export class Camera extends Node {
    *  adaptation when the sun swings into view (drop it, and the sun stays at the display's peak
    *  while everything else darkens). Scene light follows it; particle `emissive` is post-exposure
    *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. */
+  /** The camera's EV100 with the compensation in: log2(aperture² / shutterSpeed x 100 / iso) - compensation. Sunny 16 is
+   *  ~15; a lit surface of luminance L lands on screen at L / (1.2 x 2^ev100). */
+  get ev100(): number {
+    const e = this._exposure
+    return Math.log2((e.aperture * e.aperture) / e.shutterSpeed * 100 / e.iso) - this._ev
+  }
   get exposureCompensation(): number { return this._ev }
   set exposureCompensation(stops: number) {
     this._ev = Number.isFinite(stops) ? stops : 0

package/src/gl/Foliage.ts

@@ -0,0 +1,102 @@
+// Foliage — the vegetation tier of the lightmap material family (creator-gl materials/src/foliage.mat).
+//
+// A model loaded with `Model.load(src, { foliage: true })` (scene files: `foliage: true` on a `model`
+// node) takes a shader whose vertices sway in the wind, bend away from BENDERS (the hero, enemies —
+// any node registered with `Foliage.bend`) and thin out over a distance range, and whose fragment
+// tints every copy a little differently. All of it is level-wide state the engine keeps: the wind
+// and the sway options apply to every foliage model, present and future; benders are read from
+// their live world transforms each frame (the 8 nearest the camera reach the shader); a fade is per
+// ASSET — every copy of that model, present and future.
+//
+// Hosts without the tier (no `foliageSet*` bridge) ignore every call; the models then load through
+// the ordinary lightmap tier where that exists, else the standard shader.
+import { Model } from "./Model"
+import { Node } from "./Node"
+
+export type FoliageWind = {
+  /** Direction on the ground (x, z); normalised by the engine. Default [1, 0.3]. */
+  direction?: [number, number]
+  /** Metres of sway at `bendHeight` (taller parts sway more). Default 0.07. 0 = still. */
+  strength?: number
+  /** Radians per second of the main sway. Default 1.2. */
+  speed?: number
+  /** 0..1: how much the strength breathes over a slow envelope. Default 0.6. */
+  gust?: number
+}
+
+export type FoliageOptions = {
+  /** The wind, or `false` for none. */
+  wind?: FoliageWind | false
+  /** Height above the instance origin (m) where the full sway / touch applies; the base never moves.
+   *  Default 1.5. */
+  bendHeight?: number
+  /** Metres the TOP of a small plant leans away from a bender standing at its centre; the whole plant leans
+   *  as one, rooted at its base. Plants over ~2 m react less, trees over ~5 m not at all (the engine
+   *  measures each asset). Default 0.6. 0 = no touch reaction. */
+  touch?: number
+  /** 0..1: how far each copy's tint drifts from the texture (warmer/darker to cooler/lighter, by a hash
+   *  of its position). Default 0.35. */
+  variation?: number
+  /** 0..1: wrapped sun lighting — thin leaves let light through. Default 0.5. */
+  sunWrap?: number
+}
+
+const state: Required<Omit<FoliageOptions, "wind">> & { wind: Required<FoliageWind> | false } = {
+  wind: { direction: [ 1, 0.3 ], strength: 0.07, speed: 1.2, gust: 0.6 },
+  bendHeight: 1.5,
+  touch: 0.6,
+  variation: 0.35,
+  sunWrap: 0.5,
+}
+
+const pushWind = (): void => {
+  const w = state.wind
+  if (w === false) _creator.foliageSetWind?.(1, 0, 0, 1, 0)
+  else _creator.foliageSetWind?.(w.direction[0], w.direction[1], w.strength, w.speed, w.gust)
+}
+
+export const Foliage = {
+  /** Level-wide options; each field given replaces the current value (a scene file's `env.foliage`
+   *  goes through here). */
+  configure(options: FoliageOptions): void {
+    if (options.wind !== undefined) Foliage.wind(options.wind)
+    let sway = false
+    if (options.bendHeight !== undefined) { state.bendHeight = options.bendHeight; sway = true }
+    if (options.touch !== undefined) { state.touch = options.touch; sway = true }
+    if (options.variation !== undefined) { state.variation = options.variation; sway = true }
+    if (options.sunWrap !== undefined) { state.sunWrap = options.sunWrap; sway = true }
+    if (sway) _creator.foliageSetOptions?.(state.bendHeight, state.touch, state.variation, state.sunWrap)
+  },
+
+  /** The wind: fields given replace the current ones; `false` = calm. Live. */
+  wind(wind: FoliageWind | false): void {
+    if (wind === false) state.wind = false
+    else {
+      const cur = state.wind === false ? { direction: [ 1, 0.3 ] as [number, number], strength: 0.07, speed: 1.2, gust: 0.6 } : state.wind
+      state.wind = { direction: wind.direction ?? cur.direction, strength: wind.strength ?? cur.strength, speed: wind.speed ?? cur.speed, gust: wind.gust ?? cur.gust }
+    }
+    pushWind()
+  },
+
+  /** A node whose live position pushes the vegetation within `radius` metres (the hero: ~0.7; a
+   *  boulder: its size). Any number may be registered; the 8 nearest the camera act each frame. The
+   *  engine also tracks the node's velocity (smoothed over ~0.2 s): a plant you run through is brushed
+   *  forward and settles behind you instead of flipping as you cross its centre.
+   *  Returns the unregister function; a destroyed node drops out on its own. */
+  bend(node: Node, radius = 0.7): () => void {
+    _creator.foliageSetBender?.(node.id, radius > 0 ? radius : 0.01)
+    return () => Foliage.unbend(node)
+  },
+
+  /** Stop a node from bending the vegetation. */
+  unbend(node: Node): void {
+    _creator.foliageSetBender?.(node.id, 0)
+  },
+
+  /** Distance fade for EVERY copy of this model's asset (present and future): the cards thin out
+   *  from `start` to `end` metres from the camera and past `end` the copy leaves the frame entirely.
+   *  Small ground cover (grass, clover, flowers) is the target; `end` 0 = no fade. */
+  fade(model: Model, start: number, end: number): void {
+    _creator.foliageSetFade?.(model.id, start, end)
+  },
+}