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

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

@@ -0,0 +1,6 @@
+/** Share concurrent requests across loader variants; failed requests can always be retried. */
+export declare function assetBytes(key: string, load: () => Promise<ArrayBuffer>): Promise<ArrayBuffer>;
+/** A decoder rejected the payload: a later load must fetch fresh bytes, not replay bad data. */
+export declare function forgetAssetBytes(key: string | undefined): void;
+/** Clearing disk must also prevent an earlier request from retaining its old bytes. */
+export declare function clearAssetBytes(): void;

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

@@ -0,0 +1,8 @@
+/**
+ * Explicitly removes the engine's saved geometry and original model/texture/font/audio files.
+ * Also clears temporary download bytes. Existing worlds and loaded handles remain usable;
+ * registrations are session resources and will be rebuilt/reloaded on a future app launch.
+ * Custom ProceduralStorage adapters belong to their host and are not cleared by this function.
+ * Rejects if storage cannot be cleared, allowing a settings screen to report the failure.
+ */
+export declare function clearAssetCache(): Promise<void>;

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

@@ -0,0 +1,10 @@
+import type { EngineBridge } from '../native/EngineBridge';
+import { type AssetSource } from './source';
+/** Shared session handles; source-byte persistence stays in AssetBytesCache and Rust. */
+export declare class AssetLoader<T> {
+    private readonly name;
+    private readonly loads;
+    constructor(name: string);
+    load(source: AssetSource, decode: (native: EngineBridge, bytes: ArrayBuffer) => T, variant?: readonly (string | number | boolean)[]): Promise<T>;
+    private error;
+}

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

@@ -0,0 +1,2 @@
+export declare const cacheGeneration: () => number;
+export declare const advanceCacheGeneration: () => number;

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

@@ -0,0 +1,19 @@
+export declare class IndexedDbCache {
+    private readonly database;
+    private tail;
+    private pending;
+    private generation;
+    private clearOperation;
+    private constructor();
+    static open(): Promise<IndexedDbCache>;
+    private enqueue;
+    /** The Uint8Array is an owned copy made by Rust, never a view into growable WASM memory. */
+    write(name: string, bytes: Uint8Array, geometry: boolean): Promise<void>;
+    read(name: string): Promise<Uint8Array | undefined>;
+    remove(name: string): Promise<void>;
+    clear(): Promise<void>;
+    flush(): Promise<void>;
+    cleared(): Promise<void>;
+    /** Read recent geometry only. Large source files remain in IndexedDB until requested by a loader. */
+    warm(canFit: (size: number) => boolean, restore: (name: string, bytes: Uint8Array) => boolean): Promise<void>;
+}

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

@@ -0,0 +1,32 @@
+/** Optional storage override. The engine selects a best-effort platform cache by default. */
+export interface ProceduralStorage {
+    read(key: string): Uint8Array | null;
+    write(key: string, bytes: Uint8Array): void | Promise<void>;
+}
+/**
+ * Persists the output of a deterministic model factory, including nested model arrays/objects.
+ * Hits register saved vertices directly: no procedural tessellation, painting or optimization.
+ * Imported/skinned/textured models are intentionally excluded; their own loaders retain their rigs.
+ */
+export declare class ProceduralCache {
+    readonly revision: string;
+    private storage;
+    private memory;
+    private hits;
+    private builds;
+    private invalid;
+    private failures;
+    private writes;
+    constructor(revision: string, storage?: ProceduralStorage | undefined);
+    get stats(): {
+        hits: number;
+        builds: number;
+        invalid: number;
+        failures: number;
+        pendingWrites: number;
+    };
+    flush(): Promise<void>;
+    get<T>(key: string, build: () => T): T;
+    private encode;
+    private restore;
+}

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

