nova64 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nova64",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Nova64 — Ultimate 3D Fantasy Console runtime for JavaScript games powered by Three.js",
   "keywords": [
     "fantasy-console",
@@ -22,8 +22,12 @@
   },
   "type": "module",
   "main": "./runtime/index.js",
+  "types": "./runtime/index.d.ts",
   "exports": {
-    ".": "./runtime/index.js",
+    ".": {
+      "types": "./runtime/index.d.ts",
+      "default": "./runtime/index.js"
+    },
     "./runtime/*": "./runtime/*.js",
     "./runtime/api-3d/*": "./runtime/api-3d/*.js",
     "./runtime/ui/*": "./runtime/ui/*.js"
@@ -208,6 +212,13 @@
       "setInstanceColor": "readonly",
       "finalizeInstances": "readonly",
       "removeInstancedMesh": "readonly",
+      "createParticleSystem": "readonly",
+      "setParticleEmitter": "readonly",
+      "emitParticle": "readonly",
+      "burstParticles": "readonly",
+      "updateParticles": "readonly",
+      "removeParticleSystem": "readonly",
+      "getParticleStats": "readonly",
       "createLODMesh": "readonly",
       "setLODPosition": "readonly",
       "removeLODMesh": "readonly",

package/runtime/api-3d/particles.js

@@ -0,0 +1,296 @@
+// runtime/api-3d/particles.js
+// GPU particle system: typed-array physics simulation, single InstancedMesh draw call
+//
+// API:
+//   createParticleSystem(maxParticles, options) → systemId
+//   setParticleEmitter(systemId, emitter)          configure emission
+//   emitParticle(systemId, overrides?)             fire one particle
+//   burstParticles(systemId, count, overrides?)    fire N particles at once
+//   updateParticles(dt)                            step all systems (call each frame)
+//   removeParticleSystem(systemId)                 cleanup
+
+import * as THREE from 'three';
+
+export function particlesModule({ scene, counters }) {
+  // Per-particle typed arrays layout (indices into Float32Array pools):
+  //   px py pz  — position
+  //   vx vy vz  — velocity
+  //   age life  — lifetime tracking
+  //   r g b     — color (0-1)
+  //   size      — scale
+  //   active    — 1 = alive, 0 = dead
+
+  const STRIDE = 13; // slots per particle
+
+  const particleSystems = new Map();
+  let psCounter = 0;
+
+  const _dummy = new THREE.Object3D();
+  const _color = new THREE.Color();
+
+  function createParticleSystem(maxParticles = 200, options = {}) {
+    const {
+      shape = 'sphere',
+      size = 0.15,
+      segments = 4,
+      color = 0xffaa00,
+      emissive = 0xff6600,
+      emissiveIntensity = 2.0,
+      gravity = -9.8,
+      drag = 0.95,
+      // Emitter defaults
+      emitterX = 0,
+      emitterY = 0,
+      emitterZ = 0,
+      emitRate = 20, // particles per second
+      minLife = 0.8,
+      maxLife = 2.0,
+      minSpeed = 2,
+      maxSpeed = 8,
+      spread = Math.PI, // half-angle cone spread (PI = hemisphere)
+      minSize = 0.05,
+      maxSize = 0.3,
+      startColor = color,
+      endColor = 0x000000,
+    } = options;
+
+    // Geometry
+    let geometry;
+    if (shape === 'cube') {
+      geometry = new THREE.BoxGeometry(size, size, size);
+    } else {
+      geometry = new THREE.SphereGeometry(size, segments, segments);
+    }
+
+    const material = new THREE.MeshBasicMaterial({ color, vertexColors: false });
+    material.emissive = new THREE.Color(emissive);
+    // MeshBasicMaterial doesn't have emissive — use MeshStandardMaterial instead
+    const stdMat = new THREE.MeshStandardMaterial({
+      color,
+      emissive: new THREE.Color(emissive),
+      emissiveIntensity,
+      roughness: 0.8,
+      metalness: 0.0,
+    });
+
+    const mesh = new THREE.InstancedMesh(geometry, stdMat, maxParticles);
+    mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+    mesh.castShadow = false;
+    mesh.receiveShadow = false;
+
+    // Hide all instances initially by scaling to zero
+    _dummy.position.set(0, -9999, 0);
+    _dummy.scale.set(0, 0, 0);
+    _dummy.updateMatrix();
+    for (let i = 0; i < maxParticles; i++) {
+      mesh.setMatrixAt(i, _dummy.matrix);
+    }
+    mesh.instanceMatrix.needsUpdate = true;
+
+    // Enable per-instance color
+    mesh.instanceColor = new THREE.InstancedBufferAttribute(new Float32Array(maxParticles * 3), 3);
+
+    scene.add(mesh);
+
+    // Typed-array particle state pool
+    const pool = new Float32Array(maxParticles * STRIDE);
+    // All start inactive (age = life = 0, active slot = 0)
+
+    const id = ++psCounter;
+    particleSystems.set(id, {
+      mesh,
+      pool,
+      maxParticles,
+      freeList: Array.from({ length: maxParticles }, (_, i) => i),
+      activeCount: 0,
+      emitAccum: 0,
+      emitter: {
+        x: emitterX,
+        y: emitterY,
+        z: emitterZ,
+        emitRate,
+        minLife,
+        maxLife,
+        minSpeed,
+        maxSpeed,
+        spread,
+        minSize,
+        maxSize,
+      },
+      config: {
+        gravity,
+        drag,
+        startColor: new THREE.Color(startColor),
+        endColor: new THREE.Color(endColor),
+      },
+    });
+
+    counters.particle = (counters.particle || 0) + 1;
+    return id;
+  }
+
+  function setParticleEmitter(systemId, emitter = {}) {
+    const sys = particleSystems.get(systemId);
+    if (!sys) return;
+    Object.assign(sys.emitter, emitter);
+  }
+
+  function _spawnParticle(sys, overrides = {}) {
+    if (sys.freeList.length === 0) return; // pool full
+    const idx = sys.freeList.pop();
+    const base = idx * STRIDE;
+    const { pool, emitter } = sys;
+
+    const ex = overrides.x ?? emitter.x;
+    const ey = overrides.y ?? emitter.y;
+    const ez = overrides.z ?? emitter.z;
+
+    // Random direction within spread cone (pointing up by default)
+    const phi = Math.random() * Math.PI * 2;
+    const theta = Math.random() * (overrides.spread ?? emitter.spread);
+    const ct = Math.cos(theta);
+    const st = Math.sin(theta);
+    const speed = emitter.minSpeed + Math.random() * (emitter.maxSpeed - emitter.minSpeed);
+    const vx = overrides.vx ?? st * Math.cos(phi) * speed;
+    const vy = overrides.vy ?? ct * speed;
+    const vz = overrides.vz ?? st * Math.sin(phi) * speed;
+
+    const life = emitter.minLife + Math.random() * (emitter.maxLife - emitter.minLife);
+    const sz = emitter.minSize + Math.random() * (emitter.maxSize - emitter.minSize);
+
+    // position
+    pool[base + 0] = ex;
+    pool[base + 1] = ey;
+    pool[base + 2] = ez;
+    // velocity
+    pool[base + 3] = vx;
+    pool[base + 4] = vy;
+    pool[base + 5] = vz;
+    // age, life
+    pool[base + 6] = 0;
+    pool[base + 7] = life > 0 ? life : 1;
+    // color (start)
+    const sc = sys.config.startColor;
+    pool[base + 8] = overrides.r ?? sc.r;
+    pool[base + 9] = overrides.g ?? sc.g;
+    pool[base + 10] = overrides.b ?? sc.b;
+    // size
+    pool[base + 11] = sz;
+    // active
+    pool[base + 12] = 1;
+
+    sys.activeCount++;
+  }
+
+  function emitParticle(systemId, overrides = {}) {
+    const sys = particleSystems.get(systemId);
+    if (sys) _spawnParticle(sys, overrides);
+  }
+
+  function burstParticles(systemId, count = 10, overrides = {}) {
+    const sys = particleSystems.get(systemId);
+    if (!sys) return;
+    for (let i = 0; i < count; i++) _spawnParticle(sys, overrides);
+  }
+
+  function updateParticles(dt) {
+    particleSystems.forEach(sys => {
+      const { pool, maxParticles, mesh, config, emitter } = sys;
+
+      // Auto-emit based on rate
+      sys.emitAccum += emitter.emitRate * dt;
+      while (sys.emitAccum >= 1 && sys.freeList.length > 0) {
+        _spawnParticle(sys);
+        sys.emitAccum -= 1;
+      }
+
+      let needsUpdate = false;
+
+      for (let i = 0; i < maxParticles; i++) {
+        const base = i * STRIDE;
+        if (pool[base + 12] === 0) continue; // inactive
+
+        // Step age
+        pool[base + 6] += dt;
+        const age = pool[base + 6];
+        const life = pool[base + 7];
+
+        if (age >= life) {
+          // Kill particle
+          pool[base + 12] = 0;
+          sys.freeList.push(i);
+          sys.activeCount--;
+
+          // Scale to zero
+          _dummy.position.set(0, -9999, 0);
+          _dummy.scale.set(0, 0, 0);
+          _dummy.updateMatrix();
+          mesh.setMatrixAt(i, _dummy.matrix);
+          needsUpdate = true;
+          continue;
+        }
+
+        // Physics integration
+        pool[base + 3] *= config.drag; // drag on vx
+        pool[base + 5] *= config.drag; // drag on vz
+        pool[base + 4] += config.gravity * dt; // gravity on vy
+
+        pool[base + 0] += pool[base + 3] * dt; // px
+        pool[base + 1] += pool[base + 4] * dt; // py
+        pool[base + 2] += pool[base + 5] * dt; // pz
+
+        // Interpolate color start→end
+        const t = age / life;
+        const r = pool[base + 8] * (1 - t) + config.endColor.r * t;
+        const g = pool[base + 9] * (1 - t) + config.endColor.g * t;
+        const b = pool[base + 10] * (1 - t) + config.endColor.b * t;
+        _color.setRGB(r, g, b);
+        mesh.setColorAt(i, _color);
+
+        // Shrink as particle ages
+        const sz = pool[base + 11] * (1 - t * 0.8);
+
+        _dummy.position.set(pool[base + 0], pool[base + 1], pool[base + 2]);
+        _dummy.scale.set(sz, sz, sz);
+        _dummy.updateMatrix();
+        mesh.setMatrixAt(i, _dummy.matrix);
+        needsUpdate = true;
+      }
+
+      if (needsUpdate) {
+        mesh.instanceMatrix.needsUpdate = true;
+        if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
+      }
+    });
+  }
+
+  function removeParticleSystem(systemId) {
+    const sys = particleSystems.get(systemId);
+    if (!sys) return false;
+    scene.remove(sys.mesh);
+    sys.mesh.geometry?.dispose();
+    sys.mesh.material?.dispose();
+    particleSystems.delete(systemId);
+    return true;
+  }
+
+  function getParticleStats(systemId) {
+    const sys = particleSystems.get(systemId);
+    if (!sys) return null;
+    return {
+      active: sys.activeCount,
+      max: sys.maxParticles,
+      free: sys.freeList.length,
+    };
+  }
+
+  return {
+    createParticleSystem,
+    setParticleEmitter,
+    emitParticle,
+    burstParticles,
+    updateParticles,
+    removeParticleSystem,
+    getParticleStats,
+  };
+}

package/runtime/api-3d.js

@@ -11,6 +11,7 @@ import { modelsModule } from './api-3d/models.js';
 import { instancingModule } from './api-3d/instancing.js';
 import { pbrModule } from './api-3d/pbr.js';
 import { sceneModule } from './api-3d/scene.js';
+import { particlesModule } from './api-3d/particles.js';
 
 export function threeDApi(gpu) {
   if (!gpu.getScene) return { exposeTo: () => {} };
@@ -53,6 +54,7 @@ export function threeDApi(gpu) {
   Object.assign(ctx, modelsModule(ctx));
   Object.assign(ctx, instancingModule(ctx));
   Object.assign(ctx, pbrModule(ctx));
+  Object.assign(ctx, particlesModule(ctx));
   Object.assign(ctx, sceneModule(ctx)); // last: uses late binding to call other modules
 
   return {
@@ -138,6 +140,15 @@ export function threeDApi(gpu) {
         setNormalMap: ctx.setNormalMap,
         setPBRMaps: ctx.setPBRMaps,
 
+        // GPU particle system
+        createParticleSystem: ctx.createParticleSystem,
+        setParticleEmitter: ctx.setParticleEmitter,
+        emitParticle: ctx.emitParticle,
+        burstParticles: ctx.burstParticles,
+        updateParticles: ctx.updateParticles,
+        removeParticleSystem: ctx.removeParticleSystem,
+        getParticleStats: ctx.getParticleStats,
+
         // Interaction / stats / convenience
         raycastFromCamera: ctx.raycastFromCamera,
         get3DStats: ctx.get3DStats,

package/runtime/index.d.ts

@@ -0,0 +1,682 @@
+// Nova64 — Type declarations
+// https://github.com/seacloud9/nova64
+
+// ---------------------------------------------------------------------------
+// Shared primitives
+// ---------------------------------------------------------------------------
+
+/** Hex colour integer, e.g. 0xff0000 for red. */
+export type Color = number;
+
+/** Mesh identifier returned by primitive-creation functions. */
+export type MeshId = number;
+
+/** Light identifier returned by createPointLight. */
+export type LightId = number;
+
+/** Instanced-mesh identifier returned by createInstancedMesh. */
+export type InstancedMeshId = number;
+
+/** LOD identifier returned by createLODMesh. */
+export type LODId = number;
+
+/** Particle system identifier returned by createParticleSystem. */
+export type ParticleSystemId = number;
+
+export interface ParticleSystemOptions {
+  shape?: 'sphere' | 'cube';
+  size?: number;
+  segments?: number;
+  color?: Color;
+  emissive?: Color;
+  emissiveIntensity?: number;
+  gravity?: number;
+  drag?: number;
+  emitterX?: number;
+  emitterY?: number;
+  emitterZ?: number;
+  emitRate?: number;
+  minLife?: number;
+  maxLife?: number;
+  minSpeed?: number;
+  maxSpeed?: number;
+  spread?: number;
+  minSize?: number;
+  maxSize?: number;
+  startColor?: Color;
+  endColor?: Color;
+}
+
+export interface ParticleEmitter {
+  x: number;
+  y: number;
+  z: number;
+  emitRate: number;
+  minLife: number;
+  maxLife: number;
+  minSpeed: number;
+  maxSpeed: number;
+  spread: number;
+  minSize: number;
+  maxSize: number;
+}
+
+export interface ParticleOverrides {
+  x: number;
+  y: number;
+  z: number;
+  vx: number;
+  vy: number;
+  vz: number;
+  spread: number;
+  r: number;
+  g: number;
+  b: number;
+}
+
+/** Panel object returned by createPanel. */
+export interface Panel {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  options: PanelOptions;
+}
+
+/** Button object returned by createButton. */
+export interface Button {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  text: string;
+  callback: () => void;
+  options: ButtonOptions;
+  hovered: boolean;
+  pressed: boolean;
+}
+
+export interface MousePosition {
+  x: number;
+  y: number;
+}
+
+// ---------------------------------------------------------------------------
+// Material / primitive options
+// ---------------------------------------------------------------------------
+
+export interface MeshOptions {
+  /** @default 'standard' */
+  material?: 'standard' | 'holographic' | 'metallic' | 'emissive' | 'wireframe';
+  roughness?: number;
+  metalness?: number;
+  emissive?: Color;
+  emissiveIntensity?: number;
+  transparent?: boolean;
+  opacity?: number;
+  wireframe?: boolean;
+  flatShading?: boolean;
+  segments?: number;
+  size?: number;
+  height?: number;
+  width?: number;
+}
+
+export interface LODLevel {
+  shape?: 'cube' | 'sphere' | 'plane' | 'cylinder' | 'cone';
+  size?: number;
+  color?: Color;
+  distance: number;
+  options?: MeshOptions;
+}
+
+export interface PBRMaps {
+  normalMap?: THREE.Texture | null;
+  roughnessMap?: THREE.Texture | null;
+  metalnessMap?: THREE.Texture | null;
+  aoMap?: THREE.Texture | null;
+}
+
+// ---------------------------------------------------------------------------
+// UI options
+// ---------------------------------------------------------------------------
+
+export interface PanelOptions {
+  color?: Color;
+  border?: Color;
+  borderWidth?: number;
+  alpha?: number;
+  radius?: number;
+  title?: string;
+}
+
+export interface ButtonOptions {
+  normalColor?: Color;
+  hoverColor?: Color;
+  pressedColor?: Color;
+  textColor?: Color;
+  borderColor?: Color;
+  borderWidth?: number;
+  radius?: number;
+  fontSize?: number;
+}
+
+export interface ProgressBarOptions {
+  backgroundColor?: Color;
+  fillColor?: Color;
+  borderColor?: Color;
+  showText?: boolean;
+  textColor?: Color;
+  radius?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Stats
+// ---------------------------------------------------------------------------
+
+export interface Stats3D {
+  meshCount: number;
+  lightCount: number;
+  instancedMeshCount: number;
+  lodCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+export interface LogRecord {
+  level: number;
+  message: string;
+  args: unknown[];
+  timestamp: number;
+}
+
+export declare const LogLevel: Readonly<{
+  DEBUG: 0;
+  INFO: 1;
+  WARN: 2;
+  ERROR: 3;
+  NONE: 4;
+}>;
+
+export declare class Logger {
+  level: number;
+  history: LogRecord[];
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  setLevel(level: number): void;
+  getHistory(): LogRecord[];
+  clearHistory(): void;
+}
+
+export declare const logger: Logger;
+
+// ---------------------------------------------------------------------------
+// 3D API
+// ---------------------------------------------------------------------------
+
+export interface ThreeDApiInstance {
+  // Primitives
+  createCube(
+    size?: number,
+    color?: Color,
+    position?: [number, number, number],
+    options?: MeshOptions
+  ): MeshId;
+  createSphere(
+    radius?: number,
+    color?: Color,
+    position?: [number, number, number],
+    segments?: number,
+    options?: MeshOptions
+  ): MeshId;
+  createCylinder(
+    radiusTop?: number,
+    radiusBottom?: number,
+    height?: number,
+    color?: Color,
+    position?: [number, number, number],
+    options?: MeshOptions
+  ): MeshId;
+  createPlane(
+    width?: number,
+    height?: number,
+    color?: Color,
+    position?: [number, number, number]
+  ): MeshId;
+  createAdvancedCube(
+    size?: number,
+    materialOptions?: MeshOptions,
+    position?: [number, number, number]
+  ): MeshId;
+  createAdvancedSphere(
+    radius?: number,
+    materialOptions?: MeshOptions,
+    position?: [number, number, number]
+  ): MeshId;
+  createTorus(
+    radius?: number,
+    tube?: number,
+    color?: Color,
+    position?: [number, number, number],
+    options?: MeshOptions
+  ): MeshId;
+  createCone(
+    radius?: number,
+    height?: number,
+    color?: Color,
+    position?: [number, number, number],
+    options?: MeshOptions
+  ): MeshId;
+  createCapsule(
+    radius?: number,
+    length?: number,
+    color?: Color,
+    position?: [number, number, number],
+    options?: MeshOptions
+  ): MeshId;
+
+  // Mesh management
+  destroyMesh(id: MeshId): void;
+  removeMesh(id: MeshId): void;
+  getMesh(id: MeshId): THREE.Mesh | undefined;
+
+  // Model loading
+  loadModel(
+    url: string,
+    position?: [number, number, number],
+    options?: MeshOptions
+  ): Promise<MeshId>;
+  playAnimation(
+    meshId: MeshId,
+    nameOrIndex?: string | number,
+    loop?: boolean,
+    timeScale?: number
+  ): void;
+  updateAnimations(dt: number): void;
+  loadTexture(url: string): Promise<THREE.Texture>;
+
+  // Transforms
+  setPosition(meshId: MeshId, x: number, y: number, z: number): void;
+  setRotation(meshId: MeshId, x: number, y: number, z: number): void;
+  setScale(meshId: MeshId, x: number, y: number, z: number): void;
+  getPosition(meshId: MeshId): { x: number; y: number; z: number } | null;
+  getRotation(meshId: MeshId): { x: number; y: number; z: number } | null;
+  rotateMesh(meshId: MeshId, dX: number, dY: number, dZ: number): void;
+  moveMesh(meshId: MeshId, x: number, y: number, z: number): void;
+
+  // Mesh helpers
+  setFlatShading(meshId: MeshId, enabled?: boolean): void;
+  setMeshVisible(meshId: MeshId, visible: boolean): void;
+  setMeshOpacity(meshId: MeshId, opacity: number): void;
+  setCastShadow(meshId: MeshId, cast: boolean): void;
+  setReceiveShadow(meshId: MeshId, receive: boolean): void;
+
+  // Camera
+  setCameraPosition(x: number, y: number, z: number): void;
+  setCameraTarget(x: number, y: number, z: number): void;
+  setCameraLookAt(direction: [number, number, number]): void;
+  setCameraFOV(fov: number): void;
+
+  // Atmosphere
+  setFog(color: Color, near?: number, far?: number): void;
+  clearFog(): void;
+  setLightDirection(x: number, y: number, z: number): void;
+  setLightColor(color: Color): void;
+  setAmbientLight(color: Color, intensity?: number): void;
+  setDirectionalLight(direction: [number, number, number], color?: Color, intensity?: number): void;
+
+  // Scene
+  clearScene(): void;
+  setupScene(opts?: { fog?: boolean; grid?: boolean; axes?: boolean }): void;
+
+  // Effects
+  enablePixelation(factor?: number): void;
+  enableDithering(enabled?: boolean): void;
+
+  // Dynamic lights
+  createPointLight(
+    color?: Color,
+    intensity?: number,
+    distance?: number,
+    x?: number,
+    y?: number,
+    z?: number
+  ): LightId;
+  setPointLightPosition(lightId: LightId, x: number, y: number, z: number): void;
+  setPointLightColor(lightId: LightId, color: Color): void;
+  removeLight(lightId: LightId): void;
+
+  // GPU instancing
+  createInstancedMesh(
+    shape?: 'cube' | 'sphere' | 'plane' | 'cylinder',
+    count?: number,
+    color?: Color,
+    options?: MeshOptions
+  ): InstancedMeshId;
+  setInstanceTransform(
+    instancedId: InstancedMeshId,
+    index: number,
+    x?: number,
+    y?: number,
+    z?: number,
+    rx?: number,
+    ry?: number,
+    rz?: number,
+    sx?: number,
+    sy?: number,
+    sz?: number
+  ): boolean;
+  setInstanceColor(instancedId: InstancedMeshId, index: number, color: Color): boolean;
+  finalizeInstances(instancedId: InstancedMeshId): boolean;
+  removeInstancedMesh(instancedId: InstancedMeshId): boolean;
+
+  // GPU particle system
+  createParticleSystem(maxParticles?: number, options?: ParticleSystemOptions): ParticleSystemId;
+  setParticleEmitter(systemId: ParticleSystemId, emitter: Partial<ParticleEmitter>): void;
+  emitParticle(systemId: ParticleSystemId, overrides?: Partial<ParticleOverrides>): void;
+  burstParticles(
+    systemId: ParticleSystemId,
+    count?: number,
+    overrides?: Partial<ParticleOverrides>
+  ): void;
+  updateParticles(dt: number): void;
+  removeParticleSystem(systemId: ParticleSystemId): boolean;
+  getParticleStats(
+    systemId: ParticleSystemId
+  ): { active: number; max: number; free: number } | null;
+
+  // LOD system
+  createLODMesh(levels?: LODLevel[], position?: [number, number, number]): LODId;
+  setLODPosition(lodId: LODId, x: number, y: number, z: number): void;
+  removeLODMesh(lodId: LODId): boolean;
+  updateLODs(): void;
+
+  // Normal / PBR maps
+  loadNormalMap(url: string): Promise<THREE.Texture>;
+  setNormalMap(meshId: MeshId, texture: THREE.Texture): void;
+  setPBRMaps(meshId: MeshId, maps?: PBRMaps): void;
+
+  // Raycasting / stats
+  raycastFromCamera(x: number, y: number): THREE.Intersection | null;
+  get3DStats(): Stats3D;
+
+  // Direct Three.js access
+  getScene(): THREE.Scene;
+  getCamera(): THREE.PerspectiveCamera;
+  getRenderer(): THREE.WebGLRenderer;
+
+  exposeTo(target: object): void;
+}
+
+export declare function threeDApi(gpu: unknown): ThreeDApiInstance;
+
+// ---------------------------------------------------------------------------
+// UI API
+// ---------------------------------------------------------------------------
+
+export interface UIApiInstance {
+  // Font / text
+  setFont(fontName: string): void;
+  getFont(): string;
+  setTextAlign(align: CanvasTextAlign): void;
+  setTextBaseline(baseline: CanvasTextBaseline): void;
+  measureText(text: string, scale?: number): number;
+  drawText(text: string, x: number, y: number, color?: Color, scale?: number): void;
+  drawTextShadow(
+    text: string,
+    x: number,
+    y: number,
+    color?: Color,
+    shadowColor?: Color,
+    scale?: number
+  ): void;
+  drawTextOutline(
+    text: string,
+    x: number,
+    y: number,
+    color?: Color,
+    outlineColor?: Color,
+    scale?: number
+  ): void;
+
+  // Panels
+  createPanel(x: number, y: number, width: number, height: number, options?: PanelOptions): Panel;
+  drawPanel(panel: Panel): void;
+  drawAllPanels(): void;
+  removePanel(panel: Panel): void;
+  clearPanels(): void;
+
+  // Buttons
+  createButton(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    text: string,
+    callback: () => void,
+    options?: ButtonOptions
+  ): Button;
+  updateButton(button: Button): void;
+  drawButton(button: Button): void;
+  updateAllButtons(): void;
+  drawAllButtons(): void;
+  removeButton(button: Button): void;
+  clearButtons(): void;
+
+  // Progress bar
+  drawProgressBar(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    value: number,
+    maxValue: number,
+    options?: ProgressBarOptions
+  ): void;
+
+  // Shapes
+  drawRoundedRect(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    radius: number,
+    color: Color,
+    filled?: boolean
+  ): void;
+  drawGradientRect(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    color1: Color,
+    color2: Color,
+    vertical?: boolean
+  ): void;
+
+  // Layout
+  centerX(width: number, screenWidth?: number): number;
+  centerY(height: number, screenHeight?: number): number;
+  grid(
+    cols: number,
+    rows: number,
+    cellWidth: number,
+    cellHeight: number,
+    paddingX?: number,
+    paddingY?: number
+  ): Array<{ x: number; y: number; col: number; row: number }>;
+
+  // Mouse
+  setMousePosition(x: number, y: number): void;
+  setMouseButton(down: boolean): void;
+  getMousePosition(): MousePosition;
+  isMouseDown(): boolean;
+  isMousePressed(): boolean;
+
+  // Palettes
+  uiColors: Record<string, Color>;
+  uiFonts: Record<string, string>;
+
+  exposeTo(target: object): void;
+}
+
+export declare function uiApi(ctx2d: CanvasRenderingContext2D | null): UIApiInstance;
+
+// ---------------------------------------------------------------------------
+// Sub-module factory types (for tree-shaking imports)
+// ---------------------------------------------------------------------------
+
+export declare function materialsModule(ctx: object): object;
+export declare function primitivesModule(ctx: object): object;
+export declare function transformsModule(ctx: object): object;
+export declare function cameraModule(ctx: object): object;
+export declare function lightsModule(ctx: object): object;
+export declare function modelsModule(ctx: object): object;
+export declare function instancingModule(ctx: object): object;
+export declare function pbrModule(ctx: object): object;
+export declare function sceneModule(ctx: object): object;
+
+export declare function uiTextModule(ctx: object): object;
+export declare function uiPanelsModule(ctx: object): object;
+export declare function uiButtonsModule(ctx: object): object;
+export declare function uiWidgetsModule(ctx: object): object;
+
+// ---------------------------------------------------------------------------
+// Global cart API (injected into globalThis at runtime)
+// Augment with: declare global { ... } in your cart's .d.ts if needed.
+// ---------------------------------------------------------------------------
+
+export interface Nova64CartGlobals {
+  // 3D
+  createCube: ThreeDApiInstance['createCube'];
+  createSphere: ThreeDApiInstance['createSphere'];
+  createCylinder: ThreeDApiInstance['createCylinder'];
+  createPlane: ThreeDApiInstance['createPlane'];
+  createTorus: ThreeDApiInstance['createTorus'];
+  createCone: ThreeDApiInstance['createCone'];
+  createCapsule: ThreeDApiInstance['createCapsule'];
+  createAdvancedCube: ThreeDApiInstance['createAdvancedCube'];
+  createAdvancedSphere: ThreeDApiInstance['createAdvancedSphere'];
+  destroyMesh: ThreeDApiInstance['destroyMesh'];
+  removeMesh: ThreeDApiInstance['removeMesh'];
+  getMesh: ThreeDApiInstance['getMesh'];
+  loadModel: ThreeDApiInstance['loadModel'];
+  playAnimation: ThreeDApiInstance['playAnimation'];
+  updateAnimations: ThreeDApiInstance['updateAnimations'];
+  loadTexture: ThreeDApiInstance['loadTexture'];
+  setPosition: ThreeDApiInstance['setPosition'];
+  setRotation: ThreeDApiInstance['setRotation'];
+  setScale: ThreeDApiInstance['setScale'];
+  getPosition: ThreeDApiInstance['getPosition'];
+  getRotation: ThreeDApiInstance['getRotation'];
+  rotateMesh: ThreeDApiInstance['rotateMesh'];
+  moveMesh: ThreeDApiInstance['moveMesh'];
+  setFlatShading: ThreeDApiInstance['setFlatShading'];
+  setMeshVisible: ThreeDApiInstance['setMeshVisible'];
+  setMeshOpacity: ThreeDApiInstance['setMeshOpacity'];
+  setCastShadow: ThreeDApiInstance['setCastShadow'];
+  setReceiveShadow: ThreeDApiInstance['setReceiveShadow'];
+  setCameraPosition: ThreeDApiInstance['setCameraPosition'];
+  setCameraTarget: ThreeDApiInstance['setCameraTarget'];
+  setCameraLookAt: ThreeDApiInstance['setCameraLookAt'];
+  setCameraFOV: ThreeDApiInstance['setCameraFOV'];
+  setFog: ThreeDApiInstance['setFog'];
+  clearFog: ThreeDApiInstance['clearFog'];
+  setLightDirection: ThreeDApiInstance['setLightDirection'];
+  setLightColor: ThreeDApiInstance['setLightColor'];
+  setAmbientLight: ThreeDApiInstance['setAmbientLight'];
+  setDirectionalLight: ThreeDApiInstance['setDirectionalLight'];
+  clearScene: ThreeDApiInstance['clearScene'];
+  enablePixelation: ThreeDApiInstance['enablePixelation'];
+  enableDithering: ThreeDApiInstance['enableDithering'];
+  createPointLight: ThreeDApiInstance['createPointLight'];
+  setPointLightPosition: ThreeDApiInstance['setPointLightPosition'];
+  setPointLightColor: ThreeDApiInstance['setPointLightColor'];
+  removeLight: ThreeDApiInstance['removeLight'];
+  createInstancedMesh: ThreeDApiInstance['createInstancedMesh'];
+  setInstanceTransform: ThreeDApiInstance['setInstanceTransform'];
+  setInstanceColor: ThreeDApiInstance['setInstanceColor'];
+  finalizeInstances: ThreeDApiInstance['finalizeInstances'];
+  removeInstancedMesh: ThreeDApiInstance['removeInstancedMesh'];
+  createParticleSystem: ThreeDApiInstance['createParticleSystem'];
+  setParticleEmitter: ThreeDApiInstance['setParticleEmitter'];
+  emitParticle: ThreeDApiInstance['emitParticle'];
+  burstParticles: ThreeDApiInstance['burstParticles'];
+  updateParticles: ThreeDApiInstance['updateParticles'];
+  removeParticleSystem: ThreeDApiInstance['removeParticleSystem'];
+  getParticleStats: ThreeDApiInstance['getParticleStats'];
+  createLODMesh: ThreeDApiInstance['createLODMesh'];
+  setLODPosition: ThreeDApiInstance['setLODPosition'];
+  removeLODMesh: ThreeDApiInstance['removeLODMesh'];
+  updateLODs: ThreeDApiInstance['updateLODs'];
+  loadNormalMap: ThreeDApiInstance['loadNormalMap'];
+  setNormalMap: ThreeDApiInstance['setNormalMap'];
+  setPBRMaps: ThreeDApiInstance['setPBRMaps'];
+  raycastFromCamera: ThreeDApiInstance['raycastFromCamera'];
+  get3DStats: ThreeDApiInstance['get3DStats'];
+  getScene: ThreeDApiInstance['getScene'];
+  getCamera: ThreeDApiInstance['getCamera'];
+  getRenderer: ThreeDApiInstance['getRenderer'];
+
+  // UI
+  setFont: UIApiInstance['setFont'];
+  getFont: UIApiInstance['getFont'];
+  setTextAlign: UIApiInstance['setTextAlign'];
+  setTextBaseline: UIApiInstance['setTextBaseline'];
+  measureText: UIApiInstance['measureText'];
+  drawText: UIApiInstance['drawText'];
+  drawTextShadow: UIApiInstance['drawTextShadow'];
+  drawTextOutline: UIApiInstance['drawTextOutline'];
+  createPanel: UIApiInstance['createPanel'];
+  drawPanel: UIApiInstance['drawPanel'];
+  drawAllPanels: UIApiInstance['drawAllPanels'];
+  removePanel: UIApiInstance['removePanel'];
+  clearPanels: UIApiInstance['clearPanels'];
+  createButton: UIApiInstance['createButton'];
+  updateButton: UIApiInstance['updateButton'];
+  drawButton: UIApiInstance['drawButton'];
+  updateAllButtons: UIApiInstance['updateAllButtons'];
+  drawAllButtons: UIApiInstance['drawAllButtons'];
+  removeButton: UIApiInstance['removeButton'];
+  clearButtons: UIApiInstance['clearButtons'];
+  drawProgressBar: UIApiInstance['drawProgressBar'];
+  drawRoundedRect: UIApiInstance['drawRoundedRect'];
+  drawGradientRect: UIApiInstance['drawGradientRect'];
+  centerX: UIApiInstance['centerX'];
+  centerY: UIApiInstance['centerY'];
+  grid: UIApiInstance['grid'];
+  setMousePosition: UIApiInstance['setMousePosition'];
+  setMouseButton: UIApiInstance['setMouseButton'];
+  getMousePosition: UIApiInstance['getMousePosition'];
+  isMouseDown: UIApiInstance['isMouseDown'];
+  isMousePressed: UIApiInstance['isMousePressed'];
+  uiColors: UIApiInstance['uiColors'];
+  uiFonts: UIApiInstance['uiFonts'];
+
+  // Input (runtime/input.js)
+  key(code: string): boolean;
+  keyp(code: string): boolean;
+  btn(index: number): boolean;
+  btnp(index: number): boolean;
+
+  // 2D drawing (runtime/framebuffer.js / api-2d.js)
+  cls(color?: Color): void;
+  print(text: string, x: number, y: number, color?: Color, scale?: number): void;
+  printCentered(text: string, y: number, color?: Color, scale?: number): void;
+  line(x1: number, y1: number, x2: number, y2: number, color?: Color): void;
+  circle(x: number, y: number, r: number, color?: Color, filled?: boolean): void;
+  drawRect(x: number, y: number, w: number, h: number, color?: Color): void;
+  rgba8(r: number, g: number, b: number, a: number): Color;
+
+  // Storage (runtime/storage.js)
+  saveData(key: string, value: unknown): void;
+  loadData(key: string, fallback?: unknown): unknown;
+  deleteData(key: string): void;
+
+  // Audio (runtime/audio.js)
+  sfx(preset: string | { wave?: string; freq?: number; dur?: number; vol?: number }): void;
+}