nucleation 0.10.22 → 0.10.23

package/README.md

@@ -53,3 +53,15 @@ embedded scripting are native-only.
 ## License
 
 MIT
+
+### Renderer-only WebAssembly
+
+`import { Schematic } from "nucleation/renderer"` loads the bridge-only WASM build
+for schematic viewing and editing. Simulation, meshing and voxelization remain
+available from the main `nucleation` entry point. Each entry owns a separate WASM
+instance; import only the entry needed by a worker.
+
+Use `renderRegionsJson()` for region bounds and palettes, then
+`regionBlockIndices(name, start, count)` for owned `Uint32Array` windows of at most
+65,536 cells. Indices use x-fastest, then z, then y order. Call `clearContents()`
+when done to release schematic storage immediately.

package/Schematic.d.mts

@@ -20,6 +20,13 @@ export class Schematic {
      */
     static create(name: string): Schematic;
 
+    /**
+     * Release all block/entity storage immediately, keeping an empty valid
+     * schematic handle. JS consumers should call this when a parsed world or
+     * editing session is no longer needed instead of waiting for finalizers.
+     */
+    clearContents(): void;
+
     /**
      * Return an independent deep copy. Subsequent block, region, entity,
      * metadata, or transform changes do not affect the original.
@@ -501,6 +508,22 @@ export class Schematic {
      */
     getChunkNonAirBlocksJson(offsetX: number, offsetY: number, offsetZ: number, width: number, height: number, length: number): string;
 
+    /**
+     * Storage metadata and full block states for palette-index streaming. Region order
+     * is default first, then sorted names (highest precedence first); indices are LOCAL to each region. Bounds
+     * describe allocated storage, never tight bounds. x is fastest, then z, then y.
+     * No block buffer is cloned or serialized here.
+     */
+    renderRegionsJson(): string;
+
+    /**
+     * A bounded window of a region's dense palette indices (including air).
+     * At most 65,536 cells per call; no full-world scan, coordinate tuples, or
+     * intermediate Rust allocation. JS bindings copy the borrowed slice before
+     * returning, so callers may mutate the schematic or grow WASM memory safely.
+     */
+    regionBlockIndices(regionName: string, start: number, count: number): Uint32Array;
+
     /**
      * Split the schematic into chunks (default bottom-up strategy). Writes a
      * JSON array of `{"chunk_x", "chunk_y", "chunk_z", "blocks": [...]}` where

package/Schematic.d.ts

@@ -20,6 +20,13 @@ export class Schematic {
      */
     static create(name: string): Schematic;
 
+    /**
+     * Release all block/entity storage immediately, keeping an empty valid
+     * schematic handle. JS consumers should call this when a parsed world or
+     * editing session is no longer needed instead of waiting for finalizers.
+     */
+    clearContents(): void;
+
     /**
      * Return an independent deep copy. Subsequent block, region, entity,
      * metadata, or transform changes do not affect the original.
@@ -501,6 +508,22 @@ export class Schematic {
      */
     getChunkNonAirBlocksJson(offsetX: number, offsetY: number, offsetZ: number, width: number, height: number, length: number): string;
 
+    /**
+     * Storage metadata and full block states for palette-index streaming. Region order
+     * is default first, then sorted names (highest precedence first); indices are LOCAL to each region. Bounds
+     * describe allocated storage, never tight bounds. x is fastest, then z, then y.
+     * No block buffer is cloned or serialized here.
+     */
+    renderRegionsJson(): string;
+
+    /**
+     * A bounded window of a region's dense palette indices (including air).
+     * At most 65,536 cells per call; no full-world scan, coordinate tuples, or
+     * intermediate Rust allocation. JS bindings copy the borrowed slice before
+     * returning, so callers may mutate the schematic or grow WASM memory safely.
+     */
+    regionBlockIndices(regionName: string, start: number, count: number): Uint32Array;
+
     /**
      * Split the schematic into chunks (default bottom-up strategy). Writes a
      * JSON array of `{"chunk_x", "chunk_y", "chunk_z", "blocks": [...]}` where

package/Schematic.mjs

@@ -61,6 +61,21 @@ export class Schematic {
         }
     }
 
+    /**
+     * Release all block/entity storage immediately, keeping an empty valid
+     * schematic handle. JS consumers should call this when a parsed world or
+     * editing session is no longer needed instead of waiting for finalizers.
+     */
+    clearContents() {
+    wasm.Schematic_clear_contents(this.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
     /**
      * Return an independent deep copy. Subsequent block, region, entity,
      * metadata, or transform changes do not affect the original.
@@ -1959,6 +1974,61 @@ export class Schematic {
         }
     }
 
+    /**
+     * Storage metadata and full block states for palette-index streaming. Region order
+     * is default first, then sorted names (highest precedence first); indices are LOCAL to each region. Bounds
+     * describe allocated storage, never tight bounds. x is fastest, then z, then y.
+     * No block buffer is cloned or serialized here.
+     */
+    renderRegionsJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.Schematic_render_regions_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * A bounded window of a region's dense palette indices (including air).
+     * At most 65,536 cells per call; no full-world scan, coordinate tuples, or
+     * intermediate Rust allocation. JS bindings copy the borrowed slice before
+     * returning, so callers may mutate the schematic or grow WASM memory safely.
+     */
+    regionBlockIndices(regionName, start, count) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const regionNameSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, regionName)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 9, 4, true);
+
+        // This lifetime edge depends on lifetimes 'a
+        let aEdges = [this];
+
+
+        const result = wasm.Schematic_region_block_indices(diplomatReceive.buffer, this.ffiValue, regionNameSlice.ptr, start, count);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return new diplomatRuntime.DiplomatSlicePrimitive(wasm, diplomatReceive.buffer, "u32", aEdges).getValue().slice();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
     /**
      * Split the schematic into chunks (default bottom-up strategy). Writes a
      * JSON array of `{"chunk_x", "chunk_y", "chunk_z", "blocks": [...]}` where

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleation",
-  "version": "0.10.22",
+  "version": "0.10.23",
   "description": "A high-performance Minecraft schematic parser and utility library",
   "type": "module",
   "main": "index.mjs",
@@ -12,6 +12,10 @@
     "./design": {
       "types": "./veneer/design.d.ts",
       "default": "./veneer/design.mjs"
+    },
+    "./renderer": {
+      "types": "./renderer/index.d.ts",
+      "default": "./renderer/index.mjs"
     }
   },
   "files": [
@@ -20,7 +24,8 @@
     "*.d.mts",
     "veneer/",
     "nucleation.wasm",
-    "diplomat.config.mjs"
+    "diplomat.config.mjs",
+    "renderer/"
   ],
   "engines": {
     "node": ">=18"

package/renderer/AnimationEffect.d.mts

@@ -0,0 +1,44 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A reusable set of property tracks, modelled after Anime.js object animations.
+ */
+export class AnimationEffect {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    static create(durationMs: number): AnimationEffect;
+
+    static instant(): AnimationEffect;
+
+    static popIn(durationMs: number): AnimationEffect;
+
+    static dropIn(durationMs: number, height: number): AnimationEffect;
+
+    static dropAndPop(durationMs: number, height: number): AnimationEffect;
+
+    static spinIn(durationMs: number, turns: number): AnimationEffect;
+
+    static turntable(durationMs: number): AnimationEffect;
+
+    /**
+     * Add a two-key property tween. Property names follow Anime.js/Three.js:
+     * `x`, `y`, `z`, `rotateX`, `rotateY`, `rotateZ`, `scale`, `opacity`,
+     * `tintR/G/B/A`, and `emissiveR/G/B`.
+     */
+    addTween(propertyName: string, start: number, end: number, easingName: string): void;
+
+    /**
+     * Add a normalised keyframe (`at` in `0..=1`) to a property track.
+     */
+    addKeyframe(propertyName: string, at: number, value: number, easingName: string): void;
+
+    setRepeatForever(): void;
+}

package/renderer/AnimationEffect.d.ts

@@ -0,0 +1,44 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A reusable set of property tracks, modelled after Anime.js object animations.
+ */
+export class AnimationEffect {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    static create(durationMs: number): AnimationEffect;
+
+    static instant(): AnimationEffect;
+
+    static popIn(durationMs: number): AnimationEffect;
+
+    static dropIn(durationMs: number, height: number): AnimationEffect;
+
+    static dropAndPop(durationMs: number, height: number): AnimationEffect;
+
+    static spinIn(durationMs: number, turns: number): AnimationEffect;
+
+    static turntable(durationMs: number): AnimationEffect;
+
+    /**
+     * Add a two-key property tween. Property names follow Anime.js/Three.js:
+     * `x`, `y`, `z`, `rotateX`, `rotateY`, `rotateZ`, `scale`, `opacity`,
+     * `tintR/G/B/A`, and `emissiveR/G/B`.
+     */
+    addTween(propertyName: string, start: number, end: number, easingName: string): void;
+
+    /**
+     * Add a normalised keyframe (`at` in `0..=1`) to a property track.
+     */
+    addKeyframe(propertyName: string, at: number, value: number, easingName: string): void;
+
+    setRepeatForever(): void;
+}

package/renderer/AnimationEffect.mjs

@@ -0,0 +1,204 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const AnimationEffect_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.AnimationEffect_destroy(ptr);
+});
+
+/**
+ * A reusable set of property tracks, modelled after Anime.js object animations.
+ */
+export class AnimationEffect {
+    // Internal ptr reference:
+    #ptr = null;
+
+    // Lifetimes are only to keep dependencies alive.
+    // Since JS won't garbage collect until there are no incoming edges.
+    #selfEdge = [];
+
+    #internalConstructor(symbol, ptr, selfEdge) {
+        if (symbol !== diplomatRuntime.internalConstructor) {
+            console.error("AnimationEffect is an Opaque type. You cannot call its constructor.");
+            return;
+        }
+        this.#ptr = ptr;
+        this.#selfEdge = selfEdge;
+
+        // Are we being borrowed? If not, we can register.
+        if (this.#selfEdge.length === 0) {
+            AnimationEffect_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    static create(durationMs) {
+
+        const result = wasm.AnimationEffect_create(durationMs);
+
+        try {
+            return new AnimationEffect(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    static instant() {
+
+        const result = wasm.AnimationEffect_instant();
+
+        try {
+            return new AnimationEffect(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    static popIn(durationMs) {
+
+        const result = wasm.AnimationEffect_pop_in(durationMs);
+
+        try {
+            return new AnimationEffect(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    static dropIn(durationMs, height) {
+
+        const result = wasm.AnimationEffect_drop_in(durationMs, height);
+
+        try {
+            return new AnimationEffect(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    static dropAndPop(durationMs, height) {
+
+        const result = wasm.AnimationEffect_drop_and_pop(durationMs, height);
+
+        try {
+            return new AnimationEffect(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    static spinIn(durationMs, turns) {
+
+        const result = wasm.AnimationEffect_spin_in(durationMs, turns);
+
+        try {
+            return new AnimationEffect(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    static turntable(durationMs) {
+
+        const result = wasm.AnimationEffect_turntable(durationMs);
+
+        try {
+            return new AnimationEffect(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Add a two-key property tween. Property names follow Anime.js/Three.js:
+     * `x`, `y`, `z`, `rotateX`, `rotateY`, `rotateZ`, `scale`, `opacity`,
+     * `tintR/G/B/A`, and `emissiveR/G/B`.
+     */
+    addTween(propertyName, start, end, easingName) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const propertyNameSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, propertyName)));
+        const easingNameSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, easingName)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.AnimationEffect_add_tween(diplomatReceive.buffer, this.ffiValue, propertyNameSlice.ptr, start, end, easingNameSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Add a normalised keyframe (`at` in `0..=1`) to a property track.
+     */
+    addKeyframe(propertyName, at, value, easingName) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const propertyNameSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, propertyName)));
+        const easingNameSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, easingName)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.AnimationEffect_add_keyframe(diplomatReceive.buffer, this.ffiValue, propertyNameSlice.ptr, at, value, easingNameSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    setRepeatForever() {
+    wasm.AnimationEffect_set_repeat_forever(this.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/Autostack.d.mts

@@ -0,0 +1,43 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Free functions in the old ABI hung directly off `schematic_*`; here they get a
+ * namespacing opaque-less home via static methods on a zero-size type is not
+ * supported, so they live as static methods taking `&Schematic` explicitly.
+ */
+export class Autostack {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Detect repeating structures (region coverage). Writes a JSON array string;
+     * each element has `mode`, `vectors`, `coverage`, `region_min`/`region_max`,
+     * `cell_min`/`cell_max`, `label`.
+     */
+    static detectStructures(schematic: Schematic): string;
+
+    /**
+     * Graph-based detection: recovers diagonal lattice periods via the redstone
+     * logic graph. Writes `"[]"` for non-redstone builds. Requires the
+     * `simulation` feature; writes `"[]"` when compiled without it.
+     */
+    static detectStructuresGraph(schematic: Schematic): string;
+
+    /**
+     * Resize a 1D / diagonal structure along its period vector.
+     */
+    static resize1d(schematic: Schematic, vx: number, vy: number, vz: number, units: number): Schematic;
+
+    /**
+     * Resize a 2D structure to `n1`×`n2` cells along the two period vectors.
+     */
+    static resize2d(schematic: Schematic, v1x: number, v1y: number, v1z: number, v2x: number, v2y: number, v2z: number, n1: number, n2: number): Schematic;
+}

package/renderer/Autostack.d.ts

@@ -0,0 +1,43 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Free functions in the old ABI hung directly off `schematic_*`; here they get a
+ * namespacing opaque-less home via static methods on a zero-size type is not
+ * supported, so they live as static methods taking `&Schematic` explicitly.
+ */
+export class Autostack {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Detect repeating structures (region coverage). Writes a JSON array string;
+     * each element has `mode`, `vectors`, `coverage`, `region_min`/`region_max`,
+     * `cell_min`/`cell_max`, `label`.
+     */
+    static detectStructures(schematic: Schematic): string;
+
+    /**
+     * Graph-based detection: recovers diagonal lattice periods via the redstone
+     * logic graph. Writes `"[]"` for non-redstone builds. Requires the
+     * `simulation` feature; writes `"[]"` when compiled without it.
+     */
+    static detectStructuresGraph(schematic: Schematic): string;
+
+    /**
+     * Resize a 1D / diagonal structure along its period vector.
+     */
+    static resize1d(schematic: Schematic, vx: number, vy: number, vz: number, units: number): Schematic;
+
+    /**
+     * Resize a 2D structure to `n1`×`n2` cells along the two period vectors.
+     */
+    static resize2d(schematic: Schematic, v1x: number, v1y: number, v1z: number, v2x: number, v2y: number, v2z: number, n1: number, n2: number): Schematic;
+}