@@ -0,0 +1,52 @@
+import type { AssetSource } from './source';
+/** Printable ASCII plus common arithmetic and typography, prewarmed for ordinary labels. */
+export declare const DEFAULT_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~\u00D7\u00F7\u00B1\u2212\u00B0\u00B7\u2022\u2013\u2014\u2026\u2018\u2019\u201C\u201D";
+export type FontOptions = {
+    /** How deep letters are extruded, as a fraction of the font size. 0 = flat. Default 0.2. */
+    depth?: number;
+    /** Characters to prewarm (space and ? are always included). Other font-supported characters load
+     * once when text is measured or laid out. Fewer = faster startup and fewer unused meshes. Default: DEFAULT_CHARS. */
+    chars?: string;
+    /** Weight (e.g. 400, 600) for a variable font, such as the device's system font. Default: the font's own. */
+    weight?: number;
+};
+type Glyph = {
+    mesh: number;
+    advance: number;
+};
+/** A loaded font. Use it on an entity with `text`: `{ text: "2048", font }`. */
+export type Font = {
+    readonly id: number;
+    /** Height of capital letters at scale 1. */
+    readonly capHeight: number;
+    /** Cached mesh (-1 = nothing drawn, e.g. space) and advance per character. Grows as text is used. */
+    readonly glyphs: ReadonlyMap<string, Glyph>;
+};
+/**
+ * Initializes the engine automatically. Loads a TrueType / OpenType font (.ttf / .otf) for 3D text. The source/depth/weight are cached independently of the requested prewarm characters. Letters are real meshes: lit, shadowed,
+ * and every copy of a letter on screen is drawn in one call. At scale 1, letters are 1 unit tall (em).
+ * Additional Unicode glyphs are built on demand from the same font and cached. The font must contain
+ * an outline for the character; missing characters still use ?, including unsupported emoji.
+ *
+ * ```ts
+ * const font = await loadFont(require("./assets/Inter-Bold.ttf"), { chars: "0123456789" });
+ * world.spawn({ text: "2048", font, scale: 0.5, color: [1, 1, 1] });
+ * ```
+ */
+export declare function loadFont(source: AssetSource, options?: FontOptions): Promise<Font>;
+export type TextAlign = 'left' | 'center' | 'right';
+export type TextLayout = {
+    /** Extra space between letters, in ems (at scale 1, letters are 1 em tall). Default 0. */
+    letterSpacing?: number;
+    /** Digits all as wide as the widest, so changing numbers (scores, timers) don't shift. Default false. */
+    tabular?: boolean;
+};
+/** A line's advance in ems, with the same Unicode glyph loading, spacing and fallbacks as rendering. */
+export declare function measureText(font: Font, text: string, options?: TextLayout): number;
+/** Glyph placements for a line of text: centered vertically on capitals, aligned horizontally. */
+export declare function layoutText(font: Font, text: string, align: TextAlign, options?: TextLayout): {
+    mesh: number;
+    x: number;
+    y: number;
+}[];
+export {};

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

@@ -0,0 +1,30 @@
+import type { Vec3 } from '../types';
+import type { Color } from '../world/types';
+import { type Geometry } from './shape';
+export interface LoftSection {
+    z: number;
+    bottom: number;
+    top: number;
+    /** Half the width at the lower corners. */
+    width: number;
+    topWidth?: number;
+    /** Superellipse exponent, 2 = oval, larger values = boxier corners. Default 4. */
+    square?: number;
+}
+export interface LoftOptions {
+    around?: number;
+    smoothness?: number;
+    color?: Color | ((position: Vec3, normal: Vec3) => Color);
+}
+/**
+ * Smooth closed body through rounded rectangular cross sections along Z. Useful for vehicle
+ * shells, cabins, shoes and fairings. Caps have separate flat normals and planar UVs; sides have
+ * continuous longitudinal UVs and a welded seam. Input sections may increase or decrease in Z.
+ */
+export declare function loft(sections: readonly LoftSection[], options?: LoftOptions): Geometry;
+/** A rounded rectangular cross-section with flat front/back caps, centered at the origin. */
+export declare function block(w: number, h: number, d: number, square?: number, color?: LoftOptions['color']): Geometry;
+/** An exact ellipsoid with analytic normals, rather than capped/truncated poles. */
+export declare function ellipsoid(radii: Vec3, color?: LoftOptions['color'], around?: number): Geometry;
+/** Smooth Hermite interpolation through increasing [x,value] points; clamped beyond the ends. */
+export declare function smoothCurve(points: readonly (readonly [number, number])[]): (x: number) => number;

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

