nucleation 0.10.22 → 0.10.24

package/renderer/DistanceField.d.mts

@@ -0,0 +1,39 @@
+// generated by diplomat-tool
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+export class DistanceField {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Distance transform of a build's occupied voxels: every solid block
+     * learns how many blocks it sits below the surface, and the gradient of
+     * that depth gives the outward normal. Computed once over the
+     * schematic's bounding box.
+     */
+    static fromSchematic(schematic: Schematic): DistanceField;
+
+    /**
+     * Blocks below the surface at a voxel: 0 for empty/outside, 1 at the
+     * surface, increasing inward.
+     */
+    depth(x: number, y: number, z: number): number;
+
+    /**
+     * The upward component of the outward surface normal: 1 on flat ground,
+     * 0 on a vertical face, negative under an overhang. The scalar to key
+     * slope-based landscaping on (grass on the flats, stone on the steeps).
+     */
+    slope(x: number, y: number, z: number): number;
+
+    /**
+     * The full outward surface normal as JSON `[nx, ny, nz]`.
+     */
+    normalJson(x: number, y: number, z: number): string;
+}

package/renderer/DistanceField.d.ts

@@ -0,0 +1,39 @@
+// generated by diplomat-tool
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+export class DistanceField {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Distance transform of a build's occupied voxels: every solid block
+     * learns how many blocks it sits below the surface, and the gradient of
+     * that depth gives the outward normal. Computed once over the
+     * schematic's bounding box.
+     */
+    static fromSchematic(schematic: Schematic): DistanceField;
+
+    /**
+     * Blocks below the surface at a voxel: 0 for empty/outside, 1 at the
+     * surface, increasing inward.
+     */
+    depth(x: number, y: number, z: number): number;
+
+    /**
+     * The upward component of the outward surface normal: 1 on flat ground,
+     * 0 on a vertical face, negative under an overhang. The scalar to key
+     * slope-based landscaping on (grass on the flats, stone on the steeps).
+     */
+    slope(x: number, y: number, z: number): number;
+
+    /**
+     * The full outward surface normal as JSON `[nx, ny, nz]`.
+     */
+    normalJson(x: number, y: number, z: number): string;
+}

package/renderer/DistanceField.mjs

