@nayan-ui/engine 0.0.0-stage → 1.0.0-beta.4

package/lib/web/types/src/native/spec/NativeNayanEngine.d.ts

@@ -0,0 +1,210 @@
+import { type TurboModule } from 'react-native';
+/**
+ * Bridge to the Rust core. Use the `World`, `audio` and `haptics` APIs instead of calling this.
+ *
+ * Worlds are identified by the number `createWorld` returns; entity ids are opaque numbers.
+ * Entities are created and changed with one call each: `spawnDesc` / `setDesc` take a
+ * Float64Array's ArrayBuffer encoding every option (layout in native/core/include/engine_core.h).
+ * Capacity is fixed at creation, so the buffers returned by `get*` alias Rust memory (zero-copy)
+ * and stay valid until `destroyWorld`.
+ */
+export interface Spec extends TurboModule {
+    createWorld(capacity: number): number;
+    destroyWorld(world: number): void;
+    /** Returns the entity id, or -1 if the world is full or the description is rejected. */
+    spawnDesc(world: number, desc: Object): number;
+    /** Returns false if the entity is gone or a field was rejected (the rest still apply). */
+    setDesc(world: number, entity: number, desc: Object): boolean;
+    /** Packed draw transforms, 16 doubles per record: id, flags, position, rotation, scale, color. */
+    setTransforms(world: number, data: Object, count: number): number;
+    /** Returns false for stale or unknown ids. */
+    despawn(world: number, entity: number): boolean;
+    /** Instant change in momentum (dynamic bodies only). */
+    impulse(world: number, entity: number, x: number, y: number, z: number): void;
+    setGravity(world: number, x: number, y: number, z: number): void;
+    setBounds(world: number, minX: number, minZ: number, maxX: number, maxZ: number): void;
+    /** Entity used to pan/attenuate impact sounds (-1 clears). */
+    setListener(world: number, entity: number): void;
+    /** Returns the hit entity or -1; on a hit the scratch buffer holds distance, normal, point. */
+    raycast(world: number, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDistance: number, mask: number): number;
+    /** Nearest pickable entity along a ray (as last drawn), or -1; on a hit the scratch buffer holds distance, point. */
+    pick(world: number, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number): number;
+    /** Nearest pickable entity under a screen point (in view points), or -1; scratch holds distance, point. */
+    pickScreen(world: number, x: number, y: number): number;
+    /** Stores the view-projection matrix (16 column-major floats) and view size in points. */
+    setView(world: number, viewProj: Object, width: number, height: number): void;
+    /** World ray [origin xyz, direction xyz] through a view point. Writes into scratch[0..6]. Returns true on success. */
+    screenRay(world: number, x: number, y: number): boolean;
+    /** Where a view point lands on a plane. Writes into scratch[0..3]. Returns true on success. */
+    screenToWorld(world: number, x: number, y: number, ppx: number, ppy: number, ppz: number, pnx: number, pny: number, pnz: number): boolean;
+    /** Where a world position appears on screen (points from top-left). Writes into scratch[0..2]. */
+    toScreen(world: number, x: number, y: number, z: number): boolean;
+    /**
+     * Write position / velocity to the scratch buffer (`getScratch`). Return false if not alive.
+     * `rendered`: where it was last drawn, in world space (otherwise simulated, relative to its parent).
+     */
+    readPosition(world: number, entity: number, rendered: boolean): boolean;
+    readVelocity(world: number, entity: number): boolean;
+    /** Starts an animation (Float64Array buffer, layout in engine_core.h). Returns its id, or 0 if nothing started. */
+    animate(world: number, animation: Object): number;
+    stopAnimation(world: number, entity: number): boolean;
+    /** Spawns a particle burst (Float64Array buffer). Returns how many particles were spawned. */
+    burst(world: number, burst: Object): number;
+    update(world: number, dt: number): void;
+    /** Starts a timer firing `seconds` of update time from now; its id is reported in `getDone`. Returns the id, or 0. */
+    after(world: number, seconds: number): number;
+    /** Drops every pending timer. Returns how many were dropped. */
+    cancelTimers(world: number): number;
+    /** Score / lives / clock operation (layout in engine_core.h). Returns the score after it. */
+    scoreboard(world: number, op: number, a: number, b: number): number;
+    /** 8 doubles: score, lives, seconds, shown seconds, changed flags, running, points per second, best. Aliases native memory. */
+    getScoreboard(world: number): Object;
+    count(world: number): number;
+    /** capacity * 16 floats, column-major, grouped by mesh. */
+    getMatrices(world: number): Object;
+    /** capacity * 4 floats (rgba), same order as the matrices. */
+    getColors(world: number): Object;
+    /** capacity * 4 floats: texture region (u0 v0 u1 v1), same order as the matrices. */
+    getRegions(world: number): Object;
+    /** MAX_MESHES * 4 u32: [first, count] per mesh id for opaque instances, then for transparent ones. */
+    getRanges(world: number): Object;
+    /** Ids of animations that ended since the last update began (room for capacity * 5 + 64). */
+    getDone(world: number): Object;
+    doneLength(world: number): number;
+    /** Collision events from the last update, 4 u32 each: [a, b, flags, speed as f32 bits]. */
+    getEvents(world: number): Object;
+    eventLength(world: number): number;
+    /** 16 floats. */
+    getScratch(world: number): Object;
+    /** Parses a glTF/GLB ArrayBuffer. Returns its mesh id, or -1 (see `loadError`). */
+    /** Joint count and animation clips as JSON, loaded once with the model. */
+    modelRig(mesh: number): string;
+    playClip(world: number, entity: number, clip: string, loop: boolean, speed: number, fade: number, time: number): boolean;
+    stopClip(world: number, entity: number, reset: boolean): boolean;
+    skinPoints(world: number, entity: number, vertices: Object, output: Object, after: number): boolean;
+    /** Rust owns cache hashing, persistence, validation and mesh preparation. */
+    cacheRead(key: string): Object;
+    cacheWrite(key: string, data: Object): boolean;
+    cacheRemove(key: string): boolean;
+    cacheClear(): boolean;
+    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. */
+    modelIndices(mesh: number): Object;
+    /** Full bounding-box size [x, y, z]. */
+    modelSize(mesh: number): Array<number>;
+    /** The model's base color texture id, or -1. */
+    modelTexture(mesh: number): number;
+    /** A new mesh id with `base`'s geometry (to give it another texture), or -1. */
+    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).
+     */
+    pathExtrude(points: Object, counts: Array<number>, depth: number, evenOdd: boolean): Object;
+    /** Recomputes normals in place (vertex / u32 index ArrayBuffers), averaged across vertices at the same place. */
+    geometrySmoothNormals(vertices: Object, indices: Object): void;
+    /** Tessellates a solid recipe; returns independent vertex/index ArrayBuffers, with no mesh registration. */
+    geometrySolid(recipe: string): Object;
+    /** Cleans, simplifies and optimizes a mesh, preserving normal/color/UV attributes. */
+    geometryOptimize(vertices: Object, indices: Object, ratio: number, error: number, lockBorders: boolean): Object;
+    /** Flips triangles in place whose winding disagrees with their vertex normals. */
+    geometryFaceOutward(vertices: Object, indices: Object): void;
+    /**
+     * Bakes a part into merged buffers: `placement` = position xyz, rotation quat xyzw, scale xyz, color
+     * rgb. Writes at `vertexOffset` floats / `indexOffset` indices, indices offset by `first`.
+     */
+    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). */
+    loadError(): string;
+    /** Generates and registers all built-in shape meshes (cube, sphere, etc.) in the native renderer. */
+    generateBuiltinMeshes(): void;
+    /**
+     * Builds the GPU device and shader pipelines on a background thread, ahead of the first surface.
+     * Returns at once; repeat calls do nothing.
+     */
+    renderWarmUp(): void;
+    /** Returns a copy of a registered mesh's vertices (11 floats per vertex), or empty if not found. */
+    renderMeshVertices(mesh: number): Object;
+    /** Returns a copy of a registered mesh's indices (u32 triangle list), or empty if not found. */
+    renderMeshIndices(mesh: number): Object;
+    /** Geometry (copied) drawn for a mesh id: 11 floats per vertex, u32 indices. `texture` -1 = none. */
+    renderMesh(mesh: number, vertices: Object, indices: Object, texture: number, shine: number): void;
+    /**
+     * Draws a frame into surface `surface`. `frame`: Float64Array buffer (layout in engine_core.h);
+     * instance buffers hold the same number of instances; `viewProj` (16 floats) gets the camera used.
+     * 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
+     * viewer within -100..100; `width` x `height` is the view in points. Unlit, always in front of the
+     * scene. count 0 removes it.
+     */
+    renderOverlay(surface: number, matrices: Object, colors: Object, regions: Object, ranges: Object, count: number, width: number, height: number): void;
+    renderError(): string;
+    /** "vulkan", "gl" or "metal" ("" before the first surface). */
+    renderBackend(): string;
+    /** Native 2D drawing documents; commands return owned JSON results. */
+    drawingCreate(width: number, height: number, ratio: number): number;
+    drawingCommand(document: number, command: string): string;
+    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;
+    audioSetVolume(volume: number): void;
+    audioSetMuted(muted: boolean): void;
+    audioIsRunning(): boolean;
+    hapticsSupported(): boolean;
+    /** Taps as flat [time, intensity, sharpness, ...] triples. */
+    hapticsPlay(taps: Array<number>, throttle: boolean): void;
+}
+declare const _default: Spec | null | undefined;
+export default _default;

