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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niranjan Devasani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NayanEngine.podspec

@@ -0,0 +1,28 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NayanEngine"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/ursnj/nayan-ui.git", :tag => "engine-v#{s.version}" }
+
+  s.source_files = "native/cpp/**/*.{h,cpp}", "native/ios/**/*.{h,m,mm}"
+  s.vendored_frameworks = "native/core/build/EngineCore.xcframework"
+  # The Rust core's audio (cpal / CoreAudio), haptics (Core Haptics) and renderer (wgpu on Metal) need
+  # these system frameworks.
+  s.frameworks = "AudioToolbox", "AVFAudio", "CoreAudio", "CoreHaptics", "Foundation", "Metal", "QuartzCore", "UIKit"
+
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/native/core/include\" \"$(PODS_TARGET_SRCROOT)/native/cpp\"",
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20"
+  }
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -1,3 +1,309 @@
-# Temporary Holding Version
+# @nayan-ui/engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@nayan-ui/engine?label=npm)](https://www.npmjs.com/package/@nayan-ui/engine) [![license](https://img.shields.io/npm/l/@nayan-ui/engine)](#license)
+
+A fast 3D game engine for **React** and **React Native**. One TypeScript API on one Rust core: rendering (wgpu), physics (Rapier), skeletal and tween animation, particles, audio, haptics and 2D drawing.
+
+**[Documentation](https://www.nayanui.com/game-engine)** · **[First game tutorial](https://www.nayanui.com/game-engine/first-game)** · **[API reference](https://www.nayanui.com/game-engine/api-reference)** · **[Guide for AI agents](https://www.nayanui.com/game-engine/agent-guide)**
+
+- **Native speed on phones.** Rendering, physics, animation, culling and audio mixing run in Rust. On iOS and Android the game loop follows the display's clock, and frames are drawn on the engine's own render thread, so your JavaScript never waits on the GPU.
+- **Small API.** `useWorld` + `GameView` is a complete scene. Spawn entities, move them, animate them: the engine steps, draws and cleans up.
+- **Fast loading.** Images, glTF models, fonts and sounds decode on native background threads, and procedural meshes can be cached on disk between launches.
+- **Same code on the web.** The core compiles to WebAssembly and draws with WebGPU, falling back to WebGL2.
+
+| Platform    | Renders with                   | Needs                                                     |
+| ----------- | ------------------------------ | --------------------------------------------------------- |
+| iOS         | Metal                          | A development or store build (Expo Go doesn't include it) |
+| Android     | Vulkan or OpenGL ES            | `minSdkVersion` 26, a development or store build          |
+| Web (React) | WebAssembly + WebGPU or WebGL2 | A modern browser over HTTPS or localhost                  |
+
+## Install
+
+```sh
+npm install @nayan-ui/engine
+```
+
+Peer dependencies: `react`, plus `react-native` for apps. `expo-asset` is optional and only needed to load bundled files with `require(...)` in Expo.
+
+### React Native (Expo)
+
+1. Let Metro bundle 3D models, in `metro.config.js`:
+
+   ```js
+   config.resolver.assetExts.push('glb', 'gltf');
+   ```
+
+2. Target Android 8.0 (API 26) or newer (with `expo-build-properties`), and allow vibration for haptics, in `app.json`:
+
+   ```json
+   {
+     "expo": {
+       "android": { "permissions": ["android.permission.VIBRATE"] },
+       "plugins": [["expo-build-properties", { "android": { "minSdkVersion": 26 } }]]
+     }
+   }
+   ```
+
+3. Make a development build: `npx expo run:ios` / `npx expo run:android` (or an EAS build). The engine ships prebuilt native libraries, so no Rust toolchain is needed.
+
+Bare React Native apps autolink the same way: run `pod install` in `ios/` and set `minSdkVersion` 26 in Gradle.
+
+Guard screens for builds without the native module (for example Expo Go) with `isEngineAvailable`:
+
+```tsx
+import { isEngineAvailable } from '@nayan-ui/engine';
+
+if (!isEngineAvailable) return <Text>This screen needs a development build.</Text>;
+```
+
+### React (web)
+
+Nothing to configure. `useWorld` loads the WebAssembly core for you; if you create worlds yourself, `await warmUpEngine()` first.
+
+## Quick start
+
+A complete scene that works unchanged on every platform:
+
+```tsx
+import { GameView, useWorld } from '@nayan-ui/engine';
+
+export function BouncingBall() {
+  const world = useWorld(100, (w) => {
+    w.spawn({ mesh: 'plane', scale: [20, 1, 20], color: '#4C9A4C', physics: 'fixed' });
+    w.spawn({ mesh: 'sphere', position: [0, 5, 0], color: '#3399FF', physics: { type: 'dynamic', bounce: 0.6 } });
+  });
+  return world && <GameView source={world} camera={{ eye: [0, 4, 8], target: [0, 0, 0], fov: 1 }} style={{ flex: 1 }} />;
+}
+```
+
+`useWorld` warms the engine up, creates the world (100 entity slots), runs your setup and disposes it on unmount. `GameView` draws it and steps it every frame.
+
+## The five rules
+
+1. **Own** a world with `useWorld(capacity, setup)`, or create it yourself after `await warmUpEngine()` and `dispose()` it on unmount.
+2. **Play** in `GameView`'s `onUpdate(dt)`: read input, move things, spawn. The world is stepped for you right after (call `world.update(dt)` yourself only to step it earlier or with another `dt`).
+3. **Keep handles**: `spawn` returns an `Entity`; change it with `set`, remove it with `despawn`.
+4. **Batch per-frame moves** in `world.transforms`: they are applied in one native call when the world steps (`flush()` yourself before reading positions).
+5. **Don't track disposal yourself**: check `world.isDisposed`. Cleanup calls are safe no-ops after `dispose()`.
+
+## Performance
+
+The engine is built so that a game written the obvious way stays smooth on mid-range Android phones.
+
+- **Display clock and render thread (iOS and Android).** The display's vsync (`CADisplayLink` on iOS, `Choreographer` on Android) asks for each frame at 60 Hz. `onUpdate` steps the game and hands a copy of the frame to a native render thread, which culls, submits and presents it. The JS thread never waits on the GPU, and a frame that is still waiting when a newer one arrives is replaced, not queued. The clock stops while the app is in the background or the view is off screen. On the web, `requestAnimationFrame` drives the same loop.
+- **Culling in Rust.** Everything outside the camera's view (and outside the light's box for shadows) is skipped every frame, so open levels and long tracks only pay for what is on screen. Don't cull scenery in JS.
+- **Automatic quality.** `quality="auto"` (the default) starts at `high` and steps down (shadow detail first, then anti-aliasing, resolution last) only while the device can't keep up. `onStats` reports fps, update and render time, the quality chosen and the graphics backend.
+- **Background loading.** `loadTexture`, `loadModel`, `loadFont` and `audio.load` decode on native threads in parallel, and meshes are registered with the renderer inside Rust.
+- **Work between frames.** `afterNextFrame(fn)` runs `fn` right after the next frame leaves, so you can spread long setup work (map generation, mesh building) over several frames behind a loading screen.
+- **Cached procedural assets.** `ProceduralCache` saves built geometry on disk keyed by a recipe, so later launches restore it instead of rebuilding; `peek(key)` returns a saved value without building anything.
+
+Keep these habits:
+
+- Build meshes once, at module scope or behind a cache, and spawn new entities from them. Mesh ids are app-wide and never freed (`getMeshIdLimit()` tells you how many there are), so never create a mesh per spawn or per frame.
+- Move many things each frame through `world.transforms` and the `out` arguments of queries, which allocate nothing.
+- Keep long one-off jobs out of gameplay frames: a single slow frame stalls Android's Hermes far longer than desktop JavaScript suggests.
+
+## Common tasks
+
+**Physics and collisions**
+
+```ts
+const ball = world.spawn({ mesh: 'sphere', position: [0, 5, 0], physics: { type: 'dynamic', bounce: 0.6 } });
+const coin = world.spawn({ mesh: 'cylinder', position: [2, 1, 0], physics: { type: 'fixed', sensor: true } });
+world.impulse(ball, [0, 4, 0]);
+world.forEachCollision((a, b, { started }) => {
+  if (started && (a === coin || b === coin)) world.despawn(coin);
+});
+```
+
+**Animation** (runs in Rust and returns a Promise)
+
+```ts
+await world.animate(piece, { position: [2, 0, 3] }, { duration: 0.25, easing: 'back' });
+world.animate(star, { scale: 1.2 }, { repeat: 'forever', yoyo: true });
+```
+
+**Skinned characters**: glTF clips play natively, with crossfades
+
+```ts
+const hero = await loadModel(require('./hero.glb'));
+console.log(hero.animations.map((clip) => clip.name)); // e.g. ['idle', 'walk', 'run']
+const player = world.spawn({ mesh: hero });
+world.playClip(player, 'idle', { speed: 0 }); // hold the first pose on the ready screen
+world.playClip(player, 'run', { fade: 0.2 }); // crossfade when play starts
+world.stopClip(player);
+```
+
+`world.sampleSkinnedVertices` reads chosen vertices of the next pose (for planting feet on uneven ground) without skinning the whole character in JS.
+
+**Ready-made effects**
+
+```ts
+import { effects } from '@nayan-ui/engine';
+
+effects.confetti(world, {
+  position: [0, 2, 0],
+  colors: ['#FF4D4D', '#FFD933'],
+  size: 0.12,
+  speed: 6,
+  count: 40,
+  lifetime: 1.2,
+  gravity: -6
+});
+effects.dust(world, { position: [0, 0, 0], color: [0.8, 0.75, 0.65, 0.6], size: 0.3, speed: 1.5, count: 6, lifetime: 0.5 });
+await effects.pop(world, piece, { scale: 1, color: '#FF4D4D' }); // swell, flash white, shrink away
+world.despawn(piece);
+```
+
+Also available: `sparkle`, `shatter`, `splash`, `sparks`, `explosion` and `flash`.
+
+**Per-frame movement without allocations**
+
+```ts
+import { type MutableQuat, quat } from '@nayan-ui/engine';
+
+const turn: MutableQuat = [0, 0, 0, 1];
+const at: [number, number, number] = [0, 0, 0];
+
+function onUpdate(dt: number) {
+  world.position(player, at); // queries can fill an `out` array
+  quat.y(heading, turn);
+  world.transforms.transform(car, carX, 0, carZ, turn[0], turn[1], turn[2], turn[3]); // applied in one native call as the world steps
+}
+```
+
+**Models built in code**: bake a shape once, spawn it many times
+
+```ts
+import { createShape, lathe, merge, tube } from '@nayan-ui/engine';
+
+// Built once per app (after warmUpEngine), at module scope.
+const vase = createShape(
+  merge([
+    {
+      geometry: lathe(
+        [
+          [0, 0],
+          [0.4, 0.1],
+          [0.25, 0.8],
+          [0.3, 1]
+        ],
+        { segments: 24 }
+      )
+    },
+    {
+      geometry: tube(
+        [
+          [0.3, 0.9, 0],
+          [0.5, 0.7, 0],
+          [0.3, 0.5, 0]
+        ],
+        { radius: 0.04 }
+      ),
+      color: [0.5, 0.25, 0.1]
+    } // part colors are 0..1 tuples
+  ])
+);
+world.spawn({ mesh: vase, color: '#C8763A' });
+```
+
+Also available: `extrude`, `loft`, `block`, `ellipsoid`, `parametricSurface`, `Solid` and `shapeGeometry` for the built-in shapes.
+
+**Score, lives and timers**
+
+```ts
+world.scoreboard.handlers = { onTimeUp: () => endGame('lose') }; // the game's rules
+const stopListening = world.scoreboard.listen({ onScore: setScore, onSecond: setTime }); // UI follows along
+world.scoreboard.reset(3, 60); // 3 lives and a stopped 60 s countdown for the ready screen
+world.scoreboard.resume(); // Start
+world.scoreboard.add(10);
+const timer = world.after(0.5, spawnWave); // game time: pauses with the game
+world.cancelTimer(timer);
+```
+
+**Flat boards and puzzles**: `frontLight` keeps camera-facing surfaces at their exact color
+
+```tsx
+<GameView source={world} camera={{ eye: [0, 0, 50], target: [0, 0, 0], fov: 1, ortho: 10 }} light={frontLight([-0.4, 0.6, 1], 0.5)} />
+```
+
+**Input**
+
+```tsx
+<GameView
+  source={world}
+  onTap={(x, y) => {
+    const hit = world.pick(x, y);
+    if (hit) world.animate(hit.entity, { scale: 1.2 }, { yoyo: true, repeat: 1 });
+  }}
+  onSwipe={(direction) => move(direction)}
+  onDrag={({ phase, x, y }) => drag(phase, x, y)}
+/>
+```
+
+`onLongPress`, `onPinch`, the on-screen `Joystick` and `createKeyboardInput` (web) cover other controls.
+
+**Models, textures, text, sound and haptics**
+
+```ts
+import { audio, haptics, loadFont, loadModel, loadTexture } from '@nayan-ui/engine';
+
+const car = await loadModel(require('./car.glb'), { fit: 2 }); // or a URL string on the web
+const crate = await loadTexture(require('./crate.png'));
+const font = await loadFont(require('./Inter-Bold.ttf'));
+world.spawn({ mesh: car, position: [0, 0, 0] });
+world.spawn({ mesh: 'cube', texture: crate });
+world.spawn({ text: '2048', font, position: [0, 2, 0], scale: 0.5 });
+
+const sfx = audio.load({ coin: require('./coin.wav') });
+sfx.play('coin');
+haptics.impact(0.5);
+audio.enabled = settings.sounds; // respect the player's preferences
+haptics.enabled = settings.haptics;
+```
+
+**Colors** are CSS strings (`'#FF4757'`, `'rgba(0, 0, 0, 0.5)'`) or linear 0..1 tuples (`[1, 0.3, 0.3]`; channels above 1 glow) for entities, animations, particles, lights and the background. Vertex colors baked into geometry are tuples. `toColor('#FF4757')` converts a CSS color when you need the numbers.
+
+**Drawing**: a native paint canvas, also usable as a live texture inside games
+
+```tsx
+import { DrawingCanvas, DrawingDocument } from '@nayan-ui/engine';
+
+const paper = new DrawingDocument(512, 512);
+paper.setBrush({ brushType: 'MARKER', color: '#e53935', width: 12, opacity: 1 });
+<DrawingCanvas document={paper} mode="draw" />;
+world.spawn({ mesh: 'plane', texture: paper.texture() }); // paint on a 3D object
+```
+
+Drawings save as SVG paths and export transparent PNG snapshots.
+
+## Troubleshooting
+
+| Symptom                                         | Fix                                                                                                      |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `isEngineAvailable` is `false`                  | You're in Expo Go or a build made before installing the engine: make a new development build.            |
+| `.glb` files fail to bundle                     | Add `glb` and `gltf` to Metro's `assetExts`.                                                             |
+| Android build fails on `minSdkVersion`          | Set it to 26 or higher.                                                                                  |
+| An Android screenshot of the game view is blank | The engine draws into a `SurfaceView`: use `captureScreen(..., { handleGLSurfaceViewOnAndroid: true })`. |
+| Out of mesh ids                                 | A mesh is being created per spawn or per frame: build it once and reuse it (`getMeshIdLimit()`).         |
+
+## Learn more
+
+| Topic                                 | Guide                                                                                                          |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Build a complete game step by step    | [First game](https://www.nayanui.com/game-engine/first-game)                                                        |
+| Copy-paste solutions                  | [Recipes](https://www.nayanui.com/game-engine/recipes)                                                              |
+| Worlds, entities, rotations, disposal | [World & entities](https://www.nayanui.com/game-engine/world-entities)                                              |
+| Effects and particles                 | [Effects](https://www.nayanui.com/game-engine/particles)                                                            |
+| Procedural meshes and modelling       | [Geometry](https://www.nayanui.com/game-engine/procedural-geometry)                                                 |
+| Drawing and painting                  | [Drawing](https://www.nayanui.com/game-engine/drawing)                                                              |
+| Performance and caching               | [Performance](https://www.nayanui.com/game-engine/cache-performance)                                                |
+| Coding agents                         | [Agent guide](https://www.nayanui.com/game-engine/agent-guide) · [engine.json](https://www.nayanui.com/engine.json) |
+
+## License
+
+MIT © [Niranjan Devasani](https://github.com/ursnj)
+
+---
+
+Made with ❤️ by [Niranjan Reddy Devasani](https://github.com/ursnj)

package/lib/module/assets/AssetBytesCache.js

@@ -0,0 +1,76 @@
+"use strict";
+
+import { cacheGeneration } from "./CacheGeneration.js";
+import { readPersistentAsset, removePersistentAsset, writePersistentAsset } from './storage';
+// Decoded resources own their lifetime. Only temporary download bytes are evictable.
+const BUDGET = 16 * 1024 * 1024;
+const MAX_ENTRIES = 128;
+const pending = new Map();
+const retained = new Map();
+let used = 0;
+
+/** Share concurrent requests across loader variants; failed requests can always be retried. */
+export function assetBytes(key, load) {
+  const bytes = retained.get(key);
+  if (bytes) {
+    retained.delete(key);
+    retained.set(key, bytes);
+    return Promise.resolve(bytes);
+  }
+  const existing = pending.get(key);
+  if (existing) return existing;
+  const epoch = cacheGeneration();
+  const request = Promise.resolve().then(async () => {
+    let saved = null;
+    try {
+      saved = await readPersistentAsset(key);
+    } catch {
+      /* Denied/corrupt storage is a miss. */
+    }
+    if (saved && epoch === cacheGeneration()) return saved;
+    const value = await load();
+    if (epoch === cacheGeneration()) {
+      // Await only the file write, never permission requests. Callers can rely on a completed load being saved.
+      try {
+        await writePersistentAsset(key, value);
+      } catch {
+        /* Keep existing records on quota/disk-full failures. */
+      }
+    }
+    return value;
+  }).then(value => {
+    if (epoch === cacheGeneration() && value.byteLength <= BUDGET) {
+      retained.set(key, value);
+      used += value.byteLength;
+      while (used > BUDGET || retained.size > MAX_ENTRIES) {
+        const oldest = retained.keys().next().value;
+        used -= retained.get(oldest).byteLength;
+        retained.delete(oldest);
+      }
+    }
+    return value;
+  }).finally(() => {
+    if (pending.get(key) === request) pending.delete(key);
+  });
+  pending.set(key, request);
+  return request;
+}
+
+/** A decoder rejected the payload: a later load must fetch fresh bytes, not replay bad data. */
+export function forgetAssetBytes(key) {
+  if (key === undefined) return;
+  void removePersistentAsset(key).catch(() => {});
+  const bytes = retained.get(key);
+  if (bytes) {
+    used -= bytes.byteLength;
+    retained.delete(key);
+  }
+}
+
+/** Clearing disk must also prevent an earlier request from retaining its old bytes. */
+export function clearAssetBytes() {
+  retained.clear();
+  pending.clear();
+  used = 0;
+}
+//# sourceMappingURL=AssetBytesCache.js.map

package/lib/module/assets/AssetCache.js

@@ -0,0 +1,19 @@
+"use strict";
+
+import { clearAssetBytes } from "./AssetBytesCache.js";
+import { advanceCacheGeneration } from "./CacheGeneration.js";
+import { clearPersistentStorage } from './storage';
+
+/**
+ * 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 async function clearAssetCache() {
+  advanceCacheGeneration();
+  clearAssetBytes();
+  await clearPersistentStorage();
+}
+//# sourceMappingURL=AssetCache.js.map

package/lib/module/assets/AssetLoader.js

@@ -0,0 +1,52 @@
+"use strict";
+
+import NativeEngine from '../native/NativeNayanEngine';
+import { prepareEngine } from '../native/prepare';
+import { forgetAssetBytes } from "./AssetBytesCache.js";
+import { assetUri, loadAssetBytes } from './source';
+
+/** Shared session handles; source-byte persistence stays in AssetBytesCache and Rust. */
+export class AssetLoader {
+  loads = new Map();
+  constructor(name) {
+    this.name = name;
+  }
+  load(source, decode, variant = []) {
+    let uri;
+    try {
+      uri = assetUri(source);
+      if (!uri) throw new Error("couldn't resolve the asset source");
+    } catch (cause) {
+      return Promise.reject(this.error(String(source), cause));
+    }
+    // Tuple encoding prevents a URI containing separators from colliding with loader options.
+    const key = JSON.stringify([uri, ...variant]);
+    const existing = this.loads.get(key);
+    if (existing) return existing;
+    const pending = Promise.resolve().then(() => prepareEngine()).then(async () => {
+      if (!NativeEngine) throw new Error('the engine core is not linked into this build');
+      const {
+        bytes
+      } = await loadAssetBytes(source);
+      try {
+        return await decode(NativeEngine, bytes);
+      } catch (cause) {
+        // Only rejected payloads invalidate saved bytes. Initialization/network failures don't.
+        forgetAssetBytes(uri);
+        throw cause;
+      }
+    }).catch(cause => {
+      this.loads.delete(key);
+      throw this.error(uri, cause);
+    });
+    this.loads.set(key, pending);
+    return pending;
+  }
+  error(source, cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`${this.name}: couldn't load ${source}: ${message}`, {
+      cause
+    });
+  }
+}
+//# sourceMappingURL=AssetLoader.js.map

package/lib/module/assets/CacheGeneration.js

@@ -0,0 +1,7 @@
+"use strict";
+
+// Operations started before an explicit clear may finish for their caller, but cannot refill storage.
+let generation = 0;
+export const cacheGeneration = () => generation;
+export const advanceCacheGeneration = () => ++generation;
+//# sourceMappingURL=CacheGeneration.js.map

package/lib/module/assets/IndexedDbCache.web.js

@@ -0,0 +1,149 @@
+"use strict";
+
+// Browser I/O only. Rust owns cache keys, record validation, geometry and the warm-memory budget.
+const DATABASE = 'nayan-engine-assets-v1';
+function complete(transaction) {
+  return new Promise((resolve, reject) => {
+    transaction.oncomplete = () => resolve();
+    transaction.onabort = () => reject(transaction.error ?? new Error('Asset storage transaction aborted'));
+    transaction.onerror = () => reject(transaction.error ?? new Error('Asset storage transaction failed'));
+  });
+}
+function result(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('Asset storage request failed'));
+  });
+}
+export class IndexedDbCache {
+  tail = Promise.resolve();
+  pending = new Set();
+  generation = 0;
+  clearOperation = Promise.resolve();
+  constructor(database) {
+    this.database = database;
+    database.onversionchange = () => database.close();
+  }
+  static open() {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let request;
+      try {
+        request = indexedDB.open(DATABASE, 1);
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      request.onupgradeneeded = () => {
+        try {
+          const db = request.result;
+          db.createObjectStore('records');
+          db.createObjectStore('geometry').createIndex('writtenAt', 'writtenAt');
+        } catch {
+          request.transaction?.abort();
+        }
+      };
+      request.onsuccess = () => {
+        if (settled) {
+          request.result.close();
+          return;
+        }
+        settled = true;
+        resolve(new IndexedDbCache(request.result));
+      };
+      request.onerror = () => {
+        settled = true;
+        reject(request.error ?? new Error('Asset database unavailable'));
+      };
+      request.onblocked = () => {
+        settled = true;
+        reject(new Error('Another tab blocked the asset database upgrade'));
+      };
+    });
+  }
+  enqueue(operation) {
+    const task = this.tail.then(operation);
+    this.pending.add(task);
+    this.tail = task.catch(() => {}); // A failed write must not prevent a later clear/write.
+    void task.then(() => this.pending.delete(task), () => this.pending.delete(task));
+    return task;
+  }
+  /** The Uint8Array is an owned copy made by Rust, never a view into growable WASM memory. */
+  write(name, bytes, geometry) {
+    const epoch = this.generation;
+    return this.enqueue(async () => {
+      if (epoch !== this.generation) return;
+      const transaction = this.database.transaction(['records', 'geometry'], 'readwrite');
+      const saved = complete(transaction);
+      try {
+        transaction.objectStore('records').put(bytes, name);
+        if (geometry) transaction.objectStore('geometry').put({
+          bytes: bytes.byteLength,
+          writtenAt: Date.now()
+        }, name);
+      } catch (error) {
+        transaction.abort();
+        await saved.catch(() => {});
+        throw error;
+      }
+      await saved;
+    });
+  }
+  async read(name) {
+    await this.tail;
+    const transaction = this.database.transaction('records', 'readonly');
+    const finished = complete(transaction);
+    const value = await Promise.all([result(transaction.objectStore('records').get(name)), finished]);
+    const bytes = value[0];
+    return bytes instanceof Uint8Array ? bytes : undefined;
+  }
+  remove(name) {
+    return this.enqueue(async () => {
+      const transaction = this.database.transaction(['records', 'geometry'], 'readwrite');
+      const finished = complete(transaction);
+      transaction.objectStore('records').delete(name);
+      transaction.objectStore('geometry').delete(name);
+      await finished;
+    });
+  }
+  clear() {
+    this.generation++; // Cancel queued pre-clear writes; an active transaction finishes before clear.
+    this.clearOperation = this.enqueue(async () => {
+      const transaction = this.database.transaction(['records', 'geometry'], 'readwrite');
+      const finished = complete(transaction);
+      transaction.objectStore('records').clear();
+      transaction.objectStore('geometry').clear();
+      await finished;
+    });
+    return this.clearOperation;
+  }
+  flush() {
+    return Promise.all([...this.pending]).then(() => undefined);
+  }
+  cleared() {
+    return this.clearOperation;
+  }
+
+  /** Read recent geometry only. Large source files remain in IndexedDB until requested by a loader. */
+  warm(canFit, restore) {
+    const transaction = this.database.transaction(['records', 'geometry'], 'readonly');
+    const finished = complete(transaction);
+    const cursor = transaction.objectStore('geometry').index('writtenAt').openCursor(null, 'prev');
+    let scanned = 0;
+    cursor.onsuccess = () => {
+      const current = cursor.result;
+      if (!current || !canFit(0) || ++scanned > 4096) return;
+      const metadata = current.value;
+      if (typeof current.primaryKey === 'string' && metadata !== null && typeof metadata === 'object' && Number.isSafeInteger(metadata.bytes) && metadata.bytes > 0 && canFit(metadata.bytes)) {
+        const name = current.primaryKey;
+        const record = transaction.objectStore('records').get(name);
+        record.onsuccess = () => {
+          if (record.result instanceof Uint8Array && record.result.byteLength === metadata.bytes && canFit(record.result.byteLength)) restore(name, record.result);
+        };
+      }
+      current.continue();
+    };
+    return finished;
+  }
+}
+//# sourceMappingURL=IndexedDbCache.web.js.map