@@ -0,0 +1,47 @@
+import type { Vec3 } from '../types';
+import type { AssetSource } from './source';
+export type ModelOptions = {
+    /** Move the model's bounding box center to the origin, so `position` is its middle. Default true. */
+    center?: boolean;
+    /** Scale it so its largest side is this long (e.g. 1 to match the built-in shapes). Default: keep its size. */
+    fit?: number;
+    /**
+     * How glossy, 0..1: a sharp sun highlight and a reflection of the sky that grows at grazing angles.
+     * 0 is matte; around 0.8 reads as car paint or glass. Default 0.
+     */
+    shine?: number;
+};
+/** A loaded model: pass it as an entity's `mesh`. Colliders sized from the mesh fit its bounding box. */
+export type Model = {
+    /** Bounding box size [x, y, z] at scale 1 (after `fit`). */
+    readonly size: Vec3;
+    /** Mesh id in the core. */
+    readonly id: number;
+};
+/** An animation embedded in a loaded GLB. */
+export type ModelClip = {
+    readonly name: string;
+    readonly duration: number;
+};
+export type LoadedModel = Model & {
+    readonly animations: readonly ModelClip[];
+    readonly jointCount: number;
+};
+/** A registered mesh's geometry, aliasing native memory. */
+export declare function nativeGeometry(mesh: number): {
+    vertices: Float32Array<ArrayBuffer>;
+    indices: Uint32Array<ArrayBuffer>;
+};
+/** Independent materials share core geometry without overwriting an existing model's appearance. */
+export declare function registerModelMesh(mesh: number, shine: number): number;
+/**
+ * Initializes the engine automatically. Loads a glTF model once; pass it as an entity's `mesh`. Meshes, node transforms, material colors
+ * and the base color texture are kept (one texture per model); skeletal animation clips are available through `animations` and `World.playClip`.
+ * Every entity using the model is drawn in one instanced draw call.
+ *
+ * ```ts
+ * const tree = await loadModel(require("./assets/tree.glb"), { fit: 2 });
+ * world.spawn({ mesh: tree, position: [0, 1, 0], physics: "fixed" });
+ * ```
+ */
+export declare function loadModel(source: AssetSource, options?: ModelOptions): Promise<LoadedModel>;

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