package/lib/web/types/src/render/GameView.d.ts

@@ -0,0 +1,106 @@
+import { type Camera, type Light, type RenderSource } from '../types';
+import { type ColorInput } from '../world/color';
+import { type ViewStyle } from './host';
+import { type RenderQuality, type RenderQualitySetting } from './quality';
+/**
+ * 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. */
+    updateMs: number;
+    /** Average milliseconds per frame spent drawing (CPU side, including waiting on the GPU). */
+    renderMs: number;
+    /** The quality level drawn with (with `quality="auto"`, the one it settled on so far). */
+    quality: RenderQuality;
+    /** The graphics API drawing: "vulkan", "gl" (OpenGL ES) or "metal". */
+    backend: string;
+};
+export type SwipeDirection = 'left' | 'right' | 'up' | 'down';
+export type OverlayTouchPhase = 'start' | 'move' | 'end' | 'cancel';
+export type DragEvent = {
+    phase: 'start' | 'move' | 'end';
+    /** Finger position in the view, in points. */
+    x: number;
+    y: number;
+    /** Distance moved since the drag started, in points. */
+    dx: number;
+    dy: number;
+    /** On "end": the drag was interrupted (a second finger started a pinch, or the system took the touch). Put a held piece back. */
+    cancelled?: boolean;
+};
+export type PinchEvent = {
+    phase: 'start' | 'move' | 'end';
+    /** Finger spread relative to the start: 2 = twice as far apart (zoom in). */
+    scale: number;
+    /** Radians the two fingers turned since the start, clockwise on screen. */
+    rotation: number;
+    /** Midpoint between the fingers in the view, in points. */
+    x: number;
+    y: number;
+};
+export type GameViewProps = {
+    /** What to draw (usually a `World`). Changing it restarts the view; never pass a disposed world. */
+    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): 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: 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;
+    /**
+     * Resolution, anti-aliasing and shadow quality. "auto" (default) starts at "high", steps down only
+     * while the GPU really can't keep up (shadow detail first, then anti-aliasing, resolution last) and
+     * steps back up once frames are smooth again, so every phone gets the best look it can hold.
+     */
+    quality?: RenderQualitySetting;
+    /** Suspend updates and drawing while keeping the native surface mounted. */
+    paused?: boolean;
+    style?: ViewStyle;
+    /** A quick tap, at `x, y` points in the view. `world.pick(x, y)` finds what was tapped. */
+    onTap?: (x: number, y: number) => void;
+    /** A quick flick in one direction (2048, runners, sliding puzzles). */
+    onSwipe?: (direction: SwipeDirection) => void;
+    /** Finger down, moving and up (aiming, dragging pieces, slicing). */
+    onDrag?: (drag: DragEvent) => void;
+    /** A finger held still for half a second (pick up, show moves). No tap follows. */
+    onLongPress?: (x: number, y: number) => void;
+    /** Two fingers spreading, pinching or turning (zoom and rotate a board). Ends any drag in progress. */
+    onPinch?: (pinch: PinchEvent) => void;
+    /** Host primary action for keyboard input, such as Start/Stop or Play Again. */
+    onPrimaryAction?: () => void;
+    /**
+     * 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. Stepped each
+     * frame like `source`.
+     */
+    overlay?: RenderSource;
+    /**
+     * Touches for the overlay, in points in the view. Return true from "start" to claim the touch (a
+     * button was hit): its moves and end come here, and the game gets no drag, tap or swipe for it.
+     * "cancel" when the system takes the touch.
+     */
+    onOverlayTouch?: (phase: OverlayTouchPhase, x: number, y: number) => boolean | void;
+    /** Called once a second. */
+    onStats?: (stats: GameViewStats) => void;
+    /** GPU setup failures and rendering errors. Defaults to console.error. */
+    onError?: (error: Error) => void;
+};
+export declare function GameView(props: GameViewProps): import("react").JSX.Element;

