nucleation 0.4.0 → 0.5.0

package/BuildAnimation.d.ts

@@ -20,6 +20,18 @@ export class BuildAnimation {
 
     static create(name: string): BuildAnimation;
 
+    /**
+     * Clone an existing schematic into one animation group. Entity-only
+     * schematics are supported; overlapping block/entity integer positions
+     * are rejected rather than silently dropping a model.
+     */
+    static fromSchematic(schematic: Schematic): BuildAnimation;
+
+    /**
+     * Apply one effect to every existing animation group.
+     */
+    animateAll(effect: AnimationEffect): void;
+
     setDefaultEffect(effect: AnimationEffect): void;
 
     /**

package/BuildAnimation.mjs

@@ -61,6 +61,44 @@ export class BuildAnimation {
         }
     }
 
+    /**
+     * Clone an existing schematic into one animation group. Entity-only
+     * schematics are supported; overlapping block/entity integer positions
+     * are rejected rather than silently dropping a model.
+     */
+    static fromSchematic(schematic) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.BuildAnimation_from_schematic(diplomatReceive.buffer, schematic.ffiValue);
+
+        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 BuildAnimation(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Apply one effect to every existing animation group.
+     */
+    animateAll(effect) {
+    wasm.BuildAnimation_animate_all(this.ffiValue, effect.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
     setDefaultEffect(effect) {
     wasm.BuildAnimation_set_default_effect(this.ffiValue, effect.ffiValue);
 

package/RenderConfig.d.ts

@@ -1,4 +1,5 @@
 // generated by diplomat-tool
+import type { NucleationError } from "./NucleationError"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 
@@ -52,6 +53,16 @@ export class RenderConfig {
      */
     setFov(fov: number): void;
 
+    /**
+     * Set the world-space directional light and its non-negative intensity.
+     */
+    setDirectionalLight(x: number, y: number, z: number, intensity: number): void;
+
+    /**
+     * Set the unlit floor for non-HDRI rendering, in `0..=1`.
+     */
+    setAmbientLight(ambient: number): void;
+
     /**
      * Set a solid RGBA clear color (linear 0.0–1.0). Alpha < 1.0 yields a
      * transparent PNG. Ignored when HDRI is enabled.

package/RenderConfig.mjs

@@ -1,4 +1,5 @@
 // generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
 import wasm from "./diplomat-wasm.mjs";
 import * as diplomatRuntime from "./diplomat-runtime.mjs";
 
@@ -128,6 +129,50 @@ export class RenderConfig {
         }
     }
 
+    /**
+     * Set the world-space directional light and its non-negative intensity.
+     */
+    setDirectionalLight(x, y, z, intensity) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.RenderConfig_set_directional_light(diplomatReceive.buffer, this.ffiValue, x, y, z, intensity);
+
+        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();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Set the unlit floor for non-HDRI rendering, in `0..=1`.
+     */
+    setAmbientLight(ambient) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.RenderConfig_set_ambient_light(diplomatReceive.buffer, this.ffiValue, ambient);
+
+        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();
+            diplomatReceive.free();
+        }
+    }
+
     /**
      * Set a solid RGBA clear color (linear 0.0–1.0). Alpha < 1.0 yields a
      * transparent PNG. Ignored when HDRI is enabled.

package/Renderer.d.ts

@@ -1,6 +1,7 @@
 // generated by diplomat-tool
 import type { NucleationError } from "./NucleationError"
 import type { RenderConfig } from "./RenderConfig"
+import type { ResourcePack } from "./ResourcePack"
 import type { Schematic } from "./Schematic"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
@@ -32,4 +33,19 @@ export class Renderer {
      * Render a schematic to a PNG file at `path`.
      */
     static renderToFile(schematic: Schematic, packZip: Array<number>, config: RenderConfig, path: string): void;
+
+    /**
+     * Render with an already parsed resource pack, avoiding repeated ZIP parsing.
+     */
+    static renderToFileWithPack(schematic: Schematic, pack: ResourcePack, config: RenderConfig, path: string): void;
+
+    /**
+     * Render raw RGBA pixels with an already parsed resource pack.
+     */
+    static renderPixelsB64WithPack(schematic: Schematic, pack: ResourcePack, config: RenderConfig): string;
+
+    /**
+     * Render PNG bytes with an already parsed resource pack.
+     */
+    static renderPngB64WithPack(schematic: Schematic, pack: ResourcePack, config: RenderConfig): string;
 }

package/Renderer.mjs

@@ -1,6 +1,7 @@
 // generated by diplomat-tool
 import { NucleationError } from "./NucleationError.mjs"
 import { RenderConfig } from "./RenderConfig.mjs"
+import { ResourcePack } from "./ResourcePack.mjs"
 import { Schematic } from "./Schematic.mjs"
 import wasm from "./diplomat-wasm.mjs";
 import * as diplomatRuntime from "./diplomat-runtime.mjs";
@@ -133,6 +134,85 @@ export class Renderer {
         }
     }
 
+    /**
+     * Render with an already parsed resource pack, avoiding repeated ZIP parsing.
+     */
+    static renderToFileWithPack(schematic, pack, config, path) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const pathSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, path)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Renderer_render_to_file_with_pack(diplomatReceive.buffer, schematic.ffiValue, pack.ffiValue, config.ffiValue, pathSlice.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();
+        }
+    }
+
+    /**
+     * Render raw RGBA pixels with an already parsed resource pack.
+     */
+    static renderPixelsB64WithPack(schematic, pack, config) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Renderer_render_pixels_b64_with_pack(diplomatReceive.buffer, schematic.ffiValue, pack.ffiValue, config.ffiValue, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Render PNG bytes with an already parsed resource pack.
+     */
+    static renderPngB64WithPack(schematic, pack, config) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Renderer_render_png_b64_with_pack(diplomatReceive.buffer, schematic.ffiValue, pack.ffiValue, config.ffiValue, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
     constructor(symbol, ptr, selfEdge) {
         return this.#internalConstructor(...arguments)
     }

package/VideoConfig.d.ts

@@ -0,0 +1,15 @@
+// generated by diplomat-tool
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Native FFmpeg video output preset.
+ */
+export class VideoConfig {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+}

package/VideoConfig.mjs

@@ -0,0 +1,44 @@
+// generated by diplomat-tool
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const VideoConfig_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.VideoConfig_destroy(ptr);
+});
+
+/**
+ * Native FFmpeg video output preset.
+ */
+export class VideoConfig {
+    // 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("VideoConfig 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) {
+            VideoConfig_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/WsPartitionHints.d.ts

@@ -0,0 +1,29 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Caller-supplied partition hints (full-column boxes a cluster may never
+ * span under {@link PartitionPolicy::HardCut}). Order does not matter:
+ * {@link PartitionIndex::new}(crate::world_segment::partition::PartitionIndex)
+ * sorts hints by full content at construction time.
+ */
+export class WsPartitionHints {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    static create(): WsPartitionHints;
+
+    /**
+     * Add a full-column hint (`y_range: None`) covering inclusive
+     * `x0..=x1, z0..=z1`.
+     */
+    add(id: string, x0: number, x1: number, z0: number, z1: number): void;
+
+    len(): number;
+}

package/WsPartitionHints.mjs

@@ -0,0 +1,102 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const WsPartitionHints_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.WsPartitionHints_destroy(ptr);
+});
+
+/**
+ * Caller-supplied partition hints (full-column boxes a cluster may never
+ * span under {@link PartitionPolicy::HardCut}). Order does not matter:
+ * {@link PartitionIndex::new}(crate::world_segment::partition::PartitionIndex)
+ * sorts hints by full content at construction time.
+ */
+export class WsPartitionHints {
+    // 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("WsPartitionHints 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) {
+            WsPartitionHints_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    static create() {
+
+        const result = wasm.WsPartitionHints_create();
+
+        try {
+            return new WsPartitionHints(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Add a full-column hint (`y_range: None`) covering inclusive
+     * `x0..=x1, z0..=z1`.
+     */
+    add(id, x0, x1, z0, z1) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const idSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, id)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.WsPartitionHints_add(diplomatReceive.buffer, this.ffiValue, idSlice.ptr, x0, x1, z0, z1);
+
+        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();
+        }
+    }
+
+    len() {
+
+        const result = wasm.WsPartitionHints_len(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/WsProfile.d.ts

@@ -0,0 +1,46 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A pinned {@link WorldProfile}(crate::world_segment::profile::WorldProfile):
+ * the substrate palette + Y band derived (or supplied) once per world and
+ * reused across every segmentation run against it.
+ */
+export class WsProfile {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Derive a profile from up to `sample` tiles (regions) of a world
+     * directory, in ascending `(x, z)` region order. `coverage` is
+     * `ProfileParams::min_slab_coverage`; every other `ProfileParams`
+     * field uses its default (`sample_stride: 1`, `y_scan: (-64, 320)`).
+     */
+    static deriveFromDir(worldDir: string, minY: number, maxY: number, sample: number, coverage: number): WsProfile;
+
+    /**
+     * The derived substrate Y band's lower bound (inclusive).
+     */
+    bandMin(): number;
+
+    /**
+     * The derived substrate Y band's upper bound (inclusive).
+     */
+    bandMax(): number;
+
+    /**
+     * Number of distinct block names in the substrate palette.
+     */
+    paletteLen(): number;
+
+    /**
+     * The substrate palette as a JSON array of block-name strings.
+     */
+    writePaletteJson(): string;
+}

package/WsProfile.mjs

@@ -0,0 +1,152 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const WsProfile_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.WsProfile_destroy(ptr);
+});
+
+/**
+ * A pinned {@link WorldProfile}(crate::world_segment::profile::WorldProfile):
+ * the substrate palette + Y band derived (or supplied) once per world and
+ * reused across every segmentation run against it.
+ */
+export class WsProfile {
+    // 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("WsProfile 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) {
+            WsProfile_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Derive a profile from up to `sample` tiles (regions) of a world
+     * directory, in ascending `(x, z)` region order. `coverage` is
+     * `ProfileParams::min_slab_coverage`; every other `ProfileParams`
+     * field uses its default (`sample_stride: 1`, `y_scan: (-64, 320)`).
+     */
+    static deriveFromDir(worldDir, minY, maxY, sample, coverage) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const worldDirSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, worldDir)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.WsProfile_derive_from_dir(diplomatReceive.buffer, worldDirSlice.ptr, minY, maxY, sample, coverage);
+
+        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 WsProfile(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * The derived substrate Y band's lower bound (inclusive).
+     */
+    bandMin() {
+
+        const result = wasm.WsProfile_band_min(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The derived substrate Y band's upper bound (inclusive).
+     */
+    bandMax() {
+
+        const result = wasm.WsProfile_band_max(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Number of distinct block names in the substrate palette.
+     */
+    paletteLen() {
+
+        const result = wasm.WsProfile_palette_len(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The substrate palette as a JSON array of block-name strings.
+     */
+    writePaletteJson() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.WsProfile_write_palette_json(diplomatReceive.buffer, this.ffiValue, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/WsRunResult.d.ts

@@ -0,0 +1,83 @@
+// generated by diplomat-tool
+import type { BlockPos } from "./BlockPos"
+import type { NucleationError } from "./NucleationError"
+import type { WsPartitionHints } from "./WsPartitionHints"
+import type { WsProfile } from "./WsProfile"
+import type { WsSegmentJob } from "./WsSegmentJob"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * The materialized output of one segmentation run: every build (in the
+ * pipeline's deterministic stable-id order) plus the aggregate
+ * {@link RunStats}(crate::world_segment::runner::RunStats).
+ */
+export class WsRunResult {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Run the full pipeline (source -> segment -> stitch -> score ->
+     * identity -> materialize) over a world directory. No prior-snapshot
+     * builds are supplied, so every build seeds a fresh stable id (see
+     * `StableBuildId::seed`).
+     *
+     * See the module docs for why this catches a panic instead of
+     * propagating it.
+     */
+    static runDir(job: WsSegmentJob, hints: WsPartitionHints, profile: WsProfile, worldDir: string): WsRunResult;
+
+    /**
+     * Total builds materialized (same as `build_count`, from `RunStats`).
+     */
+    builds(): bigint;
+
+    tierConfident(): bigint;
+
+    tierProbable(): bigint;
+
+    tierDebris(): bigint;
+
+    crossTile(): bigint;
+
+    largestBlockCount(): bigint;
+
+    /**
+     * Number of builds held in this result (indices `0..build_count()`
+     * are valid for every per-index accessor below).
+     */
+    buildCount(): number;
+
+    /**
+     * The build's stable id (hex), stable across re-runs against the
+     * same source under the same config, absent a prior-snapshot match.
+     */
+    stableIdHex(index: number): string;
+
+    /**
+     * The build's content fingerprint, as 32 lowercase hex digits (u128,
+     * big-endian).
+     */
+    fingerprintHex(index: number): string;
+
+    /**
+     * `0` = Confident, `1` = Probable, `2` = Debris.
+     */
+    tierOf(index: number): number;
+
+    blockCountOf(index: number): bigint;
+
+    /**
+     * The build's world-space bounding box minimum (inclusive).
+     */
+    bboxMinOf(index: number): BlockPos;
+
+    /**
+     * The build's world-space bounding box maximum (inclusive).
+     */
+    bboxMaxOf(index: number): BlockPos;
+}

package/WsRunResult.mjs

@@ -0,0 +1,326 @@
+// generated by diplomat-tool
+import { BlockPos } from "./BlockPos.mjs"
+import { NucleationError } from "./NucleationError.mjs"
+import { WsPartitionHints } from "./WsPartitionHints.mjs"
+import { WsProfile } from "./WsProfile.mjs"
+import { WsSegmentJob } from "./WsSegmentJob.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const WsRunResult_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.WsRunResult_destroy(ptr);
+});
+
+/**
+ * The materialized output of one segmentation run: every build (in the
+ * pipeline's deterministic stable-id order) plus the aggregate
+ * {@link RunStats}(crate::world_segment::runner::RunStats).
+ */
+export class WsRunResult {
+    // 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("WsRunResult 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) {
+            WsRunResult_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Run the full pipeline (source -> segment -> stitch -> score ->
+     * identity -> materialize) over a world directory. No prior-snapshot
+     * builds are supplied, so every build seeds a fresh stable id (see
+     * `StableBuildId::seed`).
+     *
+     * See the module docs for why this catches a panic instead of
+     * propagating it.
+     */
+    static runDir(job, hints, profile, worldDir) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const worldDirSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, worldDir)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.WsRunResult_run_dir(diplomatReceive.buffer, job.ffiValue, hints.ffiValue, profile.ffiValue, worldDirSlice.ptr);
+
+        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 WsRunResult(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Total builds materialized (same as `build_count`, from `RunStats`).
+     */
+    builds() {
+
+        const result = wasm.WsRunResult_builds(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    tierConfident() {
+
+        const result = wasm.WsRunResult_tier_confident(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    tierProbable() {
+
+        const result = wasm.WsRunResult_tier_probable(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    tierDebris() {
+
+        const result = wasm.WsRunResult_tier_debris(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    crossTile() {
+
+        const result = wasm.WsRunResult_cross_tile(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    largestBlockCount() {
+
+        const result = wasm.WsRunResult_largest_block_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Number of builds held in this result (indices `0..build_count()`
+     * are valid for every per-index accessor below).
+     */
+    buildCount() {
+
+        const result = wasm.WsRunResult_build_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The build's stable id (hex), stable across re-runs against the
+     * same source under the same config, absent a prior-snapshot match.
+     */
+    stableIdHex(index) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.WsRunResult_stable_id_hex(diplomatReceive.buffer, this.ffiValue, index, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * The build's content fingerprint, as 32 lowercase hex digits (u128,
+     * big-endian).
+     */
+    fingerprintHex(index) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.WsRunResult_fingerprint_hex(diplomatReceive.buffer, this.ffiValue, index, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * `0` = Confident, `1` = Probable, `2` = Debris.
+     */
+    tierOf(index) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 1, true);
+
+
+        const result = wasm.WsRunResult_tier_of(diplomatReceive.buffer, this.ffiValue, index);
+
+        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 Uint8Array(wasm.memory.buffer, diplomatReceive.buffer, 1))[0];
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    blockCountOf(index) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 9, 8, true);
+
+
+        const result = wasm.WsRunResult_block_count_of(diplomatReceive.buffer, this.ffiValue, index);
+
+        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 BigUint64Array(wasm.memory.buffer, diplomatReceive.buffer, 1))[0];
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * The build's world-space bounding box minimum (inclusive).
+     */
+    bboxMinOf(index) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 13, 4, true);
+
+
+        const result = wasm.WsRunResult_bbox_min_of(diplomatReceive.buffer, this.ffiValue, index);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return BlockPos._fromFFI(diplomatRuntime.internalConstructor, diplomatReceive.buffer);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * The build's world-space bounding box maximum (inclusive).
+     */
+    bboxMaxOf(index) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 13, 4, true);
+
+
+        const result = wasm.WsRunResult_bbox_max_of(diplomatReceive.buffer, this.ffiValue, index);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return BlockPos._fromFFI(diplomatRuntime.internalConstructor, diplomatReceive.buffer);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/WsSegmentJob.d.ts

@@ -0,0 +1,28 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * One segmentation run's parameters (the primitive knobs of
+ * {@link SegmentJob}(crate::world_segment::runner::SegmentJob), plus a
+ * `hard_cut` flag selecting {@link PartitionPolicy}). Built once, passed by
+ * reference into {@link WsRunResult::run_dir}.
+ */
+export class WsSegmentJob {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * `algorithm_version` is pinned to
+     * {@link SegConfig::default}(crate::world_segment::segment::SegConfig)'s
+     * value; `score_config` uses `ScoreConfig::default()`. Neither is
+     * exposed as a knob here — construct a `SegmentJob` directly in Rust
+     * if you need to override them.
+     */
+    static create(cellSize: number, closingRadius: number, minClusterBlocks: bigint, sourceId: string, snapshotId: string, minY: number, maxY: number, extractedAt: bigint, matchIou: number, hardCut: boolean): WsSegmentJob;
+}

package/WsSegmentJob.mjs

@@ -0,0 +1,81 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const WsSegmentJob_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.WsSegmentJob_destroy(ptr);
+});
+
+/**
+ * One segmentation run's parameters (the primitive knobs of
+ * {@link SegmentJob}(crate::world_segment::runner::SegmentJob), plus a
+ * `hard_cut` flag selecting {@link PartitionPolicy}). Built once, passed by
+ * reference into {@link WsRunResult::run_dir}.
+ */
+export class WsSegmentJob {
+    // 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("WsSegmentJob 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) {
+            WsSegmentJob_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * `algorithm_version` is pinned to
+     * {@link SegConfig::default}(crate::world_segment::segment::SegConfig)'s
+     * value; `score_config` uses `ScoreConfig::default()`. Neither is
+     * exposed as a knob here — construct a `SegmentJob` directly in Rust
+     * if you need to override them.
+     */
+    static create(cellSize, closingRadius, minClusterBlocks, sourceId, snapshotId, minY, maxY, extractedAt, matchIou, hardCut) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const sourceIdSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, sourceId)));
+        const snapshotIdSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, snapshotId)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.WsSegmentJob_create(diplomatReceive.buffer, cellSize, closingRadius, minClusterBlocks, sourceIdSlice.ptr, snapshotIdSlice.ptr, minY, maxY, extractedAt, matchIou, hardCut);
+
+        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 WsSegmentJob(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/index.d.ts

@@ -20,6 +20,8 @@ export { AnimationEffect } from "./AnimationEffect"
 
 export { BuildAnimation } from "./BuildAnimation"
 
+export { VideoConfig } from "./VideoConfig"
+
 export { Autostack } from "./Autostack"
 
 export { Blocks } from "./Blocks"
@@ -118,6 +120,14 @@ export { StoreIo } from "./StoreIo"
 
 export { Voxelizer } from "./Voxelizer"
 
+export { WsPartitionHints } from "./WsPartitionHints"
+
+export { WsProfile } from "./WsProfile"
+
+export { WsRunResult } from "./WsRunResult"
+
+export { WsSegmentJob } from "./WsSegmentJob"
+
 export { WorldChunkView } from "./WorldChunkView"
 
 export { WorldSink } from "./WorldSink"

package/index.mjs

@@ -18,6 +18,8 @@ export { AnimationEffect } from "./AnimationEffect.mjs"
 
 export { BuildAnimation } from "./BuildAnimation.mjs"
 
+export { VideoConfig } from "./VideoConfig.mjs"
+
 export { Autostack } from "./Autostack.mjs"
 
 export { Blocks } from "./Blocks.mjs"
@@ -116,6 +118,14 @@ export { StoreIo } from "./StoreIo.mjs"
 
 export { Voxelizer } from "./Voxelizer.mjs"
 
+export { WsPartitionHints } from "./WsPartitionHints.mjs"
+
+export { WsProfile } from "./WsProfile.mjs"
+
+export { WsRunResult } from "./WsRunResult.mjs"
+
+export { WsSegmentJob } from "./WsSegmentJob.mjs"
+
 export { WorldChunkView } from "./WorldChunkView.mjs"
 
 export { WorldSink } from "./WorldSink.mjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleation",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A high-performance Minecraft schematic parser and utility library",
   "type": "module",
   "main": "index.mjs",