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

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

@@ -0,0 +1,209 @@
+import type { Texture } from '../assets/texture';
+export type DrawingBrush = 'NORMAL' | 'MARKER' | 'PENCIL' | 'CALLIGRAPHY' | 'WATERCOLOR' | 'NEON' | 'CRAYON' | 'SPRINKLING';
+export type DrawingShape = 'line' | 'arrow' | 'rectangle' | 'square' | 'rounded-rectangle' | 'circle' | 'ellipse' | 'triangle' | 'right-triangle' | 'diamond' | 'pentagon' | 'hexagon' | 'octagon' | 'star' | 'heart' | 'trapezoid' | 'parallelogram' | 'cross' | 'speech-bubble' | 'cloud';
+export interface DrawingShapePreview {
+    kind: DrawingShape;
+    name: string;
+    path: string;
+    filledPath: string;
+    canFill: boolean;
+}
+export type DrawingTool = 'brush' | 'fill' | 'picker' | DrawingShape;
+export type DrawingSymmetry = 'none' | 'vertical' | 'horizontal' | 'both';
+export interface DrawingLayer {
+    id: number;
+    name: string;
+    visible: boolean;
+    locked: boolean;
+    opacity: number;
+}
+export interface DrawingProject {
+    version: 2;
+    width: number;
+    height: number;
+    activeLayer: number;
+    layers: DrawingLayer[];
+    paths: SavedDrawingPath[];
+}
+export interface DrawingBrushOptions {
+    brushType: DrawingBrush;
+    color: string;
+    width: number;
+    opacity: number;
+    isEraser?: boolean;
+    pressure?: boolean;
+    smoothing?: number;
+    tool?: DrawingTool;
+    symmetry?: DrawingSymmetry;
+    filled?: boolean;
+    tolerance?: number;
+}
+export interface DrawingState {
+    controls: DrawingControls;
+    count: number;
+    canUndo: boolean;
+    canRedo: boolean;
+    revision: number;
+    width: number;
+    height: number;
+    pixelWidth: number;
+    pixelHeight: number;
+    zoom: number;
+    layers: DrawingLayer[];
+    activeLayer: number;
+    editable: boolean;
+    isDrawing: boolean;
+    tool: DrawingTool | null;
+    pickedColor: string | null;
+    error: string | null;
+}
+/** Native document settings; React may display this snapshot but never owns the tool state. */
+export interface DrawingControls {
+    tool: 'brush' | 'eraser' | 'move' | 'shape';
+    brushType: DrawingBrush;
+    color: string;
+    width: number;
+    opacity: number;
+    shape: DrawingShape;
+    filled: boolean;
+    pressure: boolean;
+    smoothing: number;
+}
+export interface DrawingSnapshot {
+    base64: string;
+    width: number;
+    height: number;
+}
+/** A committed stroke's geometry in document coordinates, for colliders, tracing and scoring. */
+export interface DrawingStroke {
+    /** Position in the document's stroke list; pass `index + 1` as `from` to read only newer strokes. */
+    index: number;
+    layerId: number;
+    color: string;
+    /** Painted width in document units, including the brush's width factor. */
+    width: number;
+    opacity: number;
+    isEraser: boolean;
+    brushType: string;
+    /** `fill`: `outline` is the painted shape. `stroke`: `outline` is the centreline. */
+    style: 'fill' | 'stroke';
+    /** [x, y, width, height] of the painted outline. */
+    bounds: [number, number, number, number];
+    /**
+     * Smoothed gesture centrelines as flat [x0, y0, x1, y1, ...] arrays: one per symmetry copy, for
+     * brush strokes drawn this session. Empty for loaded strokes, fills and shapes; use `outline`.
+     */
+    lines: number[][];
+    /** Flattened contours of the painted path as flat [x0, y0, ...] arrays. */
+    outline: {
+        points: number[];
+        closed: boolean;
+    }[];
+}
+/** The composited ink under a document point (straight alpha; transparent paper is alpha 0). */
+export interface DrawingSample {
+    color: string;
+    alpha: number;
+}
+export interface DrawingCoverageOptions {
+    /** Document rectangle to measure; defaults to the whole paper. */
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    /** Minimum ink alpha (0..1) that counts as painted. Default 0.5. */
+    minAlpha?: number;
+}
+export interface SavedDrawingPath {
+    path: string;
+    color: string;
+    width: number | string;
+    opacity?: number;
+    style?: 'fill' | 'stroke';
+    isEraser?: boolean;
+    brushType?: string;
+    touchPoints?: unknown[] | null;
+    [key: string]: unknown;
+}
+/**
+ * A native art document. Touches and live rendering never subscribe to React state.
+ *
+ * Games use the same document without `DrawingCanvas`: bind `texture()` to any entity, feed
+ * `input(..., 'document')` from the game's own touches or world hits, and read `strokes()`,
+ * `sample()` and `coverage()` for colliders and scoring. Create one document per game screen and
+ * `clear()` it on replay; `dispose()` it on unmount (this also frees its texture).
+ */
+export declare class DrawingDocument {
+    readonly id: number;
+    readonly width: number;
+    readonly height: number;
+    private disposed;
+    private boundTexture;
+    constructor(width: number, height: number, pixelRatio?: number);
+    get isDisposed(): boolean;
+    private call;
+    setBrush(options: DrawingBrushOptions): null;
+    updateControls(options: Partial<DrawingControls> & {
+        reset?: boolean;
+    }): DrawingState;
+    /** Atomic import: errors leave the current artwork intact, including unknown legacy metadata. */
+    load(paths: string | readonly SavedDrawingPath[] | DrawingProject): DrawingState;
+    get state(): DrawingState;
+    exportPaths(): string;
+    /** Rust checks idleness and revision atomically; autosave never finishes a live stroke. */
+    setEditingEnabled(enabled: boolean): DrawingState;
+    captureDraft(afterRevision?: number): {
+        project: string;
+        revision: number;
+        width: number;
+        height: number;
+    } | null;
+    /** Browser change stream. Native canvases deliver changes directly from their display clock. */
+    readChange(): DrawingState | null;
+    exportSVG(): string;
+    /** Full editable project: preserves layer order, visibility, locks and original SVG metadata. */
+    exportProject(): string;
+    layer(action: 'add' | 'duplicate' | 'select' | 'update' | 'move' | 'delete' | 'clear', options?: Partial<DrawingLayer> & {
+        index?: number;
+    }): DrawingState;
+    fill(x: number, y: number, tolerance?: number): DrawingState;
+    shapeCatalog(): DrawingShapePreview[];
+    addShape(kind: DrawingShape, x: number, y: number, endX: number, endY: number, filled?: boolean): DrawingState;
+    snapshot(): DrawingSnapshot;
+    undo(): DrawingState;
+    redo(): DrawingState;
+    clear(): DrawingState;
+    invalidateView(): DrawingState;
+    resetView(): DrawingState;
+    /** Fit the full artwork or fill the viewport width without changing saved dimensions. */
+    setViewFit(fit: 'contain' | 'width'): DrawingState;
+    finish(): DrawingState;
+    cancel(): DrawingState;
+    /**
+     * Feeds one pointer sample: 0 begin, 1 move, 2 end, 3 cancel. `view` coordinates are relative to
+     * a `DrawingCanvas` and follow its zoom/pan (browser pointer sampling; native canvases feed
+     * touches straight into the Rust core). `document` coordinates skip the view mapping, for games
+     * that convert their own touches or world hits (e.g. a raycast's texture UV × document size).
+     */
+    input(phase: 0 | 1 | 2 | 3, x: number, y: number, pressure?: number, space?: 'view' | 'document'): void;
+    /**
+     * A live texture of the artwork (transparent paper, straight alpha), usable as any entity's
+     * `texture`. In-progress strokes appear immediately; only changed rows are uploaded each frame.
+     * Created once per document and freed by `dispose()`. Its pixels are not readable through
+     * texture APIs; use `sample()`, `coverage()` or `snapshot()`.
+     */
+    texture(): Texture;
+    /** Committed strokes from index `from`, flattened to `tolerance` document units (default 0.5). */
+    strokes(options?: {
+        from?: number;
+        tolerance?: number;
+    }): DrawingStroke[];
+    /** The ink under a document point, or null off the paper. Includes an in-progress stroke. */
+    sample(x: number, y: number): DrawingSample | null;
+    /** Fraction (0..1) of a document rectangle covered by ink, for colouring and scratch-off scoring. */
+    coverage(options?: DrawingCoverageOptions): number;
+    transform(dx: number, dy: number, scale?: number): DrawingState;
+    /** Browser presentation; iOS and Android use native display clocks with automatic suspension. */
+    present(width: number, height: number, background?: string, pixelRatio?: number): boolean;
+    dispose(): void;
+}

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

@@ -0,0 +1,11 @@
+import type { ViewStyle } from '../render/host';
+import type { DrawingDocument, DrawingState } from './DrawingDocument';
+export interface DrawingCanvasProps {
+    document: DrawingDocument;
+    mode?: 'draw' | 'move' | 'view';
+    background?: string;
+    active?: boolean;
+    onChange?: (state: DrawingState) => void;
+    onError?: (error: Error) => void;
+    style?: ViewStyle;
+}

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

@@ -0,0 +1,41 @@
+export { World, isEngineAvailable } from './world/World';
+export { quat, type MutableQuat } from './world/quat';
+export { effects, type DustOptions, type EffectOptions, type FlashOptions, type PopOptions } from './world/effects';
+export { Scoreboard, type ScoreboardHandlers } from './world/Scoreboard';
+export type { AnimateOptions, AnimateTarget, BodyType, Bounds, BurstOptions, CollisionInfo, ClipOptions, ScreenPlane, Color, Easing, Entity, EntityOptions, ImpactFeedback, Keyframe, PhysicsOptions, PickHit, Quat, RaycastHit, SpringOptions } from './world/types';
+export { GameView } from './render/GameView';
+export { warmUpEngine, getMeshIdLimit } from './render/meshes';
+export type { TransformBatch, TransformOptions } from './world/TransformBatch';
+export type { DragEvent, GameViewProps, GameViewStats, OverlayTouchPhase, PinchEvent, SwipeDirection } from './render/GameView';
+export type { RenderQuality, RenderQualitySetting } from './render/quality';
+export type { AssetSource } from './assets/source';
+export { loadModel } from './assets/model';
+export { clearAssetCache } from './assets/AssetCache';
+export { ProceduralCache, type ProceduralStorage } from './assets/ProceduralCache';
+export type { Model, ModelOptions, ModelClip, LoadedModel } from './assets/model';
+export { loadTexture } from './assets/texture';
+export { Solid, solidGeometry, createSolid, optimizeGeometry, createGeometryLods, getGeometryStats, deformGeometry } from './assets/modelling';
+export type { DisplacementOptions, SolidOptions, OptimizeOptions, GeometryStats } from './assets/modelling';
+export { loft, block, ellipsoid, smoothCurve } from './assets/loft';
+export type { LoftSection, LoftOptions } from './assets/loft';
+export { parametricSurface } from './assets/surface';
+export type { ParametricSurfaceOptions } from './assets/surface';
+export type { Texture } from './assets/texture';
+export { createShape, extrude, lathe, merge, Path, recolor, shapeGeometry, smoothNormals, tube } from './assets/shape';
+export type { ExtrudeOptions, FaceColor, Geometry, LatheOptions, GeometryPart, ShapeOptions, SurfaceColor, SurfacePoint, TubeOptions } from './assets/shape';
+export { loadFont, measureText } from './assets/font';
+export type { Font, FontOptions, TextAlign, TextLayout } from './assets/font';
+export { audio } from './media/audio';
+export type { AudioPlayOptions, Sound, SoundBank, SoundSource, Voice } from './media/audio';
+export { haptics } from './media/haptics';
+export type { HapticTap } from './media/haptics';
+export { Joystick, useJoystick } from './input/Joystick';
+export type { JoystickState, JoystickProps } from './input/Joystick';
+export { createKeyboardInput } from './input/keyboard';
+export type { KeyboardInputMode, KeyboardInputOptions } from './input/keyboard';
+export { MAX_MESHES } from './types';
+export type { Camera, Light, RenderSource, Shape, Vec3 } from './types';
+export { DrawingDocument } from './drawing/DrawingDocument';
+export type { DrawingBrush, DrawingBrushOptions, DrawingControls, DrawingState, DrawingSnapshot, SavedDrawingPath, DrawingTool, DrawingShape, DrawingShapePreview, DrawingSymmetry, DrawingLayer, DrawingProject, DrawingStroke, DrawingSample, DrawingCoverageOptions } from './drawing/DrawingDocument';
+export { DrawingCanvas } from './drawing/DrawingCanvas';
+export type { DrawingCanvasProps } from './drawing/DrawingCanvas';

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

@@ -0,0 +1,12 @@
+import { type CSSProperties } from 'react';
+export type JoystickState = {
+    x: number;
+    y: number;
+};
+export declare function useJoystick(): JoystickState;
+export interface JoystickProps {
+    state: JoystickState;
+    size?: number;
+    style?: CSSProperties;
+}
+export declare function Joystick({ state, size, style }: JoystickProps): import("react").JSX.Element;

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

@@ -0,0 +1,16 @@
+export type KeyboardInputMode = 'pointer' | 'drag' | 'swipe';
+export declare const PRIMARY_INPUT_EVENT = "nayan-engine-primary-action";
+export interface KeyboardInputOptions {
+    mode?: KeyboardInputMode;
+    enabled?: () => boolean;
+    /** Optional primary control, in CSS pixels relative to the input surface. */
+    primary?: () => {
+        x: number;
+        y: number;
+    };
+}
+/** Browser keyboard adapter. Reuses pointer input, including engine gestures and raw contact surfaces. */
+export declare function createKeyboardInput(surface: HTMLElement, options?: KeyboardInputOptions): {
+    cancel: () => void;
+    dispose(): void;
+};

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

@@ -0,0 +1,45 @@
+import type { AssetSource } from '../assets/source';
+/** A decoded sound in the core's mixer. */
+export type Sound = number & {
+    readonly __sound: unique symbol;
+};
+/** A playing instance of a sound (for `audio.stop`). */
+export type Voice = number & {
+    readonly __voice: unique symbol;
+};
+export type AudioPlayOptions = {
+    /** 0..2. Default 1. */
+    volume?: number;
+    /** -1 left .. 1 right. Default 0. */
+    pan?: number;
+    /** Playback speed (also shifts pitch). Default 1. */
+    pitch?: number;
+    /** Repeat until stopped (music, engines, ambience). */
+    loop?: boolean;
+};
+/** A `require("./file.wav")` asset, or a URI. WAV, PCM or float, mono or stereo. */
+export type SoundSource = AssetSource;
+/** Named sounds. Plays are ignored until `ready` resolves (usually a few milliseconds). */
+export declare class SoundBank<K extends string> {
+    /** Resolves when every sound has loaded (failures are logged and skipped). */
+    readonly ready: Promise<void>;
+    private readonly ids;
+    constructor(sources: Record<K, SoundSource>);
+    /** The sound, once loaded (e.g. for an entity's `impact.sound`). */
+    get(name: K): Sound | undefined;
+    play(name: K, options?: AudioPlayOptions): Voice | null;
+}
+export declare const audio: {
+    /** Initializes the engine and loads named sounds into its mixer. Each asset decodes once per session. */
+    load<K extends string>(sources: Record<K, SoundSource>): SoundBank<K>;
+    /** Plays a sound (low latency: mixed in Rust on the audio thread). Returns null if it couldn't play. */
+    play(sound: Sound, { volume: v, pan, pitch, loop }?: AudioPlayOptions): Voice | null;
+    stop(voice: Voice | null | undefined): void;
+    muted: boolean;
+    /** The inverse of `muted`, matching `haptics.enabled` (e.g. `audio.enabled = settings.enableSounds`). */
+    enabled: boolean;
+    /** Master volume, 0..2. */
+    volume: number;
+    /** True once the device's audio output is running. */
+    readonly running: boolean;
+};

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

@@ -0,0 +1,21 @@
+export type HapticTap = {
+    /** Seconds from now. */
+    time: number;
+    /** 0..1 */
+    intensity: number;
+    /** 0 (dull thud) .. 1 (crisp click). */
+    sharpness: number;
+};
+export declare const haptics: {
+    /** Set false to silence all haptics (e.g. a settings toggle). */
+    enabled: boolean;
+    /** True if the device has a haptic actuator (false on simulators). */
+    readonly supported: boolean;
+    /** A single tap. Rapid repeats (< 35 ms apart) are dropped so collisions don't buzz. */
+    impact(intensity?: number, sharpness?: number): void;
+    /** A light, crisp tick for UI selection. */
+    selection(): void;
+    notify(type: "success" | "warning" | "error"): void;
+    /** Any sequence of taps. */
+    play(taps: readonly HapticTap[]): void;
+};

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

@@ -0,0 +1,3 @@
+import type { WasmCore } from '../native/BrowserEngine';
+/** The Rust mixer remains the source of all audio, including native collision feedback. */
+export declare function installAudioOutput(core: WasmCore): () => boolean;

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

@@ -0,0 +1,7 @@
+import type { EngineBridge } from './EngineBridge';
+/** Raw C exports are shared with the mobile JSI bridge. All pointers stay private here. */
+export interface WasmCore {
+    memory: WebAssembly.Memory;
+    [name: string]: unknown;
+}
+export declare function createBrowserEngine(core: WasmCore): EngineBridge;

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

@@ -0,0 +1,21 @@
+import type { Spec } from './spec/NativeNayanEngine';
+/** Geometry returned by the core without registering a renderable mesh. */
+export interface NativeGeometry {
+    vertices: ArrayBuffer;
+    indices: ArrayBuffer;
+}
+type BufferValue<T, Buffer> = T extends readonly number[] ? 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'>;
+/** 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]>;
+} & {
+    geometrySolid(recipe: string): NativeGeometry;
+    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];
+};
+export {};

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

@@ -0,0 +1,9 @@
+import type { EngineBridge } from './EngineBridge';
+export declare function prepareEngine(): Promise<void>;
+export declare function readSavedAsset(key: string): Promise<ArrayBuffer | null>;
+export declare function flushAssetStorage(): Promise<void>;
+export declare function clearedAssetStorage(): Promise<void>;
+export declare function attachCanvas(id: number, canvas: HTMLCanvasElement): Promise<void>;
+export declare function detachCanvas(id: number): void;
+declare const browser: EngineBridge;
+export default browser;

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

@@ -0,0 +1 @@
+export declare function prepareEngine(): Promise<void>;

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

@@ -0,0 +1,181 @@
+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;
+    /** 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;
+    /**
+     * 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;
+    /** 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;
+    /** [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;
+    /**
+     * 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;
+    /** 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;