package/lib/web/types/src/render/camera.d.ts

@@ -0,0 +1,5 @@
+import type { Camera, RenderSource } from '../types';
+/** `camera.follow`: ease the target toward the entity (where it was last drawn) and keep the eye at the offset. */
+export declare function follow(camera: Camera, source: RenderSource, out: [number, number, number], dt: number): void;
+/** `camera.shake`: a jittered copy of the camera; the strength fades by itself. */
+export declare function shake(camera: Camera, out: Camera, dt: number): Camera;

package/lib/web/types/src/render/host.d.ts

@@ -0,0 +1,15 @@
+import { type CSSProperties } from 'react';
+import { createTouchResponder } from './touch';
+export { createTouchResponder };
+export type ViewStyle = CSSProperties;
+export declare const pixelRatio: () => number;
+export declare function useActive(): boolean;
+interface SurfaceProps {
+    surfaceId: number;
+    style?: CSSProperties;
+    onSize: (width: number, height: number) => void;
+    onError: (error: Error) => void;
+    touch?: ReturnType<typeof createTouchResponder>;
+    onPrimaryAction?: () => void;
+}
+export declare function Surface({ surfaceId, style, onSize, onError, touch, onPrimaryAction }: SurfaceProps): import("react").JSX.Element;

package/lib/web/types/src/render/light.d.ts