@@ -0,0 +1,156 @@
+import type { Vec3 } from '../types';
+import type { Color, Quat } from '../world/types';
+import type { Model } from './model';
+import { type Geometry, type ShapeOptions } from './shape';
+type Node = {
+    readonly kind: 'sphere';
+    readonly radius: number;
+} | {
+    readonly kind: 'ellipsoid';
+    readonly radii: Vec3;
+} | {
+    readonly kind: 'box';
+    readonly size: Vec3;
+    readonly radius: number;
+} | {
+    readonly kind: 'capsule';
+    readonly start: Vec3;
+    readonly end: Vec3;
+    readonly radius: number;
+} | {
+    readonly kind: 'cylinder';
+    readonly radius: number;
+    readonly height: number;
+} | {
+    readonly kind: 'torus';
+    readonly radius: number;
+    readonly tube: number;
+} | {
+    readonly kind: 'union';
+    readonly a: Node;
+    readonly b: Node;
+    readonly blend: number;
+} | {
+    readonly kind: 'subtract' | 'intersect';
+    readonly a: Node;
+    readonly b: Node;
+} | {
+    readonly kind: 'transform';
+    readonly child: Node;
+    readonly position: Vec3;
+    readonly rotation: Quat;
+    readonly scale: Vec3;
+} | {
+    readonly kind: 'paint';
+    readonly child: Node;
+    readonly color: Color;
+} | {
+    readonly kind: 'shell';
+    readonly child: Node;
+    readonly thickness: number;
+} | {
+    readonly kind: 'displace';
+    readonly child: Node;
+    readonly amplitude: number;
+    readonly frequency: number;
+    readonly seed: number;
+    readonly octaves: number;
+};
+/**
+ * An immutable, code-authored solid. Join primitives into a single surface, blend organic forms,
+ * drill holes, hollow shells and add reproducible rock/terrain detail before tessellating once.
+ * Distances use world units; primitives are centered at the origin, cylinders/tori use the Y axis.
+ *
+ * const torso = Solid.ellipsoid([0.5, 0.7, 0.3]).paint([0.5, 0.1, 0.9]);
+ * const neck = Solid.capsule([0, 0.5, 0], [0, 0.9, 0], 0.15);
+ * const geometry = solidGeometry(torso.blend(neck, 0.15), { resolution: 48 });
+ */
+export declare class Solid {
+    private readonly node;
+    private constructor();
+    static sphere(radius?: number): Solid;
+    static ellipsoid(radii: Vec3): Solid;
+    /** Full width/height/depth. Rounding stays inside these dimensions. */
+    static box(size: Vec3, radius?: number): Solid;
+    static capsule(start: Vec3, end: Vec3, radius: number): Solid;
+    static cylinder(radius: number, height: number): Solid;
+    /** Major radius to the tube center; minor radius of the tube itself. */
+    static torus(radius: number, tube: number): Solid;
+    /** Balanced union for many parts; avoids building a deeply nested operation chain. */
+    static union(...solids: readonly Solid[]): Solid;
+    union(other: Solid): Solid;
+    /** Smoothly weld overlapping forms; blend controls the transition width in world units. */
+    blend(other: Solid, blend: number): Solid;
+    subtract(other: Solid): Solid;
+    intersect(other: Solid): Solid;
+    translate(position: Vec3): Solid;
+    rotate(rotation: Quat): Solid;
+    scale(scale: number | Vec3): Solid;
+    private transform;
+    /** Vertex colors blend with the surface at smooth joins. Apply after subtract() to color cut walls. */
+    paint(color: Color): Solid;
+    /** A shell centered on the original surface; thickness is its full wall thickness. */
+    shell(thickness: number): Solid;
+    /** Seeded fractal value noise. Use a resolution fine enough to sample its smallest features. */
+    displace(options: DisplacementOptions): Solid;
+    /** Serializable recipe for caching or inspecting a generated asset. */
+    toJSON(): Node;
+}
+export interface DisplacementOptions {
+    amplitude: number;
+    frequency?: number;
+    seed?: number;
+    /** 1..6 octaves. Default 3. */
+    octaves?: number;
+}
+export interface SolidOptions {
+    /** Cells across the longest dimension, 8..128. Default 48. Higher costs cubic sampling work. */
+    resolution?: number;
+    /** Planar UV projection. Use parametricSurface/loft for explicitly authored UVs. Default xy. */
+    uv?: 'xy' | 'xz' | 'yz';
+}
+/** Tessellates into editable, unregistered geometry. Prefer createSolid() for automatic model reuse. */
+export declare function solidGeometry(solid: Solid, options?: SolidOptions): Geometry;
+/**
+ * Tessellates, cleans and registers a solid once, then returns its cached model on later calls
+ * with the same recipe/options. White vertex colors can be tinted per spawned entity. Temporary
+ * intermediate meshes consume no IDs. Prepared solids persist automatically when platform storage
+ * is available; storage failure falls back to building. Call after warmUpEngine(), before spawning a run.
+ */
+export declare function createSolid(solid: Solid, options?: SolidOptions & ShapeOptions): Model;
+export interface OptimizeOptions {
+    /** Target triangle fraction in (0,1]. Default 1: lossless cleanup, welding and GPU cache ordering. */
+    ratio?: number;
+    /** Maximum relative error, 0..1, against the largest dimension, with attribute error included. Default 0.001. */
+    error?: number;
+    /** Keep open borders fixed, useful for separately generated terrain chunks. Default true. */
+    lockBorders?: boolean;
+}
+/**
+ * Returns new geometry, preserving the input and its normal/color/UV seams. Removes degenerate
+ * triangles and unused/identical vertices, simplifies within the error bound, then orders buffers
+ * for GPU reuse. The error bound may prevent reaching the requested ratio. Opaque static meshes only:
+ * do not use on skinning buffers or meshes whose vertex indices are used by external code.
+ */
+export declare function optimizeGeometry(geometry: Geometry, options?: OptimizeOptions): Geometry;
+/**
+ * Independently simplifies the original at each requested ratio, avoiding accumulated error.
+ * Cache/register the results once. The caller selects a level when camera distance changes.
+ */
+export declare function createGeometryLods(geometry: Geometry, ratios?: readonly number[], options?: Omit<OptimizeOptions, 'ratio'>): Geometry[];
+export interface GeometryStats {
+    vertices: number;
+    triangles: number;
+    /** CPU geometry bytes, excluding registration/driver copies. */
+    bytes: number;
+    bounds: {
+        min: Vec3;
+        max: Vec3;
+        size: Vec3;
+    } | null;
+}
+/** Cheap counts and bounds without registering a mesh. */
+export declare function getGeometryStats(geometry: Geometry): GeometryStats;
+/** Copies/sculpts one smooth surface and updates its normals. Deform hard-edged parts separately. */
+export declare function deformGeometry(geometry: Geometry, deform: (position: Vec3, uv: readonly [number, number]) => Vec3): Geometry;
+export {};

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

