@nayan-ui/engine 1.0.0-beta.3 → 1.0.0-beta.5

package/lib/module/world/color.js

@@ -0,0 +1,80 @@
+"use strict";
+
+// Colors: every engine option that takes a color accepts either a linear 0..1 tuple or a CSS color
+// string, so theme colors go straight in: `world.spawn({ color: '#FF4757' })`.
+
+/** A color as an option takes it: `[r, g, b]` / `[r, g, b, a]` (0..1, channels above 1 glow) or a CSS string. */
+
+const HEX = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+%?)\s*)?\)$/i;
+const NAMED = {
+  transparent: [0, 0, 0, 0],
+  black: [0, 0, 0, 1],
+  white: [1, 1, 1, 1],
+  red: [1, 0, 0, 1],
+  green: [0, 128 / 255, 0, 1],
+  blue: [0, 0, 1, 1],
+  yellow: [1, 1, 0, 1],
+  orange: [1, 165 / 255, 0, 1],
+  purple: [128 / 255, 0, 128 / 255, 1],
+  gray: [128 / 255, 128 / 255, 128 / 255, 1],
+  grey: [128 / 255, 128 / 255, 128 / 255, 1]
+};
+
+// Theme colors repeat endlessly; parse each string once.
+const parsed = new Map();
+const PARSED_LIMIT = 1024;
+function parse(css) {
+  const text = css.trim();
+  const named = NAMED[text.toLowerCase()];
+  if (named) return named;
+  const hex = HEX.exec(text);
+  if (hex) {
+    let digits = hex[1];
+    if (digits.length <= 4) digits = [...digits].map(d => d + d).join('');
+    const n = i => parseInt(digits.slice(i, i + 2), 16) / 255;
+    return [n(0), n(2), n(4), digits.length === 8 ? n(6) : 1];
+  }
+  const rgb = RGB.exec(text);
+  if (rgb) {
+    const alpha = rgb[4] === undefined ? 1 : rgb[4].endsWith('%') ? parseFloat(rgb[4]) / 100 : Number(rgb[4]);
+    return [Number(rgb[1]) / 255, Number(rgb[2]) / 255, Number(rgb[3]) / 255, alpha];
+  }
+  throw new Error(`@nayan-ui/engine: "${css}" is not a color (use '#RRGGBB', '#RGB', '#RRGGBBAA', 'rgb(…)', 'rgba(…)' or a 0..1 tuple)`);
+}
+
+/**
+ * Any color input as an `[r, g, b, a]` tuple (0..1), with its alpha multiplied by `alpha`. Use it when
+ * you need the numbers (to brighten, mix or fade a theme color); options take strings directly.
+ *
+ * ```ts
+ * toColor('#FF4757'); // [1, 0.278, 0.341, 1]
+ * toColor('#FF4757', 0.5); // half see-through
+ * ```
+ */
+export function toColor(color, alpha = 1) {
+  let c;
+  if (typeof color === 'string') {
+    let hit = parsed.get(color);
+    if (!hit) {
+      hit = parse(color);
+      if (parsed.size >= PARSED_LIMIT) parsed.clear();
+      parsed.set(color, hit);
+    }
+    c = hit;
+  } else c = color;
+  return [c[0], c[1], c[2], (c[3] ?? 1) * alpha];
+}
+
+/** A color input as a tuple, without copying tuples (the hot path of `spawn`, `set` and `animate`). */
+export function resolveColor(color) {
+  return typeof color === 'string' ? toColor(color) : color;
+}
+
+/** One color input, or a list to pick from, as tuples. */
+export function resolveColors(colors) {
+  if (typeof colors === 'string') return [toColor(colors)];
+  if (typeof colors[0] === 'number') return [colors];
+  return colors.map(resolveColor);
+}
+//# sourceMappingURL=color.js.map

package/lib/module/world/desc.js

@@ -3,7 +3,7 @@
 // Encodes entity options into the flat layout the Rust core decodes (native/core/include/engine_core.h,
 // native/core/src/world/desc.rs). One reusable Float64Array per world: spawning or changing an entity is
 // a single native call, and doubles keep entity ids and layer bits exact.
