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

package/lib/typescript/src/drawing/DrawingDocument.d.ts

@@ -0,0 +1,210 @@
+import type { Texture } from '../assets/texture.js';
+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;
+}
+//# sourceMappingURL=DrawingDocument.d.ts.map

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

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

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

@@ -0,0 +1,45 @@
+export { World, isEngineAvailable } from './world/World.js';
+export { quat, type MutableQuat } from './world/quat.js';
+export { toColor, type ColorInput } from './world/color.js';
+export { effects, type DustOptions, type EffectOptions, type FlashOptions, type PopOptions } from './world/effects.js';
+export { Scoreboard, type ScoreboardHandlers } from './world/Scoreboard.js';
+export type { AnimateOptions, AnimateTarget, BodyType, Bounds, BurstOptions, CollisionInfo, ClipOptions, ScreenPlane, Color, Easing, Entity, EntityOptions, ImpactFeedback, Keyframe, PhysicsOptions, PickHit, Quat, RaycastHit, SpringOptions } from './world/types.js';
+export { afterNextFrame, GameView } from './render/GameView.js';
+export { useWorld, type WorldSetup } from './render/useWorld.js';
+export { frontLight } from './render/light.js';
+export { warmUpEngine, getMeshIdLimit } from './render/meshes.js';
+export type { TransformBatch, TransformOptions } from './world/TransformBatch.js';
+export type { DragEvent, GameViewProps, GameViewStats, OverlayTouchPhase, PinchEvent, SwipeDirection } from './render/GameView.js';
+export type { RenderQuality, RenderQualitySetting } from './render/quality.js';
+export type { AssetSource } from './assets/source';
+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 { 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 type { ParametricSurfaceOptions } from './assets/surface.js';
+export type { 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 { haptics } from './media/haptics.js';
+export type { HapticTap } from './media/haptics.js';
+export { Joystick, useJoystick } from './input/Joystick';
+export type { JoystickState, JoystickProps } from './input/Joystick';
+export { createKeyboardInput } from './input/keyboard.js';
+export type { KeyboardInputMode, KeyboardInputOptions } from './input/keyboard.js';
+export { MAX_MESHES } from './types.js';
+export type { Camera, Light, RenderSource, Shape, Vec3 } from './types.js';
+export { DrawingDocument } from './drawing/DrawingDocument.js';
+export type { DrawingBrush, DrawingBrushOptions, DrawingControls, DrawingState, DrawingSnapshot, SavedDrawingPath, DrawingTool, DrawingShape, DrawingShapePreview, DrawingSymmetry, DrawingLayer, DrawingProject, DrawingStroke, DrawingSample, DrawingCoverageOptions } from './drawing/DrawingDocument.js';
+export { DrawingCanvas } from './drawing/DrawingCanvas';
+export type { DrawingCanvasProps } from './drawing/DrawingCanvas';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/input/Joystick.d.ts

@@ -0,0 +1,20 @@
+import { type ViewStyle } from 'react-native';
+/** Written by `<Joystick>` on touch; read it from your game loop. Each axis is in -1..1, y is up. */
+export type JoystickState = {
+    x: number;
+    y: number;
+};
+/** A joystick state that lives as long as the component: `const stick = useJoystick()`. */
+export declare function useJoystick(): JoystickState;
+export type JoystickProps = {
+    state: JoystickState;
+    /** Diameter of the pad in points. */
+    size?: number;
+    style?: ViewStyle;
+};
+/**
+ * A relative touch stick: wherever the finger lands inside the pad is the center.
+ * Updates `state` synchronously on the JS thread, so there is no React re-render per touch.
+ */
+export declare function Joystick({ state, size, style }: JoystickProps): import("react").JSX.Element;
+//# sourceMappingURL=Joystick.d.ts.map

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

@@ -0,0 +1,13 @@
+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;
+//# sourceMappingURL=Joystick.web.d.ts.map

package/lib/typescript/src/input/keyboard.d.ts

@@ -0,0 +1,17 @@
+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;
+};
+//# sourceMappingURL=keyboard.d.ts.map

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

@@ -0,0 +1,46 @@
+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;
+};
+//# sourceMappingURL=audio.d.ts.map

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

@@ -0,0 +1,22 @@
+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;
+};
+//# sourceMappingURL=haptics.d.ts.map

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

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

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

@@ -0,0 +1,8 @@
+import type { EngineBridge } from './EngineBridge.js';
+/** 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;
+//# sourceMappingURL=BrowserEngine.d.ts.map

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

@@ -0,0 +1,26 @@
+import type { Spec } from './spec/NativeNayanEngine.js';
+/** 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 Promise<unknown> ? T : T extends (...args: never[]) => unknown ? T : T extends object ? Buffer : T;
+type BufferMethod<T> = T extends (...args: infer A) => infer R ? (...args: {
+    [K in keyof A]: BufferValue<A[K], ArrayBufferLike>;
+}) => BufferValue<R, ArrayBuffer> : T;
+/** Native-only (a display clock and a render thread): absent on the web core and on older app builds. */
+type NativeFrames = 'publishFrame' | 'renderStats' | 'hasFrameClock' | 'startFrames' | 'stopFrames';
+type BinarySpec = Omit<Spec, 'geometrySolid' | 'geometryOptimize' | 'modelSize' | 'textureSize' | NativeFrames>;
+/** The same runtime ABI on JSI and WASM, with precise TypeScript buffer and tuple contracts. */
+export type EngineBridge = {
+    [K in keyof BinarySpec]: BufferMethod<BinarySpec[K]>;
+} & {
+    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];
+} & {
+    [K in NativeFrames]?: BufferMethod<Spec[K]>;
+};
+export {};
+//# sourceMappingURL=EngineBridge.d.ts.map

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

@@ -0,0 +1,5 @@
+import type { EngineBridge } from './EngineBridge.js';
+declare const _default: EngineBridge | null;
+export default _default;
+export type { Spec } from './spec/NativeNayanEngine.js';
+//# sourceMappingURL=NativeNayanEngine.d.ts.map

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

@@ -0,0 +1,10 @@
+import type { EngineBridge } from './EngineBridge.js';
+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;
+//# sourceMappingURL=NativeNayanEngine.web.d.ts.map

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

@@ -0,0 +1,3 @@
+/** Mobile is initialized by native module registration. */
+export declare function prepareEngine(): Promise<void> | undefined;
+//# sourceMappingURL=prepare.d.ts.map

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

@@ -0,0 +1,2 @@
+export declare function prepareEngine(): Promise<void>;
+//# sourceMappingURL=prepare.web.d.ts.map