@tty-pt/islet 0.0.0-stage → 1.3.1

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, tty-pt
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tty-pt/libislet/main/assets/logo.png" alt="@tty-pt/islet logo" width="220" />
+</p>
 
-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.
+# @tty-pt/islet
+
+[![npm version](https://img.shields.io/badge/npm-v0.1.0-CB3837?logo=npm)](#)
+[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD--2--Clause-blue)](#)
+[![TypeScript Ready](https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript)](#)
+[![Node.js Native](https://img.shields.io/badge/Node.js-N--API-339933?logo=node.js)](#)
+[![WebAssembly](https://img.shields.io/badge/WebAssembly-Reactor-654FF0?logo=webassembly)](#)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success)](#)
+
+> Universal Node.js and Browser bindings for **`libislet`**, the high-performance C99 spatial indexing engine and Morton Z-order curve coordinate mapper. Represents the canonical **Space Axis** in the Corm Recall Kernel.
+
+---
+
+## 1. Quickstart
+
+```bash
+npm install @tty-pt/islet
+```
+
+```typescript
+import { encodeMorton2D, decodeMorton2D, SpatialIndex } from "@tty-pt/islet";
+
+// 1. Map 2D coordinates to 64-bit Morton code preserving spatial locality
+const code = encodeMorton2D(100, 200);
+console.log("Morton code:", code);
+
+// 2. Decode back to original coordinates
+const { x, y } = decodeMorton2D(code);
+console.log(`Decoded: (${x}, ${y})`); // (100, 200)
+
+// 3. Spatial entity indexing & bounding box range queries
+const index = new SpatialIndex("./floorplan.islet");
+index.put(15, 25, 101 /* Desk 101 */);
+index.put(40, 50, 102 /* Desk 102 */);
+
+const deskId = index.get(15, 25); // 101
+```
+
+---
+
+## 2. Practical Use Cases
+
+- **Coworking & Blueprint Seat Selection**: Spatial neighbor calculations and coordinate lookup for desk and office blueprints.
+- **Canvas & Viewport Culling**: Efficiently find and render only visible entities within a viewport bounding box at 120 FPS.
+- **Geofencing & Proximity Queries**: Fast 1D range queries over 2D/3D coordinate spaces via Morton space-filling curves.
+
+---
+
+## 3. JavaScript / TypeScript API Reference
+
+### `encodeMorton2D(x: number, y: number): bigint | number`
+Interleaves the bits of 2D coordinates `(x, y)` into a 64-bit Morton Z-order curve index. **Executes strictly in compiled WebAssembly / C**, preserving spatial locality for 1D database indexes.
+
+### `decodeMorton2D(code: bigint | number): { x: number, y: number }`
+Reconstructs the original 2D coordinates `(x, y)` from a 64-bit Morton code strictly via WebAssembly.
+
+### `SpatialIndex`
+Spatial bounding-box and coordinate lookup index:
+* `constructor(filePath?: string, dbName?: string)`: Opens database or creates in-memory index.
+* `.put(x: number, y: number, ref: number): boolean`: Associates 2D coordinate `(x, y)` with entity reference `ref`.
+* `.get(x: number, y: number): number | null`: Retrieves entity reference at exact coordinate.
+* `.searchBox(minX: number, minY: number, maxX: number, maxY: number): Array<{ x: number, y: number, ref: number }>`: Range query returning all entities within the axis-aligned bounding box.
+* `.close(): void`: Closes database handle.
+
+### `getIsletWasm(): WebAssembly.Instance`
+Returns the WebAssembly instance loaded on the Stele shared-memory substrate.
+
+---
+
+## 4. Dual-Engine Runtime
+
+- **Node.js**: Native C99 N-API addon (`build/Release/islet_node.node`) with hardware bitwise popcount/spread instructions.
+- **Browser & Edge**: Precompiled `dist/islet.wasm` reactor with zero native compilation prerequisites.
+
+---
+
+## 4. C Development Headers via NPM
+
+```makefile
+CFLAGS += -I./node_modules/@tty-pt/islet/include
+LDLIBS += -lislet
+```
+
+---
+
+## 5. Building from Source
+
+```bash
+make npm-build    # Compiles native addon and WASM reactor
+make npm-test     # Runs verification test suite
+```
+
+## License
+
+BSD 2-Clause License. Copyright (c) 2026, tty-pt.

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export declare function encodeMorton2D(x: number, y: number): bigint;
+export declare function decodeMorton2D(code: bigint): { x: number; y: number };
+export declare function encodeMorton3D(x: number, y: number, z: number): bigint;
+export declare function decodeMorton3D(code: bigint): { x: number; y: number; z: number };
+
+export declare class SpatialIndex {
+  constructor(filePath?: string, dbName?: string);
+  put(x: number, y: number, ref: number): boolean;
+  get(x: number, y: number): number | null;
+  searchBox(minX: number, minY: number, maxX: number, maxY: number): number[];
+}
+
+export declare class IsletSpatialAxis {
+  readonly name: string;
+  constructor(filePath?: string, dbName?: string);
+  registerPoint(ref: number, x: number, y: number): void;
+  fill(params: { minX: number; minY: number; maxX: number; maxY: number }): number[];
+}

package/dist/index.js

@@ -0,0 +1,110 @@
+import { loadWasmModule, loadNativeAddon, getSubstrate } from "@tty-pt/stele";
+
+const nativeBinding = loadNativeAddon(import.meta.url, "islet");
+let wasmInstance = null;
+
+export function getIsletWasm() {
+  if (wasmInstance) return wasmInstance;
+  wasmInstance = loadWasmModule(new URL("./islet.wasm", import.meta.url));
+  return wasmInstance;
+}
+
+/**
+ * Encode 2D point (x, y) into 64-bit Morton Z-order code strictly via WebAssembly
+ */
+export function encodeMorton2D(x, y) {
+  if (nativeBinding && nativeBinding.encode2D) {
+    return nativeBinding.encode2D(x, y);
+  }
+  const wasm = getIsletWasm();
+  return wasm.exports.islet_wasm_encode2d(x, y);
+}
+
+/**
+ * Decode 64-bit Morton Z-order code into 2D point { x, y } strictly via WebAssembly
+ */
+export function decodeMorton2D(code) {
+  if (nativeBinding && nativeBinding.decode2D) {
+    return nativeBinding.decode2D(code);
+  }
+  const wasm = getIsletWasm();
+  const ptr = wasm.exports.malloc(8);
+  wasm.exports.islet_wasm_decode2d(BigInt(code), ptr);
+  const arr = new Int32Array(getSubstrate().memory.buffer, ptr, 2);
+  const res = { x: arr[0], y: arr[1] };
+  wasm.exports.free(ptr);
+  return res;
+}
+
+/**
+ * Encode 3D point (x, y, z) into 64-bit Morton Z-order code strictly via WebAssembly
+ */
+export function encodeMorton3D(x, y, z) {
+  const wasm = getIsletWasm();
+  return wasm.exports.islet_wasm_encode3d(x, y, z);
+}
+
+/**
+ * Decode 64-bit Morton Z-order code into 3D point { x, y, z } strictly via WebAssembly
+ */
+export function decodeMorton3D(code) {
+  const wasm = getIsletWasm();
+  const ptr = wasm.exports.malloc(12);
+  wasm.exports.islet_wasm_decode3d(BigInt(code), ptr);
+  const arr = new Int32Array(getSubstrate().memory.buffer, ptr, 3);
+  const res = { x: arr[0], y: arr[1], z: arr[2] };
+  wasm.exports.free(ptr);
+  return res;
+}
+
+/**
+ * SpatialIndex: 2D Point and Bounding-Box Index
+ */
+export class SpatialIndex {
+  constructor(filePath = "", dbName = "islet") {
+    this.filePath = filePath;
+    this.dbName = dbName;
+    this.handle = null;
+    this._memPoints = new Map();
+
+    if (nativeBinding && nativeBinding.open) {
+      this.handle = nativeBinding.open(this.filePath, this.dbName);
+    }
+  }
+
+  put(x, y, ref) {
+    if (nativeBinding && this.handle) {
+      return nativeBinding.put2D(this.handle, x, y, ref);
+    }
+    const code = String(encodeMorton2D(x, y));
+    this._memPoints.set(code, ref);
+    return true;
+  }
+
+  get(x, y) {
+    if (nativeBinding && this.handle) {
+      return nativeBinding.get2D(this.handle, x, y);
+    }
+    const code = String(encodeMorton2D(x, y));
+    return this._memPoints.get(code) || null;
+  }
+
+  searchBox(minX, minY, maxX, maxY) {
+    const results = [];
+    for (const [code, ref] of this._memPoints.entries()) {
+      const pt = decodeMorton2D(BigInt(code));
+      if (pt.x >= minX && pt.x <= maxX && pt.y >= minY && pt.y <= maxY) {
+        results.push({ x: pt.x, y: pt.y, ref });
+      }
+    }
+    return results;
+  }
+
+  close() {
+    if (nativeBinding && this.handle) {
+      nativeBinding.close(this.handle);
+      this.handle = null;
+    }
+    this._memPoints.clear();
+  }
+}