nucleation 0.10.4 → 0.10.7

package/Schematic.mjs

@@ -3,6 +3,7 @@ import { BlockPos } from "./BlockPos.mjs"
 import { BlockState } from "./BlockState.mjs"
 import { Dimensions } from "./Dimensions.mjs"
 import { NucleationError } from "./NucleationError.mjs"
+import { SchematicSplitResult } from "./SchematicSplitResult.mjs"
 import wasm from "./diplomat-wasm.mjs";
 import * as diplomatRuntime from "./diplomat-runtime.mjs";
 
@@ -77,6 +78,26 @@ export class Schematic {
         }
     }
 
+    /**
+     * Split spatially independent machines while keeping nearby tiny
+     * detached parts with their machine. Components at least
+     * `min_standalone_blocks` large always remain independent; smaller
+     * components attach only directly to a core within `max_air_gap`.
+     * Attachment is non-transitive and the operation is lossless.
+     */
+    splitConnectedAttachNearby(minStandaloneBlocks, maxAirGap) {
+
+        const result = wasm.Schematic_split_connected_attach_nearby(this.ffiValue, minStandaloneBlocks, maxAirGap);
+
+        try {
+            return new SchematicSplitResult(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
     /**
      * The allocated dimensions (width, height, length) of the schematic's
      * bounding box.
@@ -1506,8 +1527,11 @@ export class Schematic {
     }
 
     /**
-     * Every non-air block as a JSON array of
+     * Every IN-BOUNDS cell as a JSON array of
      * `{"x", "y", "z", "name", "properties"}` (the old `CBlockArray`).
+     * Air cells are materialized too — on a large sparse build this
+     * dump is `volume()`-sized and can exhaust wasm memory; renderers
+     * and analyzers want `get_non_air_blocks_json`.
      */
     getAllBlocksJson() {
         const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
@@ -1524,6 +1548,58 @@ export class Schematic {
         }
     }
 
+    /**
+     * Every non-air block of ONE named region (a flattened design names
+     * one per layer: `inst:{name}`, `bus:{name}`), same JSON shape as
+     * `get_all_blocks_json`. Unknown region names error.
+     */
+    getRegionNonAirBlocksJson(regionName) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const regionNameSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, regionName)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Schematic_get_region_non_air_blocks_json(diplomatReceive.buffer, this.ffiValue, regionNameSlice.ptr, 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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Every non-air block, same JSON shape as `get_all_blocks_json`.
+     * `block_count()`-sized regardless of the bounding volume.
+     */
+    getNonAirBlocksJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.Schematic_get_non_air_blocks_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
     /**
      * All blocks within a sub-region (chunk) of the schematic, as the same
      * JSON array shape as `get_all_blocks_json`.
@@ -2050,6 +2126,73 @@ export class Schematic {
         }
     }
 
+    /**
+     * Standard embedded source provenance as canonical JSON. Returns an
+     * empty string when none is present.
+     */
+    provenanceJson() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Schematic_provenance_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();
+        }
+    }
+
+    /**
+     * Validate and set standard embedded source provenance from JSON.
+     */
+    setProvenanceJson(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.Schematic_set_provenance_json(diplomatReceive.buffer, this.ffiValue, 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 });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Remove embedded source provenance.
+     */
+    clearProvenance() {
+    wasm.Schematic_clear_provenance(this.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
     /**
      * Mirror the default region along the X axis (in place). Block
      * orientations, block entities, and entities are mirrored too.
@@ -2995,6 +3138,121 @@ export class Schematic {
         }
     }
 
+    /**
+     * Embed a `CellContract` (JSON) in the schematic's metadata,
+     * validating it parses first. The contract is carried through
+     * `.schem` save/open and autodetected on open — schematic +
+     * contract = one self-describing typed cell.
+     */
+    setCellContractJson(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.Schematic_set_cell_contract_json(diplomatReceive.buffer, this.ffiValue, 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 });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * The contract embedded in the schematic's metadata, as JSON.
+     * Errors with `NotFound` when none is embedded, `Parse` when an
+     * embedded string exists but is corrupt (loud, never silent).
+     */
+    cellContractJson() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Schematic_cell_contract_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();
+        }
+    }
+
+    /**
+     * Resolve the schematic's cell contract from its sources in
+     * strict precedence — embedded metadata over Insign signs — with
+     * loud conflict warnings. Writes `{"contract": ..., "warnings":
+     * [...]}`; errors with `NotFound` when no source defines one.
+     */
+    resolveCellContractJson() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Schematic_resolve_cell_contract_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();
+        }
+    }
+
+    /**
+     * Parse the schematic's IO-contract insign annotations (`#cell`
+     * header, `bus.*` port annotations, `#route_zone` zones) to JSON:
+     * `{"cell": ..., "buses": [...], "route_zones": {...}}`.
+     */
+    compileIoContractsJson() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Schematic_compile_io_contracts_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();
+        }
+    }
+
     /**
      * Every region's palette, as a JSON object mapping region name → array of
      * block names (the default region under `"default"`).

package/SchematicSplitResult.d.mts

@@ -0,0 +1,26 @@
+// 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";
+
+
+
+/**
+ * Deterministic, lossless pieces returned by
+ * {@link Schematic::split_connected_attach_nearby}. Pieces are ordered by their
+ * largest connected component, largest first.
+ */
+export class SchematicSplitResult {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    len(): number;
+
+    /**
+     * Return an independently owned piece by zero-based index.
+     */
+    piece(index: number): Schematic;
+}