@@ -0,0 +1,202 @@
+import { type MeshGeometry } from '../render/meshes';
+import { type Shape, type Vec3 } from '../types';
+import type { Color, Quat } from '../world/types';
+import { type Model } from './model';
+import type { OptimizeOptions } from './modelling';
+type P2 = [number, number];
+/**
+ * A 2D outline, built like an SVG path: x right, y down. Solids made from it
+ * (`extrude`, `lathe`) are flipped upright, so a path drawn the way it looks on screen stands the
+ * same way in the world. Coordinates are in world units: a 1 x 1 path makes a 1 unit wide shape.
+ *
+ * ```ts
+ * const heart = Path.fromSVG("M0.5 0.9 C0 0.5 0 0.1 0.25 0.1 C0.4 0.1 0.5 0.25 0.5 0.3 C0.5 0.25 0.6 0.1 0.75 0.1 C1 0.1 1 0.5 0.5 0.9 Z");
+ * const star = new Path().addStar(0, 0, 0.5, 0.22, 5);
+ * ```
+ */
+export declare class Path {
+    private contours;
+    private start;
+    private last;
+    private get current();
+    private add;
+    /** Starts a new contour at (x, y). */
+    moveTo(x: number, y: number): this;
+    lineTo(x: number, y: number): this;
+    /** A quadratic Bézier through control point (cx, cy) to (x, y). */
+    quadraticTo(cx: number, cy: number, x: number, y: number): this;
+    /** A cubic Bézier through control points (c1x, c1y) and (c2x, c2y) to (x, y). */
+    cubicTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): this;
+    /**
+     * An elliptical arc to (x, y), as in SVG's `A` command: radii rx, ry, the ellipse turned `rotation`
+     * radians, and the flags choosing which of the four possible arcs.
+     */
+    arcTo(rx: number, ry: number, rotation: number, largeArc: boolean, sweep: boolean, x: number, y: number): this;
+    /** Closes the current contour back to its first point. */
+    close(): this;
+    /** A closed polygon through `points`. */
+    addPolygon(points: readonly (readonly [number, number])[], close?: boolean): this;
+    addRect(x: number, y: number, width: number, height: number): this;
+    /** A rectangle with corners rounded by `radius` (or [rx, ry]). */
+    addRoundedRect(x: number, y: number, width: number, height: number, radius: number | readonly [number, number]): this;
+    /** An ellipse filling the box. */
+    addOval(x: number, y: number, width: number, height: number): this;
+    addCircle(cx: number, cy: number, radius: number): this;
+    /** A star with `points` tips at `outer` radius and notches at `inner`, the first tip pointing up. */
+    addStar(cx: number, cy: number, outer: number, inner: number, points?: number): this;
+    /** A regular polygon with `sides` corners, the first pointing up. */
+    addRegularPolygon(cx: number, cy: number, radius: number, sides: number): this;
+    /**
+     * Parses SVG path data (`d`): M L H V C S Q T A Z, absolute and relative. Paste paths from Figma,
+     * Illustrator or any icon set (scale them with `fit` on the shape, or `transform` here).
+     */
+    static fromSVG(d: string): Path;
+    /** A copy moved by (dx, dy) and scaled by sx, sy (about the origin, before moving). */
+    transform(sx: number, sy?: number, dx?: number, dy?: number): Path;
+    /** The flattened contours (curves turned into points), y down as drawn. */
+    toContours(): P2[][];
+    /** [minX, minY, maxX, maxY], or undefined for an empty path. */
+    bounds(): [number, number, number, number] | undefined;
+}
+/**
+ * Shape geometry, before it's registered: 11 floats per vertex (position, normal, color, uv) and
+ * triangle indices. Builders return it; `merge` combines it; `createShape` turns it into a mesh.
+ */
+export type Geometry = MeshGeometry;
+/** A built-in shape's geometry (unit-sized, centered), to `merge` with others. */
+export declare function shapeGeometry(shape: Exclude<Shape, 'none' | 'puff' | 'flame'>, options?: {
+    color?: Color;
+}): Geometry;
+export type ExtrudeOptions = {
+    /** How deep, in the path's units. 0 = a flat, one-sided face (facing +Z). Default 0.2. */
+    depth?: number;
+    /** SVG fill rules: "nonzero" (the default winding rule) or "evenodd" (every inner contour is a hole). */
+    fillRule?: 'nonzero' | 'evenodd';
+    /** Vertex color (multiplies the entity's color). Default white. */
+    color?: Color;
+};
+/**
+ * A 2D path filled and pushed into a solid, facing +Z: badges, coins, leaves, hearts, stars, logos,
+ * fruit slices. Holes follow the fill rule. Textures map across the front face.
+ */
+export declare function extrude(path: Path, options?: ExtrudeOptions): Geometry;
+/** Where a color function is asked about: `u` around (0..1), `v` along (0..1), and the surface there. */
+export type SurfacePoint = {
+    u: number;
+    v: number;
+    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);
+export type LatheOptions = {
+    /** Steps around the axis. Default 32. */
+    segments?: number;
+    /** How far around, in radians: TAU (default) is a full turn; Math.PI a half, for a cut fruit. */
+    sweep?: number;
+    /** Color of the outside: one color, or a function of the surface point (u around, v down the profile). Default white. */
+    color?: SurfaceColor;
+    /**
+     * Pushes the surface out (or in, if negative) along its normal by this much at (u, v): peel dimples,
+     * 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;
+    /** 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. */
+    capRings?: number;
+    /**
+     * 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);
+    /** Steps from the axis to the skin across each cut face, for a detailed `cutColor`. Default 12 for a function. */
+    cutSteps?: number;
+};
+/**
+ * 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;
+/**
+ * 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:
+ * coincident vertices share a normal. Degenerate faces leave the original normals intact.
+ */
+export declare function smoothNormals(g: Geometry): Geometry;
+/**
+ * Spins a profile around the vertical axis, like a potter's wheel: fruit (apples, oranges, lemons,
+ * pears, cherries), vases, bottles, bowls, chess pieces, spinning tops. The profile is a `Path`
+ * (x = distance from the axis, y down, as drawn) or [radius, height] points (y up), top to bottom.
+ * Open ends away from the axis are capped. With `sweep` < TAU the cut faces are closed too.
+ */
+export declare function lathe(profile: Path | readonly (readonly [number, number])[], options?: LatheOptions): Geometry;
+export type TubeOptions = {
+    /** Radius, or a function of t (0 at the first point, 1 at the last) for tapering: bananas, horns, tails. Default 0.1. */
+    radius?: number | ((t: number) => number);
+    /**
+     * The cross-section: a radius multiplier at each point around (0..1, repeating), e.g. ridges for a
+     * banana or a star for a churro. Default round.
+     */
+    shape?: (around: number) => number;
+    /** Steps around the tube. Default 12. */
+    sides?: number;
+    /** Steps between each pair of points (the path is smoothed through them). Default 8. */
+    smoothness?: number;
+    /** Cap the ends (where the radius isn't 0). Default true. */
+    caps?: boolean;
+    /** Join the last point to the first with a smooth, untwisted seam; no end caps. Default false. */
+    closed?: boolean;
+    /** Color: one, or a function of the surface point (u around, v = t along). Default white. */
+    color?: SurfaceColor;
+    /** Color of the end caps (the face of a cut banana). Default `color`. */
+    capColor?: FaceColor;
+};
+/**
+ * A tube along a smooth curve through `points`: bananas, stems, chillies, worms, snakes, ropes,
+ * pipes, tentacles, candy canes.
+ */
+export declare function tube(points: readonly Vec3[], options?: TubeOptions): Geometry;
+export type GeometryPart = {
+    geometry: Geometry;
+    position?: Vec3;
+    /** A quaternion [x, y, z, w], as entities use. */
+    rotation?: Quat;
+    scale?: Vec3 | number;
+    /** Multiplies the part's vertex colors: an apple's red body, brown stem and green leaf in one mesh. */
+    color?: Color;
+};
+/**
+ * Bakes parts into one geometry, each scaled, rotated, moved and colored. One mesh draws in one
+ * instanced call and moves, spins and slices as one entity.
+ */
+export declare function merge(parts: readonly GeometryPart[]): Geometry;
+export type ShapeOptions = {
+    /** Clean/optimize before upload, or simplify within an error bound. Built once, then shared. Default false. */
+    optimize?: boolean | OptimizeOptions;
+    /** Move the bounding box's center to the origin, so `position` is the middle. Default true. */
+    center?: boolean;
+    /** Scale so the largest side is this long (1 matches the built-in shapes). Default: keep the size. */
+    fit?: number;
+    /** How glossy, 0..1 (as for models): around 0.6 for a waxy apple, 0.85 for glass. Default 0. */
+    shine?: number;
+};
+/**
+ * Registers geometry as a mesh: pass the result as an entity's `mesh` (or a burst's), with any
+ * `texture`, physics and picking. Colliders default to a box holding the shape. Mesh ids are
+ * shared by models, fonts and shapes (about 4,080) and live for the whole app. Equal geometry/options
+ * automatically reuse preparation and registration; input buffers may still be edited for a later
+ * call. Material variants remain independent. Build geometry during scene setup, outside onUpdate.
+ *
+ * ```ts
+ * const orange = createShape(lathe(orangeProfile, { color: [1, 0.55, 0.1] }), { fit: 1, shine: 0.3 });
+ * world.spawn({ mesh: orange, position: [0, 2, 0], physics: "dynamic" });
+ * ```
+ */
+export declare function createShape(geometry: Geometry, options?: ShapeOptions): Model;
+export declare function preparedModel(mesh: number, shine: number): Model;
+export declare function prepareOptions(options: ShapeOptions): string;
+export {};

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

