lecodes-sdk 2.3.0 → 2.4.0

package/package.json

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

package/src/animate/tween/Timeline.ts

@@ -1,175 +1,175 @@
-// `Timeline` (docs/timeline-plan.md §2.4): choreography over the keyframe core. Tracks on any
-// number of targets (UI elements, 3D / 2D nodes, lights, cameras) at absolute positions, JS calls
-// at times, labels, holds — one clock, one handle. Also the `animateTo` / `animateFrom` bag
-// builder every target class delegates to (`tweenBag`).
-
-import { TweenAnimation, type Animation } from "./Animation"
-import { makeValueTrack, type AnimateOptions, type AnimateValue } from "./animateValue"
-import { CLOCK_GAME, CLOCK_UI, bagProps, iterationsOf, makeTrack, type Track, type TweenMeta, type TweenSpec, type TweenTarget } from "./spec"
-
-/** Vector-valued props: an array value is ONE keyframe unless it is an array of vectors. */
-const VECTOR_PROPS = new Set(["position", "scale", "quaternion", "eulerAngles", "color"])
-
-const clockOf = (clock: TweenMeta["clock"], fallback: number): number =>
-  clock === "game" ? CLOCK_GAME : clock === "ui" ? CLOCK_UI : fallback
-
-/** @internal Build the tracks of one options bag on one target. `fromCurrent` = animateTo shape. */
-export const bagTracks = (target: TweenTarget, bag: Record<string, unknown>, atMs: number, fromCurrent: boolean): Track[] => {
-  const meta = bag as TweenMeta
-  const tracks: Track[] = []
-  for (const [prop, value] of bagProps(bag)) {
-    const track = makeTrack(target, prop, value, meta, atMs, fromCurrent, VECTOR_PROPS.has(prop))
-    if (track) tracks.push(track)
-  }
-  return tracks
-}
-
-/** @internal The `animateTo` / `animateFrom` implementation: one bag → one animation, played now. */
-export const tweenBag = (target: TweenTarget, bag: Record<string, unknown>, fromCurrent: boolean): Animation => {
-  const meta = bag as TweenMeta
-  const tracks = bagTracks(target, bag, 0, fromCurrent)
-  let durationMs = 0
-  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
-  const spec: TweenSpec = {
-    clock: clockOf(meta.clock, target._tweenClock),
-    durationMs, delayMs: 0,
-    iterations: iterationsOf(meta.loop),
-    pingPong: meta.loopMode !== "restart",
-    rate: 1, tracks, calls: [],
-  }
-  return new TweenAnimation(spec).play()
-}
-
-export type TimelineOptions = {
-  /** `'ui'` (default) = wall time; `'game'` follows `Time.scale` and pauses with the game. */
-  clock?: "ui" | "game",
-  /** Repeat the whole timeline: `true` = forever, a number = cycles. */
-  loop?: boolean | number,
-  loopMode?: "restart" | "ping-pong",
-  /** Wait before the first play, ms. */
-  delay?: number,
-}
-
-/** Where a track goes: ms, a label, or `[label, offsetMs]`. Default = the current end (sequencing). */
-export type TimelinePosition = number | string | [string, number]
-
-export type TimelineAddOptions = {
-  at?: TimelinePosition,
-  /** With several targets: each starts this many ms after the previous one. */
-  stagger?: number,
-}
-
-/** A choreography: tracks on many targets at absolute times, JS calls, labels and holds, driven by
- *  one clock. Build it once, `play()` on every entrance — `play()` restarts from t = 0 and the pose
- *  at any time is fully defined by the tracks (the first keyframe of a track holds before it
- *  starts, the last one after it ends). */
-export class TimelineImpl extends TweenAnimation {
-  private _labels = new Map<string, number>()
-  private _end = 0
-
-  constructor(options: TimelineOptions = {}) {
-    super({
-      clock: clockOf(options.clock, CLOCK_UI),
-      durationMs: 0,
-      delayMs: options.delay ?? 0,
-      iterations: iterationsOf(options.loop),
-      pingPong: options.loopMode !== "restart",
-      rate: 1, tracks: [], calls: [],
-    })
-  }
-
-  private _at(at: TimelinePosition | undefined): number {
-    if (at === undefined) return this._end
-    if (typeof at === "number") return at
-    const name = Array.isArray(at) ? at[0] : at
-    const offset = Array.isArray(at) ? at[1] : 0
-    const base = this._labels.get(name)
-    if (base === undefined) throw new Error(`Timeline: unknown label "${name}"`)
-    return base + offset
-  }
-
-  private _grow(endMs: number): void {
-    if (endMs > this._end) this._end = endMs
-    this._spec.durationMs = this._end
-  }
-
-  /** Animate `props` on one target or several (staggered), like `animateTo` — arrays are keyframes,
-   *  `duration` / `easing` / `times` / `commit` apply. The bag's `delay` shifts the track after `at`. */
-  add(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
-    const at = this._at(options.at)
-    const targets = Array.isArray(target) ? target : [target]
-    const stagger = options.stagger ?? 0
-    targets.forEach((t, i) => {
-      const tracks = bagTracks(t, props, at + i * stagger, true)
-      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
-    })
-    return this
-  }
-
-  /** Like `add` with the `animateFrom` shape: the target's own state is the implicit last keyframe. */
-  addFrom(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
-    const at = this._at(options.at)
-    const targets = Array.isArray(target) ? target : [target]
-    const stagger = options.stagger ?? 0
-    targets.forEach((t, i) => {
-      const tracks = bagTracks(t, props, at + i * stagger, false)
-      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
-    })
-    return this
-  }
-
-  /** A free-value track (see the `animate()` global): the host evaluates it and calls `onUpdate`
-   *  every frame with the value. */
-  animate<T extends AnimateValue>(options: AnimateOptions<T>, at?: TimelinePosition): this {
-    const { track, deliver, slot } = makeValueTrack(options, this._at(at))
-    this._values.set(slot, deliver)
-    this._spec.tracks.push(track)
-    this._grow(track.atMs + track.durMs)
-    return this
-  }
-
-  /** Call `fn` when playback crosses `at` (forward or backward), in time order, always before
-   *  finish, never from a previous run. */
-  call(at: TimelinePosition, fn: () => void): this {
-    const t = this._at(at)
-    this._spec.calls.push(t)
-    this._calls.push(fn)
-    this._grow(t)
-    return this
-  }
-
-  /** Name a time — for `at`, `seek` and callers (`tl.labels.landed`). Default = the current end. */
-  label(name: string, at?: TimelinePosition): this {
-    this._labels.set(name, this._at(at))
-    return this
-  }
-
-  /** Named times, ms. */
-  get labels(): Record<string, number> {
-    const o: Record<string, number> = {}
-    for (const [k, v] of this._labels) o[k] = v
-    return o
-  }
-
-  /** Extend the timeline with stillness after its current end. */
-  hold(ms: number): this {
-    this._grow(this._end + Math.max(0, ms))
-    return this
-  }
-
-  /** The current end, ms (tracks, calls and holds). */
-  get end(): number { return this._end }
-
-  /** `seek` also accepts a label. */
-  override seek(at: number | string): this {
-    return super.seek(typeof at === "string" ? this._at(at) : at)
-  }
-}
-
-/** The timeline handle type (see {@link TimelineImpl} for the members). */
-export type Timeline = TimelineImpl
-
-/** Create a timeline — `Timeline()` / `Timeline({ clock: 'game', loop: true })`. */
-export function Timeline(options?: TimelineOptions): Timeline {
-  return new TimelineImpl(options)
-}
+// `Timeline` (docs/timeline-plan.md §2.4): choreography over the keyframe core. Tracks on any
+// number of targets (UI elements, 3D / 2D nodes, lights, cameras) at absolute positions, JS calls
+// at times, labels, holds — one clock, one handle. Also the `animateTo` / `animateFrom` bag
+// builder every target class delegates to (`tweenBag`).
+
+import { TweenAnimation, type Animation } from "./Animation"
+import { makeValueTrack, type AnimateOptions, type AnimateValue } from "./animateValue"
+import { CLOCK_GAME, CLOCK_UI, bagProps, iterationsOf, makeTrack, type Track, type TweenMeta, type TweenSpec, type TweenTarget } from "./spec"
+
+/** Vector-valued props: an array value is ONE keyframe unless it is an array of vectors. */
+const VECTOR_PROPS = new Set(["position", "scale", "quaternion", "eulerAngles", "color"])
+
+const clockOf = (clock: TweenMeta["clock"], fallback: number): number =>
+  clock === "game" ? CLOCK_GAME : clock === "ui" ? CLOCK_UI : fallback
+
+/** @internal Build the tracks of one options bag on one target. `fromCurrent` = animateTo shape. */
+export const bagTracks = (target: TweenTarget, bag: Record<string, unknown>, atMs: number, fromCurrent: boolean): Track[] => {
+  const meta = bag as TweenMeta
+  const tracks: Track[] = []
+  for (const [prop, value] of bagProps(bag)) {
+    const track = makeTrack(target, prop, value, meta, atMs, fromCurrent, VECTOR_PROPS.has(prop))
+    if (track) tracks.push(track)
+  }
+  return tracks
+}
+
+/** @internal The `animateTo` / `animateFrom` implementation: one bag → one animation, played now. */
+export const tweenBag = (target: TweenTarget, bag: Record<string, unknown>, fromCurrent: boolean): Animation => {
+  const meta = bag as TweenMeta
+  const tracks = bagTracks(target, bag, 0, fromCurrent)
+  let durationMs = 0
+  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
+  const spec: TweenSpec = {
+    clock: clockOf(meta.clock, target._tweenClock),
+    durationMs, delayMs: 0,
+    iterations: iterationsOf(meta.loop),
+    pingPong: meta.loopMode !== "restart",
+    rate: 1, tracks, calls: [],
+  }
+  return new TweenAnimation(spec).play()
+}
+
+export type TimelineOptions = {
+  /** `'ui'` (default) = wall time; `'game'` follows `Time.scale` and pauses with the game. */
+  clock?: "ui" | "game",
+  /** Repeat the whole timeline: `true` = forever, a number = cycles. */
+  loop?: boolean | number,
+  loopMode?: "restart" | "ping-pong",
+  /** Wait before the first play, ms. */
+  delay?: number,
+}
+
+/** Where a track goes: ms, a label, or `[label, offsetMs]`. Default = the current end (sequencing). */
+export type TimelinePosition = number | string | [string, number]
+
+export type TimelineAddOptions = {
+  at?: TimelinePosition,
+  /** With several targets: each starts this many ms after the previous one. */
+  stagger?: number,
+}
+
+/** A choreography: tracks on many targets at absolute times, JS calls, labels and holds, driven by
+ *  one clock. Build it once, `play()` on every entrance — `play()` restarts from t = 0 and the pose
+ *  at any time is fully defined by the tracks (the first keyframe of a track holds before it
+ *  starts, the last one after it ends). */
+export class TimelineImpl extends TweenAnimation {
+  private _labels = new Map<string, number>()
+  private _end = 0
+
+  constructor(options: TimelineOptions = {}) {
+    super({
+      clock: clockOf(options.clock, CLOCK_UI),
+      durationMs: 0,
+      delayMs: options.delay ?? 0,
+      iterations: iterationsOf(options.loop),
+      pingPong: options.loopMode !== "restart",
+      rate: 1, tracks: [], calls: [],
+    })
+  }
+
+  private _at(at: TimelinePosition | undefined): number {
+    if (at === undefined) return this._end
+    if (typeof at === "number") return at
+    const name = Array.isArray(at) ? at[0] : at
+    const offset = Array.isArray(at) ? at[1] : 0
+    const base = this._labels.get(name)
+    if (base === undefined) throw new Error(`Timeline: unknown label "${name}"`)
+    return base + offset
+  }
+
+  private _grow(endMs: number): void {
+    if (endMs > this._end) this._end = endMs
+    this._spec.durationMs = this._end
+  }
+
+  /** Animate `props` on one target or several (staggered), like `animateTo` — arrays are keyframes,
+   *  `duration` / `easing` / `times` / `commit` apply. The bag's `delay` shifts the track after `at`. */
+  add(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
+    const at = this._at(options.at)
+    const targets = Array.isArray(target) ? target : [target]
+    const stagger = options.stagger ?? 0
+    targets.forEach((t, i) => {
+      const tracks = bagTracks(t, props, at + i * stagger, true)
+      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
+    })
+    return this
+  }
+
+  /** Like `add` with the `animateFrom` shape: the target's own state is the implicit last keyframe. */
+  addFrom(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
+    const at = this._at(options.at)
+    const targets = Array.isArray(target) ? target : [target]
+    const stagger = options.stagger ?? 0
+    targets.forEach((t, i) => {
+      const tracks = bagTracks(t, props, at + i * stagger, false)
+      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
+    })
+    return this
+  }
+
+  /** A free-value track (see the `animate()` global): the host evaluates it and calls `onUpdate`
+   *  every frame with the value. */
+  animate<T extends AnimateValue>(options: AnimateOptions<T>, at?: TimelinePosition): this {
+    const { track, deliver, slot } = makeValueTrack(options, this._at(at))
+    this._values.set(slot, deliver)
+    this._spec.tracks.push(track)
+    this._grow(track.atMs + track.durMs)
+    return this
+  }
+
+  /** Call `fn` when playback crosses `at` (forward or backward), in time order, always before
+   *  finish, never from a previous run. */
+  call(at: TimelinePosition, fn: () => void): this {
+    const t = this._at(at)
+    this._spec.calls.push(t)
+    this._calls.push(fn)
+    this._grow(t)
+    return this
+  }
+
+  /** Name a time — for `at`, `seek` and callers (`tl.labels.landed`). Default = the current end. */
+  label(name: string, at?: TimelinePosition): this {
+    this._labels.set(name, this._at(at))
+    return this
+  }
+
+  /** Named times, ms. */
+  get labels(): Record<string, number> {
+    const o: Record<string, number> = {}
+    for (const [k, v] of this._labels) o[k] = v
+    return o
+  }
+
+  /** Extend the timeline with stillness after its current end. */
+  hold(ms: number): this {
+    this._grow(this._end + Math.max(0, ms))
+    return this
+  }
+
+  /** The current end, ms (tracks, calls and holds). */
+  get end(): number { return this._end }
+
+  /** `seek` also accepts a label. */
+  override seek(at: number | string): this {
+    return super.seek(typeof at === "string" ? this._at(at) : at)
+  }
+}
+
+/** The timeline handle type (see {@link TimelineImpl} for the members). */
+export type Timeline = TimelineImpl
+
+/** Create a timeline — `Timeline()` / `Timeline({ clock: 'game', loop: true })`. */
+export function Timeline(options?: TimelineOptions): Timeline {
+  return new TimelineImpl(options)
+}