@@ -0,0 +1,114 @@
+// generated by diplomat-tool
+import { Schematic } from "./Schematic.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const DistanceField_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.DistanceField_destroy(ptr);
+});
+
+export class DistanceField {
+    // 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("DistanceField 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) {
+            DistanceField_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Distance transform of a build's occupied voxels: every solid block
+     * learns how many blocks it sits below the surface, and the gradient of
+     * that depth gives the outward normal. Computed once over the
+     * schematic's bounding box.
+     */
+    static fromSchematic(schematic) {
+
+        const result = wasm.DistanceField_from_schematic(schematic.ffiValue);
+
+        try {
+            return new DistanceField(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Blocks below the surface at a voxel: 0 for empty/outside, 1 at the
+     * surface, increasing inward.
+     */
+    depth(x, y, z) {
+
+        const result = wasm.DistanceField_depth(this.ffiValue, x, y, z);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The upward component of the outward surface normal: 1 on flat ground,
+     * 0 on a vertical face, negative under an overhang. The scalar to key
+     * slope-based landscaping on (grass on the flats, stone on the steeps).
+     */
+    slope(x, y, z) {
+
+        const result = wasm.DistanceField_slope(this.ffiValue, x, y, z);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The full outward surface normal as JSON `[nx, ny, nz]`.
+     */
+    normalJson(x, y, z) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.DistanceField_normal_json(this.ffiValue, x, y, z, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/ExecutionMode.d.mts

@@ -0,0 +1,42 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { OutputCondition } from "./OutputCondition.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * How long to run the circuit for one `execute` call (PORTING rule 10).
+ */
+export class ExecutionMode {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Run for exactly `ticks` ticks.
+     */
+    static fixedTicks(ticks: number): ExecutionMode;
+
+    /**
+     * Run until the output named `output_name` meets `condition`,
+     * checking every `check_interval` ticks, giving up after `max_ticks`
+     * ticks (the result's `condition_met` reports which happened).
+     */
+    static untilCondition(outputName: string, condition: OutputCondition, maxTicks: number, checkInterval: number): ExecutionMode;
+
+    /**
+     * Run until any output changes from its initial reading, checking
+     * every `check_interval` ticks, giving up after `max_ticks` ticks.
+     */
+    static untilChange(maxTicks: number, checkInterval: number): ExecutionMode;
+
+    /**
+     * Run (one tick at a time) until all outputs have been unchanged for
+     * `stable_ticks` consecutive ticks, giving up after `max_ticks`
+     * ticks (the result's `condition_met` reports stability).
+     */
+    static untilStable(stableTicks: number, maxTicks: number): ExecutionMode;
+}

package/renderer/ExecutionMode.d.ts

@@ -0,0 +1,42 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { OutputCondition } from "./OutputCondition.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * How long to run the circuit for one `execute` call (PORTING rule 10).
+ */
+export class ExecutionMode {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Run for exactly `ticks` ticks.
+     */
+    static fixedTicks(ticks: number): ExecutionMode;
+
+    /**
+     * Run until the output named `output_name` meets `condition`,
+     * checking every `check_interval` ticks, giving up after `max_ticks`
+     * ticks (the result's `condition_met` reports which happened).
+     */
+    static untilCondition(outputName: string, condition: OutputCondition, maxTicks: number, checkInterval: number): ExecutionMode;
+
+    /**
+     * Run until any output changes from its initial reading, checking
+     * every `check_interval` ticks, giving up after `max_ticks` ticks.
+     */
+    static untilChange(maxTicks: number, checkInterval: number): ExecutionMode;
+
+    /**
+     * Run (one tick at a time) until all outputs have been unchanged for
+     * `stable_ticks` consecutive ticks, giving up after `max_ticks`
+     * ticks (the result's `condition_met` reports stability).
+     */
+    static untilStable(stableTicks: number, maxTicks: number): ExecutionMode;
+}

package/renderer/ExecutionMode.mjs

@@ -0,0 +1,127 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import { OutputCondition } from "./OutputCondition.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const ExecutionMode_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.ExecutionMode_destroy(ptr);
+});
+
+/**
+ * How long to run the circuit for one `execute` call (PORTING rule 10).
+ */
+export class ExecutionMode {
+    // 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("ExecutionMode 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) {
+            ExecutionMode_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Run for exactly `ticks` ticks.
+     */
+    static fixedTicks(ticks) {
+
+        const result = wasm.ExecutionMode_fixed_ticks(ticks);
+
+        try {
+            return new ExecutionMode(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Run until the output named `output_name` meets `condition`,
+     * checking every `check_interval` ticks, giving up after `max_ticks`
+     * ticks (the result's `condition_met` reports which happened).
+     */
+    static untilCondition(outputName, condition, maxTicks, checkInterval) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const outputNameSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, outputName)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.ExecutionMode_until_condition(diplomatReceive.buffer, outputNameSlice.ptr, condition.ffiValue, maxTicks, checkInterval);
+
+        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 ExecutionMode(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Run until any output changes from its initial reading, checking
+     * every `check_interval` ticks, giving up after `max_ticks` ticks.
+     */
+    static untilChange(maxTicks, checkInterval) {
+
+        const result = wasm.ExecutionMode_until_change(maxTicks, checkInterval);
+
+        try {
+            return new ExecutionMode(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Run (one tick at a time) until all outputs have been unchanged for
+     * `stable_ticks` consecutive ticks, giving up after `max_ticks`
+     * ticks (the result's `condition_met` reports stability).
+     */
+    static untilStable(stableTicks, maxTicks) {
+
+        const result = wasm.ExecutionMode_until_stable(stableTicks, maxTicks);
+
+        try {
+            return new ExecutionMode(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/Field3.d.mts

@@ -0,0 +1,40 @@
+// generated by diplomat-tool
+import type { FieldRange } from "./FieldRange.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Immutable scalar field evaluated over world-space `(x, y, z)`.
+ *
+ * A `Field3` has scalar semantics only. It may be shared by geometry and
+ * material consumers without being reinterpreted as a signed-distance field.
+ */
+export class Field3 {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Deterministic value-noise FBM normalized to `[-1, 1]`.
+     */
+    static valueNoiseFbm(frequency: number, seed: number, octaves: number): Field3;
+
+    evalAt(x: number, y: number, z: number): number;
+
+    /**
+     * The field's analytically proven output range.
+     *
+     * Returns `NotFound` when no range can be proven — callers mapping a
+     * field onto a gradient must handle that rather than silently
+     * propagating a sentinel into their `lo`/`hi` bounds.
+     */
+    outputRange(): FieldRange;
+
+    static fromJsonString(json: string): Field3;
+
+    toJson(): string;
+}

package/renderer/Field3.d.ts

@@ -0,0 +1,40 @@
+// generated by diplomat-tool
+import type { FieldRange } from "./FieldRange.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Immutable scalar field evaluated over world-space `(x, y, z)`.
+ *
+ * A `Field3` has scalar semantics only. It may be shared by geometry and
+ * material consumers without being reinterpreted as a signed-distance field.
+ */
+export class Field3 {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Deterministic value-noise FBM normalized to `[-1, 1]`.
+     */
+    static valueNoiseFbm(frequency: number, seed: number, octaves: number): Field3;
+
+    evalAt(x: number, y: number, z: number): number;
+
+    /**
+     * The field's analytically proven output range.
+     *
+     * Returns `NotFound` when no range can be proven — callers mapping a
+     * field onto a gradient must handle that rather than silently
+     * propagating a sentinel into their `lo`/`hi` bounds.
+     */
+    outputRange(): FieldRange;
+
+    static fromJsonString(json: string): Field3;
+
+    toJson(): string;
+}

package/renderer/Field3.mjs

@@ -0,0 +1,160 @@
+// generated by diplomat-tool
+import { FieldRange } from "./FieldRange.mjs"
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Field3_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Field3_destroy(ptr);
+});
+
+/**
+ * Immutable scalar field evaluated over world-space `(x, y, z)`.
+ *
+ * A `Field3` has scalar semantics only. It may be shared by geometry and
+ * material consumers without being reinterpreted as a signed-distance field.
+ */
+export class Field3 {
+    // 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("Field3 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) {
+            Field3_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Deterministic value-noise FBM normalized to `[-1, 1]`.
+     */
+    static valueNoiseFbm(frequency, seed, octaves) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Field3_value_noise_fbm(diplomatReceive.buffer, frequency, seed, octaves);
+
+        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 Field3(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    evalAt(x, y, z) {
+
+        const result = wasm.Field3_eval_at(this.ffiValue, x, y, z);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The field's analytically proven output range.
+     *
+     * Returns `NotFound` when no range can be proven — callers mapping a
+     * field onto a gradient must handle that rather than silently
+     * propagating a sentinel into their `lo`/`hi` bounds.
+     */
+    outputRange() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 9, 4, true);
+
+
+        const result = wasm.Field3_output_range(diplomatReceive.buffer, this.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 FieldRange._fromFFI(diplomatRuntime.internalConstructor, diplomatReceive.buffer);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    static fromJsonString(json) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const jsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, json)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Field3_from_json_string(diplomatReceive.buffer, jsonSlice.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 Field3(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    toJson() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Field3_to_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/renderer/FieldProgram.d.mts

@@ -0,0 +1,40 @@
+// generated by diplomat-tool
+import type { FieldProgramDistanceKind } from "./FieldProgramDistanceKind.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { SdfBounds } from "./SdfBounds.mjs"
+import type { SdfNormal } from "./SdfNormal.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A validated, sandboxed custom SDF field program: deterministic typed
+ * bytecode over scalar/vec3/bool values with bounded loops, carrying
+ * its own explicit finite bounds and distance-kind metadata. Build one
+ * with {@link FieldProgramBuilder} or import it from JSON.
+ */
+export class FieldProgram {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    static fromJsonString(json: string): FieldProgram;
+
+    toJson(): string;
+
+    evalAt(x: number, y: number, z: number): number;
+
+    /**
+     * Unit-length gradient of the scalar output at `(x, y, z)`: the
+     * program's own forward-mode analytic gradient where it's
+     * differentiable there, falling back to a numerical estimate
+     * (central differences via `epsilon`) otherwise.
+     */
+    gradient(x: number, y: number, z: number, epsilon: number): SdfNormal;
+
+    bounds(): SdfBounds;
+
+    distanceKind(): FieldProgramDistanceKind;
+}