@@ -0,0 +1,7 @@
+/** Browser assets use URLs (including URLs emitted by Vite/webpack imports). */
+export type AssetSource = number | string;
+export declare function assetUri(source: AssetSource): string | undefined;
+export declare function loadAssetBytes(source: AssetSource): Promise<{
+    uri: string;
+    bytes: ArrayBuffer;
+}>;

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

@@ -0,0 +1,6 @@
+import type { ProceduralStorage } from './ProceduralCache';
+export declare function proceduralStorage(revision: string): ProceduralStorage | undefined;
+export declare function readPersistentAsset(key: string): Promise<ArrayBuffer | null>;
+export declare function writePersistentAsset(key: string, bytes: ArrayBuffer): Promise<void>;
+export declare function removePersistentAsset(key: string): Promise<void>;
+export declare function clearPersistentStorage(): Promise<void>;

package/lib/web/types/src/assets/storage.shared.d.ts

@@ -0,0 +1,6 @@
+import type { ProceduralStorage } from './ProceduralCache';
+export declare function proceduralStorage(revision: string): ProceduralStorage | undefined;
+export declare function readPersistentAsset(key: string): Promise<ArrayBuffer | null>;
+export declare function writePersistentAsset(key: string, bytes: ArrayBuffer): Promise<void>;
+export declare function removePersistentAsset(key: string): Promise<void>;
+export declare function clearPersistentStorage(): Promise<void>;

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