package/src/audio/support.ts

@@ -1,6 +1,8 @@
 // Feature gate for the game audio system (docs/audio-plan.md). `_creatorAudio` is OPTIONAL as a
 // block: a host without it (or whose engine failed to open a device) makes every Sound silent and
-// every Voice inert — a project stays runnable, nothing throws.
+// every Voice inert — a project stays runnable, nothing throws. hasSupport() opens no device: the
+// native engine is created by the first call that needs it (a load, a bus write), so reading this
+// at load costs nothing; a host whose device then fails to open hands Sound.load the silent clip.
 
 export const audioSupported: boolean =
   typeof _creatorAudio !== "undefined" && !!_creatorAudio && typeof _creatorAudio.hasSupport === "function" && _creatorAudio.hasSupport()

package/src/bridges/audio.d.ts

@@ -13,27 +13,32 @@ declare global {
   // CREATOR_PKG_AUDIO (desktop first; Android / Apple pending — parity `audio-game`). The headless
   // renderer provides a RECORDER (plays are logged, nothing is mixed). Every parameter block is a
   // fixed-order Float32Array (creator-audio.h CAUD_SRC_* / the effect param orders).
+  // The engine (and the audio DEVICE) is created LAZILY, by the first call that needs it — the
+  // `@guard audioEnsureEngine` on every method that touches engine state (creator-pkg.h
+  // "creator-audio host integration"): an app that never makes a sound never opens the device.
+  // hasSupport() therefore opens nothing: it is "the bridge is here and no init has failed".
   /** @engine audio */
   var _creatorAudio: {
-    /** @guard audioEnsureEngine @c caudHasSupport */
+    /** True on a host with the bridge until an engine init has FAILED (no device at all). Opens
+     *  nothing: the engine is created by the first call that needs it. @custom */
     hasSupport(): boolean
     /** Decode the bytes behind a fetch system id (WAV / MP3 / OGG Vorbis) on the engine's
      *  loader thread; mono unless `stereo`. onDone(clipId, durationSeconds, channels). @custom */
     loadClip(systemId: bytes, stereo: boolean, onDone: (clipId: number, duration: number, channels: number) => void, onReject: (message: string) => void): void
     /** @c caudClipRelease */
     releaseClip(clipId: u32): void
-    /** Bus id by name (-1 unknown); 0 master, 1 sfx, 2 music, 3 ui, 4 voice. @c caudBusId */
+    /** Bus id by name (-1 unknown); 0 master, 1 sfx, 2 music, 3 ui, 4 voice. @guard audioEnsureEngine @c caudBusId */
     busId(name: string): i32
-    /** Creates (or finds) an app-defined bus under master. -1 when the 16 slots are full. @c caudBusCreate */
+    /** Creates (or finds) an app-defined bus under master. -1 when the 16 slots are full. @guard audioEnsureEngine @c caudBusCreate */
     createBus(name: string): i32
-    /** @c caudBusSetVolume */
+    /** @guard audioEnsureEngine @c caudBusSetVolume */
     setBusVolume(bus: i32, volume: f32): void
-    /** @c caudBusSetMuted */
+    /** @guard audioEnsureEngine @c caudBusSetMuted */
     setBusMuted(bus: i32, muted: boolean): void
     /** kind 1 reverb [roomSize, damping, width, mix, preDelay] · 2 echo [delay, decay, mix] ·
-     *  3 lowpass [cutoffHz]; an empty array turns the effect off. Changes are smoothed. @c caudBusSetEffect */
+     *  3 lowpass [cutoffHz]; an empty array turns the effect off. Changes are smoothed. @guard audioEnsureEngine @c caudBusSetEffect */
     setBusEffect(bus: i32, kind: i32, params: Float32Array): void
-    /** @c caudBusStopAll */
+    /** @guard audioEnsureEngine @c caudBusStopAll */
     stopBus(bus: i32, fade: f32): void
     /** A 3D emitter. `attachSource` binds it to an entity the engine follows every frame;
      *  `setSourcePosition` places an unbound one (playAt). @guard audioEnsureEngine @c caudSourceCreate */
@@ -41,11 +46,11 @@ declare global {
     /** @c gl:audioAttachSource */
     attachSource(sourceId: u32, entityId: u32): void
     /** [minDistance, maxDistance, rolloff (0 none 1 inverse 2 linear 3 exp), coneInnerDeg,
-     *  coneOuterDeg, coneOuterGain, doppler, spread, occlusion (0/1), bus]. @c caudSourceSetParams */
+     *  coneOuterDeg, coneOuterGain, doppler, spread, occlusion (0/1), bus]. @guard audioEnsureEngine @c caudSourceSetParams */
     setSourceParams(sourceId: u32, params: Float32Array): void
-    /** @c caudSourceSetPose @pack x 3 @rest nullptr */
+    /** @guard audioEnsureEngine @c caudSourceSetPose @pack x 3 @rest nullptr */
     setSourcePosition(sourceId: u32, x: f32, y: f32, z: f32): void
-    /** @c caudSourceStopAll */
+    /** @guard audioEnsureEngine @c caudSourceStopAll */
     stopSource(sourceId: u32, fade: f32): void
     /** @c caudSourceVoices */
     sourceVoices(sourceId: u32): i32
@@ -53,22 +58,22 @@ declare global {
     destroySource(sourceId: u32): void
     /** The listener entity; 0 = the active scene camera (the default). @c gl:audioSetListener */
     setListener(entityId: u32): void
-    /** @c caudListenerSetDoppler */
+    /** @guard audioEnsureEngine @c caudListenerSetDoppler */
     setListenerOptions(dopplerFactor: f32): void
     /** HRTF binaural rendering for the `maxVoices` nearest spatial voices (headphones); the rest keep panning. @guard audioEnsureEngine @c caudSetHrtf */
     setHrtf(enabled: boolean, maxVoices: i32): void
     /** Whether the engine's time scale (Time.scale) also pitches the sfx bus. Default false (pause = mute only). @guard audioEnsureEngine @c caudSetTimeScalePitch */
     setTimeScalePitch(enabled: boolean): void
     /** → a voice token (0 = nothing played: the pool refused, the clip is not ready). bus -1 = the
-     *  source's bus (sfx for 2D). pan is 2D only. @c caudPlay @pack bus CaudPlay */
+     *  source's bus (sfx for 2D). pan is 2D only. @guard audioEnsureEngine @c caudPlay @pack bus CaudPlay */
     play(clipId: u32, sourceId: u32, bus: i32, volume: f32, pitch: f32, loop: boolean, priority: i32, fadeIn: f32, startAt: f32, pan: f32): u32
-    /** @c caudVoiceSetVolume */
+    /** @guard audioEnsureEngine @c caudVoiceSetVolume */
     setVoiceVolume(token: u32, volume: f32): void
-    /** @c caudVoiceSetPitch */
+    /** @guard audioEnsureEngine @c caudVoiceSetPitch */
     setVoicePitch(token: u32, pitch: f32): void
-    /** @c caudVoiceSetPan */
+    /** @guard audioEnsureEngine @c caudVoiceSetPan */
     setVoicePan(token: u32, pan: f32): void
-    /** @c caudVoiceStop */
+    /** @guard audioEnsureEngine @c caudVoiceStop */
     stopVoice(token: u32, fade: f32): void
     /** @c caudVoicePlaying */
     voicePlaying(token: u32): boolean
@@ -77,7 +82,7 @@ declare global {
     /** THE ended listener (single slot per JS world): called once per tick with the tokens of the
      *  voices that ended since the previous tick — natural end, stop, steal. @custom */
     setOnEnded(callback: ((tokens: Float32Array) => void) | null): void
-    /** @c caudStopAll */
+    /** @guard audioEnsureEngine @c caudStopAll */
     stopAll(fade: f32): void
     /** A reverb volume: shape 0 box (dims = full size) / 1 sphere (dims[0] = diameter), in the
      *  entity's local units; `blend` metres of crossfade inside the border; reverb params as for
@@ -85,7 +90,7 @@ declare global {
     createZone(): u32
     /** @c gl:audioAttachZone */
     attachZone(zoneId: u32, entityId: u32): void
-    /** @c caudZoneSet */
+    /** @guard audioEnsureEngine @c caudZoneSet */
     setZone(zoneId: u32, shape: i32, dims: Float32Array, blend: f32, bus: i32, reverb: Float32Array): void
     /** @c gl:audioDetachZone, caudZoneDestroy */
     destroyZone(zoneId: u32): void

package/src/bridges/device.d.ts

@@ -38,6 +38,25 @@ declare global {
     /** Whether the overlay is on. */
     statsOverlay?(): boolean
 
+    // ---- The frame rate (device.setFrameRate / setVsync / displayRefreshRate) ---------------------
+    /** Cap the host's frame loop at `fps` frames a second (device.setFrameRate): the tick, and the
+     *  3D frame with it, runs at most that often. `0` = no cap: the display's own rate, or, with
+     *  vsync off, as fast as the host renders. A request, not a state — a phone asks its panel for
+     *  the rate and may be refused; the screen's own maximum still wins. Host state, kept through
+     *  `_creatorApp.run()`. Optional: a host whose loop has no pacing of its own (web, headless)
+     *  leaves it out. */
+    setFrameRate?(fps: f64): void
+    /** Present without waiting for the display's refresh (device.setVsync): off = no vsync wait,
+     *  tearing possible, and with no cap set the loop renders as fast as it can. Optional: desktop
+     *  only — a mobile compositor never presents outside the refresh, so the slot is absent there
+     *  and the SDK answers `false`. */
+    setVsync?(enabled: boolean): void
+    /** The display's refresh rate in Hz (device.displayRefreshRate): the fastest the screen offers
+     *  the app — 120 on a 120 Hz phone whatever mode the cap has put it in (an iPhone's 60 unless
+     *  the app's Info.plist lifts the floor), the monitor's current mode on desktop. Optional: 0
+     *  where the host cannot tell (web, Linux for now). */
+    displayRefreshRate?(): f64
+
     // ---- device.motion (orientation sensor; pull-per-frame model) --------------------------------
     /** Does this device have the motion sensors (gyro)? Surfaced as device.motion.available. */
     motionAvailable?(): boolean

package/src/bridges/gl.d.ts

@@ -286,6 +286,11 @@ declare global {
     setInstanceTransforms(entityId: u32, matrices: Float32Array, first: u32): void
     setInstancedMeshMaterial(entityId: u32, materialId: u32): void
     setInstancedMeshShadows(entityId: u32, cast: boolean, receive: boolean): void
+    /** GLB scatter (gl/Scatter.ts ↔ creator-gl/src/scatter.cpp): the loaded model `sourceId` drawn at `placements.length / 5`
+     *  placements (x y z, yaw in degrees, uniform scale) under `entityId`, hardware-instanced in cells of `cell` metres
+     *  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
     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. */
@@ -780,6 +785,12 @@ declare global {
     /** Distance fade for every instance of the entity's ASSET (present and future): the cards thin out between `start`
      *  and `end` metres from the camera and past `end` the LOD pass takes the instance out of the scene. end 0 = none. */
     foliageSetFade?(entityId: u32, start: f32, end: f32): void
+    /** THE PLANTS' CASTER DISTANCE: a foliage instance casts the sun's shadow only within `distance` metres of the camera
+     *  (the LOD pass flips its renderables' castShadows); past it a baked ground keeps the shadow. 0 = every plant casts. */
+    foliageSetCast?(distance: f32): void
+    /** THE GROUND'S COLOUR UNDER THE PLANTS: the terrain's control map (RGBA = its four layers' weights) and each layer's
+     *  mean colour (12 floats, linear rgb x 4) — a grass blade's base takes the colour of the soil it stands in. Level-wide. */
+    foliageSetGroundTint?(terrainId: u32, controlTextureId: u32, colors: Float32Array): void
     /** @ifdef CREATOR_GL_PHYSICS */
     physicsConfigure(gx: f32, gy: f32, gz: f32, maxBodies: u32): void
     /** @c setPhysicsInterpolation @ifdef CREATOR_GL_PHYSICS */

package/src/compile/serverSplit.ts

@@ -13,6 +13,7 @@
  */
 
 import type { AppConfig } from "../server/auth/appConfig"
+import { CODE_EXT } from "./assetMacro"
 import { bundleProjectWithMap, SERVER_INJECT, type MemoryFiles } from "./bundler"
 import type { CompileEntry } from "./compileProject"
 import { deriveEndpointParams } from "./serverTypes"
@@ -271,12 +272,18 @@ export const compileServerBundle = async (opts: CompileServerOptions): Promise<{
   // with a Figma-exported design next to app.server.ts). A stub's value is the resource's PATH: a
   // row of shared data that names a picture (`photo: "images/a.jpg"`) reaches the server as the
   // path of that picture, which a seed stores into a file field (files/db.ts). The board's `design/`
-  // files are never server code and stay out entirely.
+  // files are never server code and stay out entirely. A text file that is not code follows the
+  // app bundle's rules (compileProject.ts entriesToFiles): a `.json` is its parsed data — a shared
+  // module of a price list the person gave does `import raw from "./price.json"`, and the seed
+  // that imports the module ran into "raw is not defined" while the text went in as code — and any
+  // other text (.csv, .txt, .md) is its string.
   const files: MemoryFiles = {}
   for (const e of opts.entries) {
     const path = normalizePath(e.path)
     if (/^\/design\//.test(path)) continue
     if (e.type !== "text" || path.toLowerCase().endsWith(".svg")) { files[path] = `export default ${JSON.stringify(path)}`; continue }
+    if (path.toLowerCase().endsWith(".json")) { files[path] = `export default ${e.text?.trim() || "null"}`; continue }
+    if (!CODE_EXT.test(path)) { files[path] = `export default ${JSON.stringify(e.text ?? "")}`; continue }
     files[path] = e.text ?? ""
   }
   let params = opts.params