-
+import { resolveColor } from "./color.js";
 export const DESC_LEN = 64;
 const FLAG = {
   MESH: 1 << 0,
@@ -102,10 +102,11 @@ export function encode(d, o, mesh) {
   }
   if (o.color) {
     flags |= FLAG.COLOR;
-    d[SLOT.COLOR] = o.color[0];
-    d[SLOT.COLOR + 1] = o.color[1];
-    d[SLOT.COLOR + 2] = o.color[2];
-    d[SLOT.COLOR + 3] = o.color[3] ?? 1;
+    const c = resolveColor(o.color);
+    d[SLOT.COLOR] = c[0];
+    d[SLOT.COLOR + 1] = c[1];
+    d[SLOT.COLOR + 2] = c[2];
+    d[SLOT.COLOR + 3] = c[3] ?? 1;
   }
   if (o.velocity) {
     flags |= FLAG.VELOCITY;

package/lib/module/world/effects.js

@@ -9,6 +9,8 @@
 // Every particle takes a world slot, out of the capacity shared with the game's own entities, so the
 // counts stay close to what was passed in. Effects run entirely in the Rust core after one call each.
 
+import { resolveColor, resolveColors } from "./color.js";
+
 /** Shared options of the layered effects (confetti, sparkle, shatter, splash, sparks, explosion). */
 
 /** A soft cloud of puffs that swell and fade: landing dust, kicked-up sand, sawdust, steam, muzzle smoke. */
@@ -17,10 +19,16 @@
 
 /** The cleared-piece pop: swell, flash white, settle, shrink away. */
 
-const rgba = c => [c[0], c[1], c[2], c[3] ?? 1];
-const list = colors => typeof colors[0] === 'number' ? [rgba(colors)] : colors.map(rgba);
+const rgba = input => {
+  const c = resolveColor(input);
+  return [c[0], c[1], c[2], c[3] ?? 1];
+};
+const list = colors => resolveColors(colors).map(rgba);
 const part = (count, share) => Math.max(1, Math.round(count * share));
-const fade = c => [c[0], c[1], c[2], 0];
+const fade = input => {
+  const c = resolveColor(input);
+  return [c[0], c[1], c[2], 0];
+};
 
 /** The colors' average. */
 function mean(colors) {
@@ -30,13 +38,17 @@ function mean(colors) {
 }
 
 /** The same hue, self-lit: its brightest channel lifted to `peak` (above 1 glows, through light, shadow and fog). */
-function hot(c, peak = 2.2, alpha = c[3] ?? 1) {
+function hot(input, peak = 2.2, alpha) {
+  const c = resolveColor(input);
+  alpha ??= c[3] ?? 1;
   const k = peak / Math.max(c[0], c[1], c[2], 0.25);
   return [c[0] * k, c[1] * k, c[2] * k, alpha];
 }
 
 /** Part way (`t`, 0..1) to white, with `alpha`. */
-function pale(c, t, alpha = c[3] ?? 1) {
+function pale(input, t, alpha) {
+  const c = resolveColor(input);
+  alpha ??= c[3] ?? 1;
   return [c[0] + (1 - c[0]) * t, c[1] + (1 - c[1]) * t, c[2] + (1 - c[2]) * t, alpha];
 }
 function aim(e) {
@@ -70,7 +82,7 @@ function glowFlash(world, e, colors, size) {
   });
 }
 function dust(world, o) {
-  const single = typeof o.color[0] === 'number';
+  const colors = resolveColors(o.color);
   return world.burst({
     position: o.position,
     count: o.count,
@@ -81,9 +93,9 @@ function dust(world, o) {
     gravity: o.gravity ?? 0,
     direction: o.direction,
     spread: o.spread,
-    color: o.color,
+    color: colors.length === 1 ? colors[0] : colors,
     endSize: o.endSize ?? 2,
-    endColor: o.endColor ?? (single ? fade(o.color) : undefined)
+    endColor: o.endColor ?? (colors.length === 1 ? fade(colors[0]) : undefined)
   });
 }
 

package/lib/typescript/src/assets/AssetLoader.d.ts

@@ -5,7 +5,7 @@ export declare class AssetLoader<T> {
     private readonly name;
     private readonly loads;
     constructor(name: string);
-    load(source: AssetSource, decode: (native: EngineBridge, bytes: ArrayBuffer) => T, variant?: readonly (string | number | boolean)[]): Promise<T>;
+    load(source: AssetSource, decode: (native: EngineBridge, bytes: ArrayBuffer) => T | Promise<T>, variant?: readonly (string | number | boolean)[]): Promise<T>;
     private error;
 }
 //# sourceMappingURL=AssetLoader.d.ts.map

package/lib/typescript/src/assets/ProceduralCache.d.ts

@@ -2,6 +2,12 @@
 export interface ProceduralStorage {
     read(key: string): Uint8Array | null;
     write(key: string, bytes: Uint8Array): void | Promise<void>;
+    /**
+     * The store itself verifies every record's integrity (the engine's own Rust store checksums each
+     * one with SHA-256), so the cache needn't checksum and scan them again in JS. Geometry is still
+     * validated by the core when it's registered.
+     */
+    readonly verified?: boolean;
 }
 /**
  * Persists the output of a deterministic model factory, including nested model arrays/objects.
@@ -26,6 +32,12 @@ export declare class ProceduralCache {
         pendingWrites: number;
     };
     flush(): Promise<void>;
+    /**
+     * A value already cached (in memory, or saved by an earlier launch), without building anything:
+     * undefined when there is none yet. Lets work that's spread over many frames (a level generated
+     * step by step) skip itself entirely when a saved result exists, then save with `get`.
+     */
+    peek<T>(key: string): T | undefined;
     get<T>(key: string, build: () => T): T;
     private encode;
     private restore;

package/lib/typescript/src/assets/model.d.ts

@@ -1,3 +1,4 @@
+import { type MeshGeometry } from '../render/meshes.js';
 import type { Vec3 } from '../types.js';
 import type { AssetSource } from './source';
 export type ModelOptions = {
@@ -32,6 +33,15 @@ export declare function nativeGeometry(mesh: number): {
     vertices: Float32Array<ArrayBuffer>;
     indices: Uint32Array<ArrayBuffer>;
 };
+/**
+ * Registers a mesh the core already holds (a created, cached or loaded model, a glyph, an alias):
+ * the renderer copies it inside Rust, and JS reads its geometry only if something asks for it
+ * (merging, caching). Apps built before `renderModel` upload it through JS as before.
+ */
+export declare function registerCoreMesh(mesh: number, info?: {
+    texture?: number;
+    shine?: number;
+}, geometry?: () => MeshGeometry): void;
 /** Independent materials share core geometry without overwriting an existing model's appearance. */
 export declare function registerModelMesh(mesh: number, shine: number): number;
 /**

package/lib/typescript/src/index.d.ts

@@ -1,9 +1,12 @@
 export { World, isEngineAvailable } from './world/World.js';
 export { quat, type MutableQuat } from './world/quat.js';
+export { toColor, type ColorInput } from './world/color.js';
 export { effects, type DustOptions, type EffectOptions, type FlashOptions, type PopOptions } from './world/effects.js';
 export { Scoreboard, type ScoreboardHandlers } from './world/Scoreboard.js';
 export type { AnimateOptions, AnimateTarget, BodyType, Bounds, BurstOptions, CollisionInfo, ClipOptions, ScreenPlane, Color, Easing, Entity, EntityOptions, ImpactFeedback, Keyframe, PhysicsOptions, PickHit, Quat, RaycastHit, SpringOptions } from './world/types.js';
-export { GameView } from './render/GameView.js';
+export { afterNextFrame, GameView } from './render/GameView.js';
+export { useWorld, type WorldSetup } from './render/useWorld.js';
+export { frontLight } from './render/light.js';
 export { warmUpEngine, getMeshIdLimit } from './render/meshes.js';
 export type { TransformBatch, TransformOptions } from './world/TransformBatch.js';
 export type { DragEvent, GameViewProps, GameViewStats, OverlayTouchPhase, PinchEvent, SwipeDirection } from './render/GameView.js';

package/lib/typescript/src/native/EngineBridge.d.ts

@@ -4,11 +4,13 @@ export interface NativeGeometry {
     vertices: ArrayBuffer;
     indices: ArrayBuffer;
 }
-type BufferValue<T, Buffer> = T extends readonly number[] ? T : T extends object ? Buffer : T;
+type BufferValue<T, Buffer> = T extends readonly number[] ? T : T extends Promise<unknown> ? T : T extends (...args: never[]) => unknown ? T : T extends object ? Buffer : T;
 type BufferMethod<T> = T extends (...args: infer A) => infer R ? (...args: {
     [K in keyof A]: BufferValue<A[K], ArrayBufferLike>;
 }) => BufferValue<R, ArrayBuffer> : T;
-type BinarySpec = Omit<Spec, 'geometrySolid' | 'geometryOptimize' | 'modelSize' | 'textureSize'>;
+/** Native-only (a display clock and a render thread): absent on the web core and on older app builds. */
+type NativeFrames = 'publishFrame' | 'renderStats' | 'hasFrameClock' | 'startFrames' | 'stopFrames';
+type BinarySpec = Omit<Spec, 'geometrySolid' | 'geometryOptimize' | 'modelSize' | 'textureSize' | NativeFrames>;
 /** The same runtime ABI on JSI and WASM, with precise TypeScript buffer and tuple contracts. */
 export type EngineBridge = {
     [K in keyof BinarySpec]: BufferMethod<BinarySpec[K]>;
@@ -17,6 +19,8 @@ export type EngineBridge = {
     geometryOptimize(vertices: ArrayBufferLike, indices: ArrayBufferLike, ratio: number, error: number, lockBorders: boolean): NativeGeometry;
     modelSize(mesh: number): [x: number, y: number, z: number];
     textureSize(texture: number): [width: number, height: number];
+} & {
+    [K in NativeFrames]?: BufferMethod<Spec[K]>;
 };
 export {};
 //# sourceMappingURL=EngineBridge.d.ts.map

package/lib/typescript/src/native/spec/NativeNayanEngine.d.ts

@@ -90,6 +90,8 @@ export interface Spec extends TurboModule {
     shapePrepare(vertices: Object, indices: Object, options: string): number;
     solidPrepare(recipe: string, options: string): number;
     modelLoad(data: Object, center: boolean, fit: number): number;
+    /** `modelLoad` on a background native thread (the data is copied first): resolves to the mesh id, or -1. */
+    modelLoadAsync(data: Object, center: boolean, fit: number): Promise<number>;
     /** 11 floats per vertex (position, normal, color, uv); aliases native memory. */
     modelVertices(mesh: number): Object;
     /** u32 triangle indices; aliases native memory. */
@@ -102,6 +104,11 @@ export interface Spec extends TurboModule {
     meshAlias(base: number): number;
     /** Registers geometry (copied): 11 floats per vertex, u32 triangle indices. Returns the mesh id, or -1. */
     meshCreate(vertices: Object, indices: Object): number;
+    /**
+     * Hands a core model's own geometry (from `meshCreate`, `modelLoad`, a font) to the renderer, in
+     * Rust: nothing is copied through JS. `texture` -1 for none. False if the mesh is unknown.
+     */
+    renderModel(mesh: number, texture: number, shine: number): boolean;
     /**
      * Fills 2D contours ([x, y] f32 pairs, `counts[k]` points per contour) by the non-zero or even-odd
      * rule and extrudes them `depth` deep. Returns an ArrayBuffer of 11 floats per vertex (unindexed).
@@ -122,12 +129,16 @@ export interface Spec extends TurboModule {
     geometryPlace(vertices: Object, indices: Object, placement: Array<number>, first: number, outVertices: Object, vertexOffset: number, outIndices: Object, indexOffset: number): void;
     /** Decodes a PNG/JPEG ArrayBuffer. Returns the texture id, or -1. */
     textureLoad(data: Object): number;
+    /** `textureLoad` on a background native thread: resolves to the texture id, or -1. */
+    textureLoadAsync(data: Object): Promise<number>;
     /** RGBA8 pixels, top row first; aliases native memory. */
     texturePixels(texture: number): Object;
     /** [width, height]. */
     textureSize(texture: number): Array<number>;
     /** Builds extruded glyph meshes for `chars`. Returns the font id, or -1. */
     fontLoad(data: Object, depth: number, chars: string, weight: number): number;
+    /** `fontLoad` (outlines and glyph meshes) on a background native thread: resolves to the font id, or -1. */
+    fontLoadAsync(data: Object, depth: number, chars: string, weight: number): Promise<number>;
     /** [codepoint, mesh (-1 = nothing drawn), advance, ...] followed by the cap height. */
     fontGlyphs(font: number): Array<number>;
     /** Why the last model / texture / font / alias load failed ("" after a success). */
@@ -151,6 +162,22 @@ export interface Spec extends TurboModule {
      * Returns 1 (drawn), 0 (surface not ready yet / frame skipped) or -1 (see `renderError`).
      */
     renderFrame(surface: number, frame: Object, matrices: Object, colors: Object, regions: Object, ranges: Object, count: number, viewProj: Object, world: number): number;
+    /**
+     * `renderFrame`'s arguments, but the frame is copied and drawn on the native render thread: returns
+     * at once, with `viewProj` written. 1 once the surface has presented a frame, 0 before, -1 if the
+     * last frame failed (see `renderError`).
+     */
+    publishFrame(surface: number, frame: Object, matrices: Object, colors: Object, regions: Object, ranges: Object, count: number, viewProj: Object, world: number): number;
+    /** [frames presented, smoothed render milliseconds] for a surface drawn by the render thread. */
+    renderStats(surface: number): Array<number>;
+    /** True where the platform drives frames from its display clock (`startFrames`); else use requestAnimationFrame. */
+    hasFrameClock(): boolean;
+    /**
+     * Calls `onFrame` on the JS thread once per display refresh while the surface is attached and
+     * visible, with the frame time in milliseconds. A frame JS hasn't started yet isn't queued again.
+     */
+    startFrames(surface: number, onFrame: (timeMs: number) => void): void;
+    stopFrames(surface: number): void;
     /**
      * The screen-space overlay drawn over surface `surface` from its next frame on, copied from a world's
      * buffers. In points: x right and y up from the view's top-left (on screen y <= 0), z toward the
@@ -167,6 +194,8 @@ export interface Spec extends TurboModule {
     drawingDestroy(document: number): void;
     /** Decodes a WAV ArrayBuffer. Returns a sound id, or -1. */
     audioLoad(data: Object): number;
+    /** `audioLoad` on a background native thread: resolves to the sound id, or -1. */
+    audioLoadAsync(data: Object): Promise<number>;
     /** Returns a voice id (> 0), or 0 if nothing played. */
     audioPlay(sound: number, volume: number, pan: number, pitch: number, loop: boolean): number;
     audioStop(voice: number): void;

package/lib/typescript/src/render/GameView.d.ts

@@ -1,7 +1,18 @@
 import { type Camera, type Light, type RenderSource } from '../types.js';
-import type { Color } from '../world/types.js';
+import { type ColorInput } from '../world/color.js';
 import { type ViewStyle } from './host';
 import { type RenderQuality, type RenderQualitySetting } from './quality.js';
+/**
+ * Runs `fn` right after the next frame a GameView hands to the screen, on the same display clock
+ * (the native one where the platform has it): the time a frame leaves is the best moment for
+ * background work, such as loading in slices. With no GameView running it falls back to
+ * requestAnimationFrame. Returns a function that cancels it.
+ *
+ * ```ts
+ * const cancel = afterNextFrame(() => buildNextChunk());
+ * ```
+ */
+export declare function afterNextFrame(fn: () => void): () => void;
 export type GameViewStats = {
     fps: number;
     /** Mean time spent in `onUpdate` per frame, in milliseconds. */
@@ -41,15 +52,16 @@ export type GameViewProps = {
     source: RenderSource;
     /**
      * Your game loop, called once per frame before drawing, with the elapsed seconds (capped at 0.1;
-     * 0 until the first frame is on screen, so nothing plays out unseen).
-     * Step your simulation here, e.g. `world.update(dt)`, then read input, spawn, move the camera.
+     * 0 until the first frame is on screen, so nothing plays out unseen): read input, spawn, move the
+     * camera. The world (and `overlay`) is stepped for you right after; call `world.update(dt)` here
+     * yourself only to step it at a different point or with a different `dt`.
      */
     onUpdate?: (dt: number) => void;
     /** Mutate this object (e.g. `camera.eye`) from `onUpdate`; it is read every frame. */
     camera?: Camera;
     light?: Light;
-    /** Sky / clear color, linear 0..1 RGB (alpha ignored). Also the fog color. Default dark navy. */
-    background?: Color;
+    /** Sky / clear color: a CSS color or linear 0..1 RGB (alpha ignored). Also the fog color. Default dark navy. */
+    background?: ColorInput;
     /** Distance fog density towards `background` (e.g. 0.02). Default 0 (off). */
     fog?: number;
     /**
@@ -76,8 +88,8 @@ export type GameViewProps = {
     /**
      * A screen-space layer drawn over the scene by the renderer (scoreboards, buttons): usually a second
      * `World`, in points from the view's top-left with y up (so on screen y <= 0) and z toward the viewer
-     * within -100..100. Unlit (flat faces show their exact color) and always in front. Step it yourself
-     * (`overlay.update(dt)` in `onUpdate`).
+     * within -100..100. Unlit (flat faces show their exact color) and always in front. Stepped each
+     * frame like `source`.
      */
     overlay?: RenderSource;
     /**

package/lib/typescript/src/render/light.d.ts

@@ -0,0 +1,12 @@
+import type { Light } from '../types.js';
+/**
+ * A light for flat, front-facing scenes (boards, puzzles, 2D games looking down -z): surfaces facing
+ * the camera (+z) are lit at exactly 1, so flat panels show their color unchanged, while rounded
+ * shapes keep their shading (lighter toward the light, darker away). Shadows are off.
+ *
+ * ```tsx
+ * <GameView source={world} light={frontLight([-0.45, 0.6, 1], 0.5)} />
+ * ```
+ */
+export declare function frontLight(direction: [number, number, number], ambient: number): Light;
+//# sourceMappingURL=light.d.ts.map

package/lib/typescript/src/render/quality.d.ts

@@ -23,8 +23,9 @@ export type FrameReport = {
 };
 /**
  * Picks the level for "auto": starts at the best, steps down one level after `SLOW_SECONDS`
- * consecutive seconds whose typical frame misses ~50 fps while drawing took most of it, and steps
- * back up after `FAST_SECONDS` smooth seconds. A level that fails again soon after being restored
+ * consecutive seconds whose typical frame misses ~50 fps while drawing took most of it (after a
+ * single second when it misses ~33 fps, so a struggling phone recovers in seconds rather than
+ * stuttering through every level), and steps back up after `FAST_SECONDS` smooth seconds. A level that fails again soon after being restored
  * becomes the ceiling, so it never bounces.
  */
 export declare class AutoQuality {
@@ -35,6 +36,7 @@ export declare class AutoQuality {
     private changed;
     private raisedAt;
     private slow;
+    private verySlow;
     private fast;
     get quality(): RenderQuality;
     /** Feeds one second of frames; returns true when the level changed. */

package/lib/typescript/src/render/useWorld.d.ts

@@ -0,0 +1,20 @@
+import { type DependencyList } from 'react';
+import { World } from '../world/World.js';
+/** What `useWorld`'s setup may return: a cleanup, run just before the world is disposed. */
+export type WorldSetup = (world: World) => void | (() => void);
+/**
+ * A `World` owned by a component: the engine is warmed up (needed on the web, cheap on mobile), the
+ * world is created with `capacity` entity slots and handed to `setup` to fill, and it is disposed on
+ * unmount. A change in `deps` replaces it with a fresh one. Returns null until it's ready (one frame),
+ * and while the engine is unavailable (Expo Go) or failed to start (`onError`, console by default).
+ *
+ * ```tsx
+ * const world = useWorld(100, (w) => {
+ *   w.spawn({ mesh: 'plane', scale: [20, 1, 20], color: '#4C9A4C', physics: 'fixed' });
+ *   w.spawn({ mesh: 'sphere', position: [0, 4, 0], color: '#3399FF', physics: 'dynamic' });
+ * });
+ * return world && <GameView source={world} style={{ flex: 1 }} />;
+ * ```
+ */
+export declare function useWorld(capacity: number, setup?: WorldSetup, deps?: DependencyList, onError?: (error: Error) => void): World | null;
+//# sourceMappingURL=useWorld.d.ts.map

package/lib/typescript/src/types.d.ts

@@ -1,4 +1,5 @@
-import type { Color, Entity } from './world/types.js';
+import type { ColorInput } from './world/color.js';
+import type { Entity } from './world/types.js';
 export type Vec3 = readonly [number, number, number];
 /** Number of mesh ids: built-in shapes (0..15), then loaded models, glyphs and textured variants. */
 export declare const MAX_MESHES = 4096;
@@ -23,6 +24,14 @@ export interface RenderSource {
     readonly capacity: number;
     /** Called by GameView after each frame with the camera it drew with (for picking and `toScreen`). */
     setView?(viewProj: Float32Array, width: number, height: number): void;
+    /**
+     * Steps the source. When present, GameView calls it once a frame after `onUpdate`, unless
+     * `onUpdate` already did (`updateCount` changed) or the source is disposed.
+     */
+    update?(dt: number): void;
+    /** How many times `update` has run. */
+    readonly updateCount?: number;
+    readonly isDisposed?: boolean;
 }
 /**
  * Built-in shapes, each 1 unit across before scaling. "none" isn't drawn (groups, pivots, trigger zones).
@@ -64,9 +73,9 @@ export type Light = {
     shadowExtent?: number;
     /**
      * Color and brightness of the light, multiplying both sun and ambient: e.g. [0.35, 0.38, 0.6] for
-     * moonlight. Glowing colors (channels above 1) aren't affected. Alpha, if given, is ignored.
-     * Default [1, 1, 1].
+     * moonlight, or a CSS color. Glowing colors (channels above 1) aren't affected. Alpha, if given, is
+     * ignored. Default [1, 1, 1].
      */
-    color?: Color;
+    color?: ColorInput;
 };
 //# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/world/Scoreboard.d.ts

@@ -12,10 +12,12 @@ export type ScoreboardHandlers = {
 /**
  * Score, lives and the game clock, kept and advanced in Rust by `world.update`: countdowns, elapsed
  * time and time-based points (survival, distance) cost no JS per frame. Handlers run from `update`
- * only when something they show changed.
+ * only when something they show changed. Set `handlers` for the game's own rules, and `listen` for
+ * anything else that follows along (a UI showing the score), so neither replaces the other.
  *
  * ```ts
- * world.scoreboard.handlers = { onScore: setScore, onSecond: setTime, onTimeUp: () => end(true) };
+ * world.scoreboard.handlers = { onTimeUp: () => end(true) };
+ * const stop = world.scoreboard.listen({ onScore: setScore, onSecond: setTime });
  * world.scoreboard.reset(3);
  * world.scoreboard.startCountdown(60);
  * world.scoreboard.add(10);
@@ -23,7 +25,9 @@ export type ScoreboardHandlers = {
  */
 export declare class Scoreboard {
     private readonly world;
+    /** The game's own handlers. `listen` adds more without replacing these. */
     handlers: ScoreboardHandlers;
+    private readonly listeners;
     private readonly state;
     /** @internal */
     constructor(world: number);
@@ -59,7 +63,13 @@ export declare class Scoreboard {
      * that countdown in full (a ready screen); `resume()` starts it.
      */
     reset(lives?: number, countdownSeconds?: number): void;
+    /**
+     * Adds handlers alongside `handlers` (and other listeners); they run after them, in order of
+     * listening. Returns a function that removes them.
+     */
+    listen(handlers: ScoreboardHandlers): () => void;
     /** @internal Runs handlers for what changed since the last call. */
     dispatch(): void;
+    private run;
 }
 //# sourceMappingURL=Scoreboard.d.ts.map

package/lib/typescript/src/world/TransformBatch.d.ts

@@ -2,8 +2,8 @@ import type { Entity, EntityOptions } from './types.js';
 export type TransformOptions = Pick<EntityOptions, 'position' | 'rotation' | 'scale' | 'color'>;
 export declare const TRANSFORM_STRIDE = 16;
 /**
- * Explicit draw-only updates, applied in one native call by `flush()`. Flush before reading
- * positions, animating, or stepping the world. Records and scratch storage are reused; values are
+ * Explicit draw-only updates, applied in one native call by `flush()`. `world.update` flushes
+ * `world.transforms` before stepping; flush yourself before reading positions or animating. Records and scratch storage are reused; values are
  * copied when queued, never retained by reference. The scalar methods (`position`, `rotation`,
  * `scale`, `color`, `transform`) allocate nothing; consecutive calls for the same entity share one
  * record.

package/lib/typescript/src/world/World.d.ts

@@ -44,6 +44,7 @@ export declare class World implements RenderSource {
     private gravityValue;
     private boundsValue;
     private listenerValue;
+    private updates;
     constructor(capacity: number);
     private get native();
     /** True once `dispose()` has run. Cleanup calls (despawn, set, has, queries, stopping animations
@@ -61,7 +62,8 @@ export declare class World implements RenderSource {
     set(e: Entity, options: EntityOptions): boolean;
     /**
      * This world's shared draw-only transform batch (created on first use). Queue per-frame moves with
-     * its allocation-free methods after `update()`, then `flush()` once before the frame is drawn.
+     * its allocation-free methods; the next `update()` applies them first (or `flush()` them yourself
+     * before reading positions or animating).
      */
     get transforms(): TransformBatch;
     /** Reusable draw-only transforms; use set() for text entities and flush before animations/queries. */
@@ -131,6 +133,8 @@ export declare class World implements RenderSource {
     cancelTimers(): void;
     /** Score, lives and the game clock, kept in Rust (created on first use). */
     get scoreboard(): Scoreboard;
+    /** How many times `update` has run. GameView reads it to step the world only when `onUpdate` didn't. */
+    get updateCount(): number;
     /** Timers waiting to fire. */
     get timerCount(): number;
     /** Resolves the promises of animations the core reports as ended, then runs due timers. */
@@ -183,7 +187,11 @@ export declare class World implements RenderSource {
     /** Impact sounds pan and fade relative to this entity (usually the player). */
     get listener(): Entity | null;
     set listener(e: Entity | null);
-    /** Advances the simulation (fixed 60 Hz steps), resolves finished animations, refreshes what GameView draws. */
+    /**
+     * Advances the simulation (fixed 60 Hz steps), resolves finished animations, runs due timers and
+     * scoreboard handlers, and refreshes what GameView draws. `GameView` calls it for you each frame;
+     * call it yourself from `onUpdate` only to step with a different `dt` (it is then not stepped twice).
+     */
     update(dt: number): void;
     /**
      * Calls `fn` for each touch that started or ended during the last `update`. `info` is reused:

package/lib/typescript/src/world/color.d.ts

@@ -0,0 +1,18 @@
+import type { Color } from './types.js';
+/** A color as an option takes it: `[r, g, b]` / `[r, g, b, a]` (0..1, channels above 1 glow) or a CSS string. */
+export type ColorInput = Color | string;
+/**
+ * Any color input as an `[r, g, b, a]` tuple (0..1), with its alpha multiplied by `alpha`. Use it when
+ * you need the numbers (to brighten, mix or fade a theme color); options take strings directly.
+ *
+ * ```ts
+ * toColor('#FF4757'); // [1, 0.278, 0.341, 1]
+ * toColor('#FF4757', 0.5); // half see-through
+ * ```
+ */
+export declare function toColor(color: ColorInput, alpha?: number): [number, number, number, number];
+/** A color input as a tuple, without copying tuples (the hot path of `spawn`, `set` and `animate`). */
+export declare function resolveColor(color: ColorInput): Color;
+/** One color input, or a list to pick from, as tuples. */
+export declare function resolveColors(colors: ColorInput | readonly ColorInput[]): readonly Color[];
+//# sourceMappingURL=color.d.ts.map