@@ -0,0 +1,11 @@
+import type { Light } from '../types';
+/**
+ * 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;

package/lib/web/types/src/render/meshes.d.ts

@@ -0,0 +1,44 @@
+export declare const VERTEX_FLOATS = 11;
+type V3 = readonly [number, number, number];
+export declare class Builder {
+    vertices: number[];
+    indices: number[];
+    /** Adds a vertex, returns its index. */
+    vertex(p: V3, n: V3, u: number, v: number): number;
+    /** Two triangles, counter-clockwise a b c d as seen from the front. */
+    quad(a: number, b: number, c: number, d: number): void;
+    /**
+     * A (rows + 1) x (cols + 1) vertex grid; `at(u, v)` gives position and normal. u runs along a row and
+     * v down the rows; the grid faces the side from which u goes right and v goes down.
+     */
+    grid(rows: number, cols: number, at: (u: number, v: number) => [V3, V3]): void;
+    /** A flat disc at height y facing up (+1) or down (-1). */
+    disc(y: number, radius: number, facing: 1 | -1, segments: number): void;
+}
+/** Render-ready geometry: VERTEX_FLOATS floats per vertex, u32 triangle indices. */
+export type MeshGeometry = {
+    vertices: Float32Array;
+    indices: Uint32Array;
+};
+/** What the renderer draws for a mesh id: geometry, and a texture id (see `loadTexture`) if any. */
+/** `shine` 0..1: how glossy (sun highlight and sky reflection), 0 = matte. */
+export type MeshInfo = {
+    geometry: MeshGeometry;
+    texture?: number;
+    shine?: number;
+};
+/** Registers what a mesh id draws (loaded models, glyphs, textured variants). */
+export declare function registerMesh(mesh: number, info: MeshInfo, uploadGeometry?: boolean): void;
+/** One past the highest mesh id in use: per-frame scans of a source's ranges stop here. */
+export declare const getMeshIdLimit: () => number;
+/** Generates the built-in shapes in the Rust core and registers them with the native renderer (once). */
+export declare function uploadBuiltInMeshes(): void;
+/**
+ * Initializes the shared core and built-in meshes. Await before using the engine on the web.
+ * Mobile initialization remains synchronous and also warms the GPU on a background thread.
+ * Repeat calls reuse initialization and mesh registration.
+ */
+export declare function warmUpEngine(): Promise<void>;
+/** What to draw for a mesh id, or undefined ("none", or unknown). Built-in shapes use native geometry. */
+export declare function meshInfo(mesh: number): MeshInfo | undefined;
+export {};