package/SchematicSplitResult.d.ts

@@ -0,0 +1,26 @@
+// 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";
+
+
+
+/**
+ * Deterministic, lossless pieces returned by
+ * {@link Schematic::split_connected_attach_nearby}. Pieces are ordered by their
+ * largest connected component, largest first.
+ */
+export class SchematicSplitResult {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    len(): number;
+
+    /**
+     * Return an independently owned piece by zero-based index.
+     */
+    piece(index: number): Schematic;
+}

package/SchematicSplitResult.mjs

@@ -0,0 +1,84 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import { Schematic } from "./Schematic.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const SchematicSplitResult_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.SchematicSplitResult_destroy(ptr);
+});
+
+/**
+ * Deterministic, lossless pieces returned by
+ * {@link Schematic::split_connected_attach_nearby}. Pieces are ordered by their
+ * largest connected component, largest first.
+ */
+export class SchematicSplitResult {
+    // 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("SchematicSplitResult 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) {
+            SchematicSplitResult_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    len() {
+
+        const result = wasm.SchematicSplitResult_len(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Return an independently owned piece by zero-based index.
+     */
+    piece(index) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.SchematicSplitResult_piece(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 Schematic(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/Store.d.mts

@@ -7,7 +7,7 @@ import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 /**
  * A key/value store opened from a URL (e.g. `mem://`, `file:///path`,
- * `s3://bucket/prefix`, `redis://…`, `postgres://…`).
+ * `ssh://user@host/path`, `s3://bucket/prefix`, `redis://…`, `postgres://…`).
  */
 export class Store {
     /** @internal */

package/Store.d.ts

@@ -7,7 +7,7 @@ import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 /**
  * A key/value store opened from a URL (e.g. `mem://`, `file:///path`,
- * `s3://bucket/prefix`, `redis://…`, `postgres://…`).
+ * `ssh://user@host/path`, `s3://bucket/prefix`, `redis://…`, `postgres://…`).
  */
 export class Store {
     /** @internal */

package/Store.mjs

@@ -10,7 +10,7 @@ const Store_box_destroy_registry = new FinalizationRegistry((ptr) => {
 
 /**
  * A key/value store opened from a URL (e.g. `mem://`, `file:///path`,
- * `s3://bucket/prefix`, `redis://…`, `postgres://…`).
+ * `ssh://user@host/path`, `s3://bucket/prefix`, `redis://…`, `postgres://…`).
  */
 export class Store {
     // Internal ptr reference: