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

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

@@ -0,0 +1,394 @@
+import type { MeshGeometry } from '../render/meshes.js';
+/** A node of a field graph. Plain numbers are constants wherever a field is expected. */
+export declare class FieldRef {
+    readonly id: number;
+    constructor(id: number);
+}
+export type FieldInput = FieldRef | number;
+/** A 2D primitive in a field's (x, z) plane; `offset` is subtracted from its distance, `width` is its fade length. */
+export type FieldShape = {
+    kind: 'point';
+    x: number;
+    z: number;
+    offset?: number;
+    width?: number;
+} | {
+    kind: 'segment';
+    ax: number;
+    az: number;
+    bx: number;
+    bz: number;
+    offset?: number;
+    width?: number;
+} | {
+    kind: 'box';
+    x: number;
+    z: number;
+    halfX: number;
+    halfZ: number;
+    yaw?: number;
+    offset?: number;
+    width?: number;
+};
+type Node = {
+    op: string;
+} & Record<string, unknown>;
+/**
+ * Builds a field graph: generic math and geometry nodes evaluated by the native core. Shared nodes
+ * are computed once per sample point and `select` evaluates only the branch it takes.
+ *
+ * ```ts
+ * const f = new FieldGraph();
+ * const bank = f.sub(f.abs(f.sub(f.x, f.sines(f.x, f.z, 10, [[0, 0.035, 0, 11]]))), 5);
+ * f.output('bank', bank);
+ * ```
+ */
+export declare class FieldGraph {
+    private nodes;
+    private outputs;
+    private constants;
+    private inputs;
+    private node;
+    private ref;
+    private refs;
+    constant(value: number): FieldRef;
+    /** A named input: `x`/`z` (local frame) for terrain fields; u, v, row, col, i, count, r0… elsewhere. */
+    input(name: string): FieldRef;
+    get x(): FieldRef;
+    get z(): FieldRef;
+    add(a: FieldInput, b: FieldInput): FieldRef;
+    sub(a: FieldInput, b: FieldInput): FieldRef;
+    mul(a: FieldInput, b: FieldInput): FieldRef;
+    div(a: FieldInput, b: FieldInput): FieldRef;
+    /** a + b + c… left to right. */
+    sum(...values: FieldInput[]): FieldRef;
+    /** a · b · c… left to right. */
+    product(...values: FieldInput[]): FieldRef;
+    min(...args: FieldInput[]): FieldRef;
+    max(...args: FieldInput[]): FieldRef;
+    neg(a: FieldInput): FieldRef;
+    abs(a: FieldInput): FieldRef;
+    sqrt(a: FieldInput): FieldRef;
+    floor(a: FieldInput): FieldRef;
+    square(a: FieldInput): FieldRef;
+    sin(a: FieldInput): FieldRef;
+    cos(a: FieldInput): FieldRef;
+    exp(a: FieldInput): FieldRef;
+    /** `a` to the power `b`. */
+    pow(a: FieldInput, b: FieldInput): FieldRef;
+    /** `a − floor(a)`. */
+    fract(a: FieldInput): FieldRef;
+    /**
+     * Value noise in 0..1 on a unit lattice: the common sine-hash shader noise, smoothstep-blended.
+     * With `period`, it repeats every `period` cells in x (to wrap around a lathe without a seam).
+     */
+    noise(x: FieldInput, z: FieldInput, period?: number): FieldRef;
+    /** a + (b − a) · t, componentwise on numbers or fields. */
+    mix(a: FieldInput, b: FieldInput, t: FieldInput): FieldRef;
+    hypot(...args: FieldInput[]): FieldRef;
+    /** Hermite smoothstep of `a` clamped to 0..1. */
+    smooth(a: FieldInput): FieldRef;
+    clamp(a: FieldInput, lo: FieldInput, hi: FieldInput): FieldRef;
+    /** `le` where `test` <= 0, otherwise `gt` (only the chosen branch is evaluated). */
+    select(test: FieldInput, le: FieldInput, gt: FieldInput): FieldRef;
+    /** base + Σ amp · sin(fx·x + fz·z + phase), terms as [fx, fz, phase, amp]. */
+    sines(x: FieldInput, z: FieldInput, base: number, terms: readonly (readonly [number, number, number, number])[]): FieldRef;
+    /** Σ height · max(0, 1 − u² − v²)^power over oriented ellipses [x, z, height, radiusU, radiusV, yaw]. */
+    bumps(x: FieldInput, z: FieldInput, items: readonly (readonly [number, number, number, number, number, number])[], power?: number): FieldRef;
+    /** The smallest signed distance to the shapes (minus each one's offset); +∞ with none. */
+    distance(x: FieldInput, z: FieldInput, shapes: readonly FieldShape[]): FieldRef;
+    /** Π smoothstep((distance − offset) / width): 0 at the shapes, 1 beyond their fade. */
+    falloff(x: FieldInput, z: FieldInput, shapes: readonly FieldShape[]): FieldRef;
+    /** The largest depth inside any of the boxes (min of side clearances, minus offset); −∞ with none. */
+    depth(x: FieldInput, z: FieldInput, shapes: readonly FieldShape[]): FieldRef;
+    /** Names a field so recipes can refer to it. Returns the name. */
+    output(name: string, value: FieldInput): string;
+    toJSON(): {
+        nodes: Node[];
+        outputs: Record<string, number>;
+    };
+}
+type Inputs<K extends string> = {
+    readonly [P in K]: FieldRef;
+};
+type Color3 = readonly [FieldInput, FieldInput, FieldInput];
+/**
+ * A function of named inputs written as a field graph, for model options that would otherwise call
+ * a JS function per vertex: `lathe`/`tube`/`loft` colors and `lathe` displacement, `recolor`. Build
+ * one with `surfaceColor`, `faceColor`, `sectionColor` or `surfaceDisplacement`.
+ */
+export declare class FieldFunction {
+    readonly fields: FieldGraph;
+    readonly outputs: number;
+    constructor(fields: FieldGraph, outputs: number);
+    toJSON(): {
+        fields: FieldGraph;
+        out: string[];
+    };
+}
+/**
+ * A color of each surface point: `u`, `v` (texture coordinates; around and along a lathe or tube),
+ * position `x`, `y`, `z` and normal `nx`, `ny`, `nz`. Returns [r, g, b].
+ */
+export declare const surfaceColor: (build: (f: FieldGraph, p: Inputs<"u" | "v" | "x" | "y" | "z" | "nx" | "ny" | "nz">) => Color3) => FieldFunction;
+/** A color across a round end face: `r` from its center (0) to its rim (1), `angle` around it (radians). */
+export declare const faceColor: (build: (f: FieldGraph, p: Inputs<"r" | "angle">) => Color3) => FieldFunction;
+/** A color across a lathe's cut face: `r` from the axis (0) to the skin (1) at that height, and the height `y`. */
+export declare const sectionColor: (build: (f: FieldGraph, p: Inputs<"r" | "y">) => Color3) => FieldFunction;
+/** A lathe's displacement along its normal at (`u` around, `v` down the profile). */
+export declare const surfaceDisplacement: (build: (f: FieldGraph, p: Inputs<"u" | "v">) => FieldInput) => FieldFunction;
+type Three = readonly [string, string, string];
+export type MeshPart = {
+    kind: 'surface';
+    rows: number;
+    cols: number;
+    position: Three;
+    normal: Three;
+    uv: readonly [string, string];
+    color: Three;
+    double?: boolean;
+    flip?: boolean;
+} | {
+    kind: 'cards';
+    count: number;
+    seed: number;
+    randoms: number;
+    /** [cu, cv, texU, texV] per corner (3 or 4): center + right·cu + up·cv. */
+    corners: readonly (readonly [number, number, number, number])[];
+    center: Three;
+    right: Three;
+    up: Three;
+    normal: Three;
+    color: Three;
+    double?: boolean;
+};
+export interface MeshRecipe {
+    fields: FieldGraph;
+    parts: readonly MeshPart[];
+}
+export type Frame = 'local' | 'world';
+export interface TerrainRecipe {
+    /** Grid lines along both axes, ascending. */
+    axis: readonly number[];
+    height: string;
+    normalStep?: number;
+    uvSize?: readonly [number, number];
+    shade?: string;
+    tint?: readonly [number, number, number];
+    /** Tested in order: a point belongs to the first region whose field is <= 0. */
+    regions?: readonly {
+        field: string;
+        surface: number;
+        material: number;
+    }[];
+    fallback: {
+        surface: number;
+        material: number;
+    };
+    materials: number;
+}
+export type SolidRecipe = {
+    kind: 'box';
+    x: number;
+    z: number;
+    halfX: number;
+    halfZ: number;
+    yaw?: number;
+    bottom: number;
+    top: number;
+    frame?: Frame;
+} | {
+    kind: 'circle';
+    x: number;
+    z: number;
+    radius: number;
+    bottom: number;
+    top: number;
+    frame?: Frame;
+} | {
+    kind: 'hull';
+    template: number;
+    x: number;
+    y: number;
+    z: number;
+    scale: readonly [number, number, number];
+    yaw?: number;
+    frame?: Frame;
+};
+export type ScatterFilter = {
+    kind: 'field';
+    field: string;
+    min?: number;
+    max?: number;
+} | {
+    kind: 'walkable';
+    radius: number;
+} | {
+    kind: 'surface';
+    surfaces: readonly number[];
+} | {
+    kind: 'spawn';
+    minDistance: number;
+};
+export type ItemSolid = {
+    kind: 'none';
+} | {
+    kind: 'circle';
+    radius: string;
+    bottom: string;
+    top: string;
+} | {
+    kind: 'hull';
+    template: string;
+    scale: Three;
+    y: string;
+    yaw: string;
+};
+export interface ScatterLayer {
+    name: string;
+    count: number;
+    randoms?: number;
+    /** Layers with the same salt draw the same random values (paired scenery); by default each step has its own. */
+    salt?: number;
+    source?: 'none' | 'reachable' | {
+        anchors: readonly (readonly number[])[];
+    };
+    frame?: Frame;
+    x: string;
+    z: string;
+    filters?: readonly ScatterFilter[];
+    y: string;
+    attributes?: readonly string[];
+    solid?: {
+        variant?: string;
+        shapes: readonly ItemSolid[];
+    };
+}
+export type WorldStep = {
+    kind: 'spawn';
+    near: readonly [number, number];
+    rings: number;
+    samples: number;
+    radius: number;
+    surfaces?: readonly number[];
+} | ({
+    kind: 'scatter';
+} & ScatterLayer) | {
+    kind: 'reach';
+    cell: number;
+    steps: number;
+    radius: number;
+    extent: number;
+} | {
+    kind: 'pick';
+    groups: readonly {
+        name: string;
+        count: number;
+        spacing: number;
+        fromSpawn?: number;
+    }[];
+    attempts?: number;
+} | {
+    kind: 'overview';
+    size: number;
+    extent: number;
+};
+export interface WorldRecipe {
+    seed: number;
+    /** Turns the local frame (fields, platforms, local solids) into the world. */
+    rotation?: number;
+    fields: FieldGraph;
+    terrain: TerrainRecipe;
+    platforms?: readonly {
+        x: number;
+        z: number;
+        halfX: number;
+        halfZ: number;
+        y: number;
+        surface: number;
+    }[];
+    /** Mesh recipes whose convex hulls are solid templates (rendered rocks block exactly their outline). */
+    templates?: readonly MeshRecipe[];
+    solids?: readonly SolidRecipe[];
+    walk: {
+        boundary: number;
+        clearance: string;
+        footprint?: number;
+        step?: readonly [number, number];
+        height: number;
+        lift?: number;
+        cell?: number;
+    };
+    steps: readonly WorldStep[];
+}
+export interface WorldOptions {
+    /** Saves the world under this storage key, and restores one saved there from the same recipe. */
+    key?: string;
+    /** Also builds the terrain meshes (on the build's thread with `generateWorldAsync`). */
+    prepareTerrain?: boolean;
+}
+export interface Spot {
+    x: number;
+    z: number;
+}
+/** A generated world held by the native core; queries take world coordinates. */
+export declare class ProceduralWorld {
+    readonly handle: number;
+    readonly spawn: Spot;
+    /** True when it was restored from storage rather than generated. */
+    readonly restored: boolean;
+    readonly layers: Readonly<Record<string, {
+        stride: number;
+        count: number;
+    }>>;
+    picks: Record<string, Spot[]>;
+    private fields;
+    private disposed;
+    constructor(handle: number);
+    private get id();
+    /** A scatter layer's items: [x, y, z, ...attributes] per item (see `layers[name].stride`). */
+    layer(name: string): Float64Array;
+    /** Reachable cells as [x, z] pairs. */
+    reachable(): Float64Array;
+    /** The overview step's surface codes, row by row (0 outside the walk boundary). */
+    overview(): Uint8Array;
+    /** Re-picks the spots for run `run` (0 = as generated); false keeps the previous ones. */
+    pick(run: number): boolean;
+    /** The terrain mesh of `material` (built once; each material is handed over once). */
+    terrain(material: number): MeshGeometry;
+    ground(x: number, z: number): number;
+    surface(x: number, z: number): number;
+    /** The platform (recipe index) under a point, or -1. */
+    platformAt(x: number, z: number): number;
+    walkable(x: number, z: number, radius: number): boolean;
+    /** How far a walker of `radius` is from anything blocking it (negative when blocked). */
+    clearance(x: number, z: number, radius: number): number;
+    solidClearance(x: number, z: number, radius: number, bottom: number, top: number): number;
+    /** A named field of the recipe at a world point. */
+    field(name: string, x: number, z: number): number;
+    /** The ground's tilt as a quaternion [x, y, z, w], in a frame turned by `yaw`. */
+    tilt(x: number, z: number, yaw?: number): [number, number, number, number];
+    /** Whether a walker of `radius` could walk straight from a to b, ends at most `rise` apart in height. */
+    canSee(a: Spot, b: Spot, { radius, step, rise }?: {
+        radius?: number;
+        step?: number;
+        rise?: number;
+    }): boolean;
+    /** Sweeps a walker by (dx, dz), sliding along obstacles and other `bodies`; updates `point`. */
+    move(point: Spot, dx: number, dz: number, radius: number, bodies?: readonly (Spot & {
+        radius: number;
+    })[]): void;
+    dispose(): void;
+}
+/** Generates (or restores, see `WorldOptions.key`) a world on this thread. */
+export declare function generateWorld(recipe: WorldRecipe, options?: WorldOptions): ProceduralWorld;
+/** `generateWorld` on a background native thread (the web core builds at once). */
+export declare function generateWorldAsync(recipe: WorldRecipe, options?: WorldOptions): Promise<ProceduralWorld>;
+/** Whether a world was saved under `key` (cheap: doesn't read the world). */
+export declare function isWorldKept(key: string): boolean;
+/** Builds a procedural mesh (parametric surfaces and seeded cards) in the native core. */
+export declare function generateMesh(recipe: MeshRecipe): MeshGeometry;
+/** Recolors geometry in place (and returns it) by a `surfaceColor`, in the native core. */
+export declare function paintGeometry<G extends MeshGeometry>(geometry: G, color: FieldFunction): G;
+export {};
+//# sourceMappingURL=procedural.d.ts.map

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

@@ -3,6 +3,7 @@ import { type Shape, type Vec3 } from '../types.js';
 import type { Color, Quat } from '../world/types.js';
 import { type Model } from './model.js';
 import type { OptimizeOptions } from './modelling.js';
+import { FieldFunction } from './procedural.js';
 type P2 = [number, number];
 /**
  * A 2D outline, built like an SVG path: x right, y down. Solids made from it
@@ -87,10 +88,13 @@ export type SurfacePoint = {
     position: Vec3;
     normal: Vec3;
 };
-/** A flat color, or one per point of the surface: blushes, stripes, speckles, spots. */
-export type SurfaceColor = Color | ((p: SurfacePoint) => Color);
-/** A flat color, or one per point of a round face: `r` from its center (0) to its rim (1), `angle` around it. */
-export type FaceColor = Color | ((r: number, angle: number) => Color);
+/**
+ * A flat color, or one per point of the surface: blushes, stripes, speckles, spots. Prefer a
+ * `surfaceColor` field function (evaluated by the native core) to a JS function for detailed models.
+ */
+export type SurfaceColor = Color | ((p: SurfacePoint) => Color) | FieldFunction;
+/** A flat color, or one per point of a round face (`faceColor`): `r` from its center (0) to its rim (1), `angle` around it. */
+export type FaceColor = Color | ((r: number, angle: number) => Color) | FieldFunction;
 export type LatheOptions = {
     /** Steps around the axis. Default 32. */
     segments?: number;
@@ -103,7 +107,7 @@ export type LatheOptions = {
      * ribs, ridges, bumps. Normals are recomputed so the bumps catch the light. Make it repeat in u
      * (equal at u = 0 and 1) to avoid a seam.
      */
-    displace?: (u: number, v: number) => number;
+    displace?: ((u: number, v: number) => number) | FieldFunction;
     /** Color of the flat ends where the profile stops away from the axis (the face of a fruit cut across). Default `color`. */
     capColor?: FaceColor;
     /** Rings across each end cap, for patterned `capColor`. Default 1, or 12 for a function. */
@@ -112,7 +116,7 @@ export type LatheOptions = {
      * Color of the faces where a partial sweep is cut open (the flesh of a fruit cut through its core).
      * As a function: `r` from the axis (0) to the skin (1) at that height, and the height `y`. Default `color`.
      */
-    cutColor?: Color | ((r: number, y: number) => Color);
+    cutColor?: Color | ((r: number, y: number) => Color) | FieldFunction;
     /** Steps from the axis to the skin across each cut face, for a detailed `cutColor`. Default 12 for a function. */
     cutSteps?: number;
 };
@@ -120,7 +124,9 @@ export type LatheOptions = {
  * Recolors geometry point by point (in place, and returned): two-tone leaves, painted tips, stripes on
  * an extrusion. `u` and `v` are the texture coordinates there.
  */
-export declare function recolor(geometry: Geometry, color: (p: SurfacePoint) => Color): Geometry;
+export declare function recolor(geometry: Geometry, color: ((p: SurfacePoint) => Color) | FieldFunction): Geometry;
+/** Builds a sweep (lathe, tube or loft) part in the native core. */
+export declare function nativeSweep(part: Record<string, unknown>): Geometry;
 /**
  * Recomputes corner-angle-weighted normals in place, welding UV seams and poles at 1e-5 units.
  * Uses Rust when available. Call on a sculpted surface before merging caps or other hard edges:

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

@@ -1,3 +1,5 @@
+import type { Light } from '../types.js';
+import { type ColorInput } from '../world/color.js';
 import type { AssetSource } from './source';
 /** A loaded image. Pass it as an entity's `texture`. */
 export type Texture = {
@@ -27,4 +29,65 @@ export declare function textureImage(id: number): TextureImage;
  * (it shares the geometry, colliders and picking of the original).
  */
 export declare function texturedMesh(mesh: number, texture: Texture): number;
+export type BakeOptions = {
+    /** The picture's width and height in pixels: about the size it's shown at (textures have no mipmaps). */
+    size: number;
+    /** The scene's light, as passed to `GameView`: the picture is shaded as the model would be. */
+    light: Light;
+    /** The scene's background, which glossy models reflect. Default black. */
+    background?: ColorInput;
+    /** Glossiness 0..1. Default: the model's own (its `createShape` shine). */
+    shine?: number;
+    /** Samples per pixel along each side, for smooth edges. Default 4. */
+    supersample?: number;
+    /** Empty margin around the model, as a fraction of its larger side. Default 0.04. */
+    padding?: number;
+    /**
+     * Draw several models together (a tile and the fruit on it) instead of `model` alone: each scaled
+     * then moved (no rotation), tinted and glossy as an entity would be.
+     */
+    parts?: readonly BakePart[];
+    /** The square of x/y to draw, instead of one around the models (with `padding`). */
+    frame?: {
+        center: [x: number, y: number];
+        extent: number;
+    };
+    /**
+     * Keep the picture in the engine's cache under this key (a `ProceduralCache.storageKey`, so app
+     * updates rebake it), and restore it from there: check `isBakeKept(key)` to skip building the models.
+     */
+    key?: string;
+};
+/** One model in a bake. */
+export type BakePart = {
+    model: {
+        readonly id: number;
+    } | number;
+    position?: readonly [number, number, number];
+    scale?: number | readonly [number, number, number];
+    color?: ColorInput;
+    /** Glossiness 0..1. Default: the model's own. */
+    shine?: number;
+};
+/** A model's baked picture: its texture, and the square of the model's x/y it covers. */
+export type BakedModel = {
+    texture: Texture;
+    /** The square's centre, in model units. */
+    center: [x: number, y: number];
+    /** Half the square's side, in model units. */
+    extent: number;
+};
+/**
+ * Draws a model once, in the native core, into an anti-aliased picture with a transparent
+ * background: seen from +z (orthographic), shaded as the renderer shades it under `light`. Show it
+ * instead of the model where it only ever faces the camera (icons, tiles, cards): on the built-in
+ * `"plane"` turned to face +z, scaled to `2 * extent`, under a `frontLight` (which shows camera-facing
+ * surfaces at exactly their color), with an alpha just below 1 so its soft edges blend. One quad
+ * then draws what took thousands of triangles, with smooth edges at every quality level.
+ */
+export declare function bakeModel(model: {
+    readonly id: number;
+} | number | null, options: BakeOptions): BakedModel;
+/** Whether a picture was kept under `key` by `bakeModel` (so it can be restored without its models). */
+export declare function isBakeKept(key: string): boolean;
 //# sourceMappingURL=texture.d.ts.map

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

@@ -16,20 +16,26 @@ export { loadModel } from './assets/model.js';
 export { clearAssetCache } from './assets/AssetCache.js';
 export { ProceduralCache, type ProceduralStorage } from './assets/ProceduralCache.js';
 export type { Model, ModelOptions, ModelClip, LoadedModel } from './assets/model.js';
-export { loadTexture } from './assets/texture.js';
+export { bakeModel, isBakeKept, loadTexture } from './assets/texture.js';
 export { Solid, solidGeometry, createSolid, optimizeGeometry, createGeometryLods, getGeometryStats, deformGeometry } from './assets/modelling.js';
 export type { DisplacementOptions, SolidOptions, OptimizeOptions, GeometryStats } from './assets/modelling.js';
 export { loft, block, ellipsoid, smoothCurve } from './assets/loft.js';
 export type { LoftSection, LoftOptions } from './assets/loft.js';
 export { parametricSurface } from './assets/surface.js';
+export { faceColor, FieldFunction, FieldGraph, FieldRef, generateMesh, generateWorld, generateWorldAsync, isWorldKept, ProceduralWorld, sectionColor, surfaceColor, surfaceDisplacement } from './assets/procedural.js';
+export type { FieldInput, FieldShape, ItemSolid, MeshPart, MeshRecipe, ScatterFilter, ScatterLayer, SolidRecipe, Spot, TerrainRecipe, WorldOptions, WorldRecipe, WorldStep } from './assets/procedural.js';
 export type { ParametricSurfaceOptions } from './assets/surface.js';
-export type { Texture } from './assets/texture.js';
+export type { BakedModel, BakeOptions, BakePart, Texture } from './assets/texture.js';
 export { createShape, extrude, lathe, merge, Path, recolor, shapeGeometry, smoothNormals, tube } from './assets/shape.js';
 export type { ExtrudeOptions, FaceColor, Geometry, LatheOptions, GeometryPart, ShapeOptions, SurfaceColor, SurfacePoint, TubeOptions } from './assets/shape.js';
 export { loadFont, measureText } from './assets/font.js';
 export type { Font, FontOptions, TextAlign, TextLayout } from './assets/font.js';
 export { audio } from './media/audio.js';
 export type { AudioPlayOptions, Sound, SoundBank, SoundSource, Voice } from './media/audio.js';
+export { speech } from './media/speech.js';
+export type { SpeechOptions, SpeechVoice } from './media/speech.js';
+export { microphone } from './media/microphone.js';
+export type { MicrophoneOptions, MicrophonePermission, MicrophoneState, Recording, TakeOptions } from './media/microphone.js';
 export { haptics } from './media/haptics.js';
 export type { HapticTap } from './media/haptics.js';
 export { Joystick, useJoystick } from './input/Joystick';

package/lib/typescript/src/media/audio.d.ts

@@ -35,6 +35,19 @@ export declare const audio: {
     /** 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;
+    /**
+     * Frees a sound's samples, for sounds made at runtime (a `microphone.take` recording, once played).
+     * Its id then plays nothing; voices already playing it finish first. Don't release a bank's sounds.
+     */
+    release(sound: Sound | null | undefined): void;
+    /** A sound's length in seconds (0 if unknown or released). */
+    duration(sound: Sound): number;
+    /**
+     * A sound's loudness (RMS, 0..1) over time, one value per `1 / perSecond` seconds from its start:
+     * drive a talking mouth, a bobbing body or a meter from it while the sound plays (at `pitch` p,
+     * value i plays at i / (perSecond * p) seconds).
+     */
+    levels(sound: Sound, perSecond?: number): Float32Array;
     muted: boolean;
     /** The inverse of `muted`, matching `haptics.enabled` (e.g. `audio.enabled = settings.enableSounds`). */
     enabled: boolean;

package/lib/typescript/src/media/input.web.d.ts

@@ -0,0 +1,4 @@
+import type { WasmCore } from '../native/BrowserEngine.js';
+import type { EngineBridge } from '../native/EngineBridge.js';
+export declare function installMicrophoneInput(core: WasmCore, bridge: EngineBridge): void;
+//# sourceMappingURL=input.web.d.ts.map

package/lib/typescript/src/media/microphone.d.ts

@@ -0,0 +1,51 @@
+import type { Sound } from './audio.js';
+export type MicrophoneState = 'off' | 'starting' | 'listening' | 'failed';
+export type MicrophonePermission = 'granted' | 'undetermined' | 'denied';
+/** What `microphone.take` returns: a sound to play, how long it lasts and its loudness over time. */
+export type Recording = {
+    sound: Sound;
+    /** Seconds at pitch 1. */
+    duration: number;
+    /** RMS loudness, `levelsPerSecond` values a second (see `audio.levels`). */
+    levels: Float32Array;
+    levelsPerSecond: number;
+};
+export type MicrophoneOptions = {
+    /** Seconds of input kept (0.5..30). Default 10. */
+    maxSeconds?: number;
+};
+export type TakeOptions = {
+    /** Leave out the last `skipEnd` seconds (the silence after someone stops talking). Default 0. */
+    skipEnd?: number;
+    /** Loudness values per second in `levels`. Default 30. */
+    levelsPerSecond?: number;
+};
+export declare const microphone: {
+    /** Whether this engine build can record (false on older app builds and without a native module). */
+    readonly supported: boolean;
+    /** Whether the app may record. On Android, 'undetermined' also covers a denial (it can't tell). */
+    readonly permission: MicrophonePermission;
+    /** Shows the system prompt the first time (answering at once after that); true if recording is allowed. */
+    requestPermission(): Promise<boolean>;
+    /** Starts listening (asynchronously: see `state`). Ask for the permission first. */
+    start({ maxSeconds }?: MicrophoneOptions): boolean;
+    /** Stops listening and releases the microphone (its system indicator turns off); forgets what was heard. */
+    stop(): void;
+    /** 'failed' when there's no microphone, no permission or the input couldn't open. */
+    readonly state: MicrophoneState;
+    /**
+     * How loud the input is now: 0 at -60 dBFS or quieter, 1 at full scale; speech close to a phone
+     * is usually 0.4..0.8, a quiet room under 0.3. Rises at once and falls back over ~0.15 s. Cheap
+     * enough to read every frame.
+     */
+    readonly level: number;
+    /** Seconds of input held (up to `maxSeconds`), since starting or the last `take`. */
+    readonly held: number;
+    /**
+     * The last `seconds` of input (ending `skipEnd` seconds ago) as a new Sound, and forgets
+     * everything heard so far so the next take starts fresh. Null if nothing was heard. Release the
+     * sound with `audio.release` once it has played: each take holds its samples until then.
+     */
+    take(seconds?: number, { skipEnd, levelsPerSecond }?: TakeOptions): Recording | null;
+};
+//# sourceMappingURL=microphone.d.ts.map

package/lib/typescript/src/media/speech.d.ts

@@ -0,0 +1,38 @@
+export type SpeechOptions = {
+    /** BCP 47 language tag, such as en-US or hi-IN. Defaults to the system language. */
+    language?: string;
+    /** Identifier returned by getAvailableVoicesAsync. */
+    voice?: string;
+    /** Speed relative to the platform default, 0.1..2. Default 1. */
+    rate?: number;
+    /** Pitch multiplier, 0.5..2. Default 1. */
+    pitch?: number;
+    /** Loudness, 0..1. Default 1. */
+    volume?: number;
+};
+export type SpeechVoice = {
+    identifier: string;
+    name: string;
+    language: string;
+    quality: 'Default' | 'Enhanced';
+};
+/** System text-to-speech. Independent of the engine mixer, microphone and asset loading. */
+export declare const speech: {
+    /** API availability; installed voices and Android TTS initialization may still fail. */
+    readonly supported: boolean;
+    /**
+     * Queues text using the system synthesizer. Resolves when queued, not when speech finishes.
+     * No audio files are created. Call stop on leaving a screen to cancel its queued speech.
+     */
+    speak(text: string, options?: SpeechOptions): Promise<void>;
+    /** Stops current speech and clears the entire speech queue. */
+    stop(): Promise<void>;
+    /** iOS and web only; rejects on Android, which has no system pause API. */
+    pause(): Promise<void>;
+    /** iOS and web only; rejects on Android. */
+    resume(): Promise<void>;
+    /** Includes speech paused on iOS/web. */
+    isSpeakingAsync(): Promise<boolean>;
+    getAvailableVoicesAsync(): Promise<SpeechVoice[]>;
+};
+//# sourceMappingURL=speech.d.ts.map

package/lib/typescript/src/media/speechPlatform.d.ts

@@ -0,0 +1,5 @@
+export declare const speechPlatform: {
+    readonly supported: boolean;
+    request(command: string): Promise<string>;
+};
+//# sourceMappingURL=speechPlatform.d.ts.map