package/lib/web/types/src/render/quality.d.ts

@@ -0,0 +1,47 @@
+export type RenderQuality = 'high' | 'medium' | 'low' | 'lowest';
+/** `"auto"` starts at "high" and steps down only while the device really can't keep up. */
+export type RenderQualitySetting = RenderQuality | 'auto';
+export type QualityLevel = {
+    /** Most device pixels drawn per point (the screen's own ratio when lower). */
+    maxPixelRatio: number;
+    /** MSAA samples: 4 or 1 (off). */
+    samples: 1 | 4;
+    /** Shadow map width and height in texels. */
+    shadowSize: number;
+    /** 3x3 filtered (soft) shadow edges, or a single tap (hard). */
+    softShadows: boolean;
+};
+/** From best looking to cheapest; "auto" walks down this list only as far as it must. */
+export declare const QUALITIES: readonly RenderQuality[];
+export declare const QUALITY_LEVELS: Record<RenderQuality, QualityLevel>;
+/** One second of frames, as the frame loop measured it. */
+export type FrameReport = {
+    /** The typical (median) time between frames, in ms: hiccups (garbage collection, a busy JS frame) don't move it. */
+    frameMs: number;
+    /** The typical (median) time spent drawing a frame, in ms (including any wait for the screen). */
+    renderMs: number;
+};
+/**
+ * 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 (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 {
+    private index;
+    /** The best level it may return to (raised past a level that keeps failing). */
+    private ceiling;
+    private started;
+    private changed;
+    private raisedAt;
+    private slow;
+    private verySlow;
+    private fast;
+    get quality(): RenderQuality;
+    /** Feeds one second of frames; returns true when the level changed. */
+    report(now: number, frames: FrameReport): boolean;
+    private moved;
+}
+/** The middle value of `values` (sorted in place). */
+export declare function median(values: number[]): number;

package/lib/web/types/src/render/responder.d.ts

@@ -0,0 +1,39 @@
+import type { PointerEvent as ReactPointerEvent } from 'react';
+type Touch = {
+    pageX: number;
+    pageY: number;
+};
+interface Event {
+    nativeEvent: Touch & {
+        locationX: number;
+        locationY: number;
+        touches: Touch[];
+    };
+}
+interface Gesture {
+    dx: number;
+    dy: number;
+}
+interface Callbacks {
+    onStartShouldSetPanResponder: () => boolean;
+    onMoveShouldSetPanResponder: () => boolean;
+    onPanResponderGrant: (event: Event) => void;
+    onPanResponderMove: (event: Event, gesture: Gesture) => void;
+    onPanResponderRelease: (event: Event, gesture: Gesture) => void;
+    onPanResponderTerminate: (event: Event, gesture: Gesture) => void;
+}
+export interface PanResponderInstance {
+    panHandlers: {
+        onPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void;
+        onPointerMove: (event: ReactPointerEvent<HTMLDivElement>) => void;
+        onPointerUp: (event: ReactPointerEvent<HTMLDivElement>) => void;
+        onPointerCancel: (event: ReactPointerEvent<HTMLDivElement>) => void;
+        onLostPointerCapture: (event: ReactPointerEvent<HTMLDivElement>) => void;
+    };
+    cancel: () => void;
+}
+/** Adapt DOM pointer capture to the gesture recognizer used on mobile. Coordinates stay in CSS pixels. */
+export declare const PanResponder: {
+    create(callbacks: Callbacks): PanResponderInstance;
+};
+export {};

package/lib/web/types/src/render/touch.d.ts