@@ -0,0 +1,16 @@
+import type { Vec3 } from '../types';
+import type { Geometry, SurfaceColor } from './shape';
+export interface ParametricSurfaceOptions {
+    uSegments?: number;
+    vSegments?: number;
+    /** Match the first/last positions and smooth their normals, keeping separate 0/1 UVs. */
+    wrapU?: boolean;
+    wrapV?: boolean;
+    color?: SurfaceColor;
+}
+/**
+ * Samples an arbitrary surface on u/v in [0,1]. Winding follows dP/du cross dP/dv.
+ * Use for terrain, cloth, wings, twisted ribbons and custom mathematical forms. Wrapped edges
+ * retain texture seams; coincident pole vertices share normals. Degenerate triangles are omitted.
+ */
+export declare function parametricSurface(sample: (u: number, v: number) => Vec3, options?: ParametricSurfaceOptions): Geometry;

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

@@ -0,0 +1,29 @@
+import type { AssetSource } from './source';
+/** A loaded image. Pass it as an entity's `texture`. */
+export type Texture = {
+    readonly id: number;
+    readonly width: number;
+    readonly height: number;
+};
+export type TextureImage = {
+    width: number;
+    height: number;
+    pixels: Uint8Array;
+};
+/**
+ * Initializes the engine automatically. Loads a PNG or JPEG once (up to 4096 x 4096). Use it on any entity: `{ mesh: "cube", texture }`.
+ * The entity's `color` tints it; `textureRegion` shows part of it (sprite sheets, card atlases).
+ *
+ * ```ts
+ * const crate = await loadTexture(require("./assets/crate.png"));
+ * world.spawn({ mesh: "cube", texture: crate });
+ * ```
+ */
+export declare function loadTexture(source: AssetSource): Promise<Texture>;
+/** Pixels of a texture id (aliasing native memory), for the renderer. */
+export declare function textureImage(id: number): TextureImage;
+/**
+ * The mesh id that draws `mesh`'s geometry with `texture`: a textured variant made on first use
+ * (it shares the geometry, colliders and picking of the original).
+ */
+export declare function texturedMesh(mesh: number, texture: Texture): number;

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

@@ -0,0 +1,3 @@
+import type { DrawingCanvasProps } from './types';
+export type { DrawingCanvasProps } from './types';
+export declare const DrawingCanvas: import("react").MemoExoticComponent<({ document: drawing, mode, background, active, onError, onChange, style }: DrawingCanvasProps) => import("react").JSX.Element>;