@@ -0,0 +1,25 @@
+import type { DragEvent, OverlayTouchPhase, PinchEvent, SwipeDirection } from './GameView';
+import { type PanResponderInstance } from './responder';
+declare const TAP_SLOP = 10;
+declare const TAP_TIME = 300;
+declare const SWIPE_DISTANCE = 30;
+declare const SWIPE_SPEED = 0.3;
+declare const LONG_PRESS_TIME = 500;
+type Handlers = {
+    onTap?: (x: number, y: number) => void;
+    onSwipe?: (direction: SwipeDirection) => void;
+    onDrag?: (drag: DragEvent) => void;
+    onLongPress?: (x: number, y: number) => void;
+    onPinch?: (pinch: PinchEvent) => void;
+    onOverlayTouch?: (phase: OverlayTouchPhase, x: number, y: number) => boolean | void;
+};
+/**
+ * Creates a PanResponder that recognizes taps, swipes, drags, long presses and pinches.
+ * `getHandlers` is called on each event so the caller can swap handlers without recreating the responder.
+ */
+export declare function createTouchResponder(getHandlers: () => Handlers): {
+    responder: PanResponderInstance;
+    dispose: () => void;
+    cancel: () => void;
+};
+export { TAP_SLOP, TAP_TIME, SWIPE_DISTANCE, SWIPE_SPEED, LONG_PRESS_TIME };

package/lib/web/types/src/render/useWorld.d.ts

@@ -0,0 +1,19 @@
+import { type DependencyList } from 'react';
+import { World } from '../world/World';
+/** 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;

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

@@ -0,0 +1,80 @@
+import type { ColorInput } from './world/color';
+import type { Entity } from './world/types';
+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;
+/** What the renderer draws. `World` implements it; so can any custom simulation. */
+export interface RenderSource {
+    /** Native world id, when this source supports skeletal characters. */
+    readonly nativeWorld?: number;
+    /** Column-major mat4 per instance (16 floats), grouped by mesh. Only the first `count` are valid. */
+    readonly matrices: Float32Array;
+    /** RGBA per instance (4 floats), same order as `matrices`. Alpha below 1 draws see-through. */
+    readonly colors: Float32Array;
+    /** Texture region per instance (u0 v0 u1 v1), same order. Optional: the whole texture by default. */
+    readonly regions?: Float32Array;
+    /**
+     * `[first, count]` per mesh id, in instances: opaque instances at `ranges[2 * mesh]`, transparent ones
+     * at `ranges[2 * (MAX_MESHES + mesh)]`. Shorter arrays just have no transparent part.
+     */
+    readonly ranges: Uint32Array;
+    /** Total number of valid instances. */
+    readonly count: number;
+    /** Maximum number of instances (sizes the GPU buffers). */
+    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).
+ * "puff" is a soft, round sprite that always faces the camera and is always see-through: overlapping
+ * puffs blend into smoke, dust, steam and clouds. "flame" is the same sprite drawn additively: it adds
+ * light to what's behind it, so overlapping flames build up to a hot white core and stay bright over
+ * smoke (fire, sparks, explosions, magic, glows). Use them as a burst's `mesh`.
+ */
+export type Shape = 'cube' | 'sphere' | 'plane' | 'cylinder' | 'cone' | 'capsule' | 'torus' | 'roundedBox' | 'puff' | 'flame' | 'none';
+/** Mesh ids of the built-in shapes, as the core and renderer know them. */
+export declare const SHAPE_MESH: Record<Shape, number>;
+export type Camera = {
+    eye: [number, number, number];
+    target: [number, number, number];
+    /** Vertical field of view in radians (ignored when `ortho` is set). */
+    fov: number;
+    /** Orthographic: half the visible height in world units. Board and puzzle games look flat and tidy. */
+    ortho?: number;
+    /**
+     * Chase an entity: each frame the target moves toward it and the eye keeps `offset` from the target.
+     * `smoothing` is roughly the seconds it takes to catch up (0 = rigid, default 0.15).
+     */
+    follow?: {
+        target: Entity;
+        offset: Vec3;
+        smoothing?: number;
+    } | null;
+    /** Shake strength in world units (e.g. 0.3 for a hit). Fades out by itself. */
+    shake?: number;
+};
+export type Light = {
+    /** Direction *towards* the light. Need not be normalized. */
+    direction: [number, number, number];
+    /** 0..1 ambient term. */
+    ambient: number;
+    /** Cast shadows (one directional shadow map centred on the camera target). Default true. */
+    shadows?: boolean;
+    /** Half-size in world units of the shadowed area around the camera target. Default 30. */
+    shadowExtent?: number;
+    /**
+     * Color and brightness of the light, multiplying both sun and ambient: e.g. [0.35, 0.38, 0.6] for
+     * moonlight, or a CSS color. Glowing colors (channels above 1) aren't affected. Alpha, if given, is
+     * ignored. Default [1, 1, 1].
+     */
+    color?: ColorInput;
+};