nucleation 0.10.4 → 0.10.7

package/TickSimulation.mjs

@@ -282,7 +282,7 @@ export class TickSimulation {
         const result = wasm.TickSimulation_run_until_quiescent(this.ffiValue, budget);
 
         try {
-            return result;
+            return result === 1;
         }
 
         finally {
@@ -314,7 +314,7 @@ export class TickSimulation {
         const result = wasm.TickSimulation_is_quiescent(this.ffiValue);
 
         try {
-            return result;
+            return result === 1;
         }
 
         finally {
@@ -381,6 +381,100 @@ export class TickSimulation {
         }
     }
 
+    /**
+     * Batched block-state reads: `positions_json` is `[[x,y,z], ...]`,
+     * the answer a JSON array of descriptors in the same order
+     * (`"minecraft:air"` for empty).
+     *
+     * A verification sweep over a computational build is thousands of
+     * probe reads per settle; one boundary call per sweep instead of one
+     * per probe is the difference between the FFI being the throughput
+     * ceiling and not.
+     */
+    readProbes(positionsJson) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const positionsJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, positionsJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.TickSimulation_read_probes(diplomatReceive.buffer, this.ffiValue, positionsJsonSlice.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();
+        }
+    }
+
+    /**
+     * Who powers this cell and why — a power-source tree from the
+     * simulation's current state, as JSON.
+     *
+     * Each node carries `pos`, `state`, `kind` (`wire` / `conductor` /
+     * `source` / `block`), the `power` the cell carries or emits, and
+     * `inputs`: the per-side contributions that explain it, each with a
+     * `mechanism` (`block_signal`, `wire`, `wire_up`, `wire_down`,
+     * `strong`, `signal`), the arriving `power`, and a recursive
+     * `source` node. Cycles stop with `"cycle": true`. Coordinates are
+     * the same structure-local space `get_block` reads.
+     *
+     * This is the static complement of running the sim: an open (a dead
+     * route that settles quiescent) shows up as an empty `inputs` list
+     * exactly where the feed should have been.
+     */
+    conductionTrace(x, y, z) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_conduction_trace(this.ffiValue, x, y, z, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Write every settled non-air state back into `schematic` — the bulk
+     * form of `{simulate=true}`: settle once, keep the world the engine
+     * ended on. Returns how many blocks changed.
+     *
+     * The schematic's bounding-box minimum corresponds to the
+     * simulation's `(0, 0, 0)`, which is exactly how `from_schematic`
+     * loaded it. A file baked this way carries real wire connections and
+     * power in its palette, loads quiescent under `InWorld`, and renders
+     * correctly in any static consumer. Cells the simulation turned into
+     * air (a popped-off component) are left as the schematic had them.
+     */
+    bakeTo(schematic) {
+
+        const result = wasm.TickSimulation_bake_to(this.ffiValue, schematic.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
     /**
      * Snapshot the entire simulation; returns a checkpoint id.
      */
@@ -510,6 +604,196 @@ export class TickSimulation {
         }
     }
 
+    /**
+     * Start recording a run timeline from the current tick.
+     *
+     * A timeline is what makes a span of simulation reviewable after the
+     * fact: block deltas, the inputs that caused them and the piston
+     * strokes they drove, plus one whole-world frame to replay them from.
+     * Off by default — a simulation used for timing should not pay for it.
+     *
+     * Called again, it restarts from the current tick, and the previously
+     * stopped span is released.
+     *
+     * Starting a recording also wipes the plain block-change log that
+     * {@link TickSimulation::changes_json} and {@link TickSimulation::changes_count}
+     * read back to empty — a separate reset from
+     * {@link TickSimulation::record_updates}/{@link TickSimulation::clear_updates},
+     * which govern a different log. A host holding a cursor into the
+     * change log (the sim lab keeps a cumulative one) must reset that
+     * cursor when it calls this, or it will read past the end of a log
+     * that is no longer the one it was walking.
+     */
+    recordTimeline() {
+    wasm.TickSimulation_record_timeline(this.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * End the recording, keeping the span readable.
+     *
+     * This is a host's Stop button, and it is not a rewind: the span stays
+     * readable and exportable until the next
+     * {@link TickSimulation::record_timeline}, while the simulation is free to
+     * run on without the recording following it. No-op if nothing was
+     * recording.
+     */
+    stopTimeline() {
+    wasm.TickSimulation_stop_timeline(this.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Where the recorded run was busy, as JSON:
+     * `{"start":T,"end":T,"ticks":[{"tick":T,"changes":N,"inputs":N,
+     * "pistons":N}]}`.
+     *
+     * The strip a host draws to let someone pick a span worth exporting.
+     * Only ticks that did something appear: an idle tick is **absent**
+     * rather than present with zeroes, so a build that sits still does not
+     * advance the strip and a long quiet run stays cheap to send.
+     *
+     * `{"start":0,"end":0,"ticks":[]}` when nothing has been recorded.
+     */
+    timelineActivityJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_timeline_activity_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Exact and translated recurrence in the timeline a read query would
+     * resolve to (see {@link Self::timeline}), as JSON:
+     * `{"exact":{"start":T,"end":T,"period":N,"drift":[x,y,z]}|null,
+     * "translated":{...}|null}`.
+     *
+     * **An absent cycle is `null`, not an error.** Most builds — an
+     * adder, a door — never repeat their own state, and that is the
+     * ordinary outcome, not a failed search.
+     *
+     * **O(ticks × blocks): replays the whole recorded span to build one
+     * digest per tick boundary**, then rebuilds full frames for the
+     * handful of candidates that survive. This is an on-demand "find
+     * cycles" action for a host UI button, never something to call per
+     * tick or per frame — poll {@link Self::timeline_activity_json} instead.
+     *
+     * Materialises the whole recorded timeline once to answer this call
+     * (an owned `RunTimeline`'s `initial` frame copies every non-air
+     * block) — acceptable for one on-demand press, not for a loop.
+     *
+     * `{"exact":null,"translated":null}` when nothing has been recorded.
+     */
+    timelineCyclesJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_timeline_cycles_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Project `[start_tick, end_tick)` of the timeline a read query would
+     * resolve to (see {@link Self::timeline}) into the animated-GLB mesher's
+     * `Timeline` JSON — `{"origin":[x,y,z],"tick_ms":F,
+     * "events":[{"kind":"set_block"|"piston",...}]}` — via
+     * `crate::tick_timeline::mesher_timeline_json`.
+     *
+     * **Materialises the whole recorded timeline to answer this call**
+     * (an owned `RunTimeline`'s `initial` frame copies every non-air
+     * block in the world) — this is an on-demand "export this
+     * selection" action, not something to call per frame or poll.
+     *
+     * Fails if no timeline has been recorded, or if `start_tick..
+     * end_tick` is empty or outside the recorded span.
+     */
+    animationTimelineJson(startTick, endTick, tickMs) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.TickSimulation_animation_timeline_json(diplomatReceive.buffer, this.ffiValue, startTick, endTick, tickMs, 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 selection's starting scene — `[start_tick, end_tick)` of the
+     * timeline a read query would resolve to (see {@link Self::timeline}) —
+     * as schematic bytes, base64-encoded.
+     *
+     * A WASM handle cannot cross a worker boundary, so this exists for a
+     * host to hand the bytes to a worker, which rebuilds the schematic
+     * with `Schematic.fromData`.
+     *
+     * **Materialises the whole recorded timeline to answer this call**
+     * — see {@link Self::animation_timeline_json}; an on-demand export
+     * action, not a per-frame poll.
+     *
+     * Fails if no timeline has been recorded, or if `start_tick..
+     * end_tick` is empty or outside the recorded span.
+     */
+    selectionSchematicB64(startTick, endTick) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.TickSimulation_selection_schematic_b64(diplomatReceive.buffer, this.ffiValue, startTick, endTick, 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();
+        }
+    }
+
     /**
      * How many updates have been recorded — page before pulling them.
      */
@@ -615,6 +899,93 @@ export class TickSimulation {
         }
     }
 
+    /**
+     * Every block a piston currently has in flight, as JSON:
+     * `[{"to":[x,y,z],"from":[x,y,z],"state":"...","carried":"...",
+     * "carried_short":"..."|null,"remains":"..."|null,"dir":"east",
+     * "extending":bool,"started":T,"lands":T,"source_piston":bool}]`.
+     *
+     * Draw `carried` travelling `from` -> `to`, and `remains` (when it is
+     * not null) parked at `to` for the whole move. They differ from
+     * `state` — what actually lands — only for a retracting piston, whose
+     * body stays put while its head comes home; vanilla's
+     * `PistonHeadRenderer` splits exactly these two slots.
+     *
+     * `carried_short` is the same arm with `short=true`. Draw it while the
+     * head is **within half a block of its body** — `progress <= 0.5`
+     * extending, `progress >= 0.5` retracting — or the shaft passes
+     * visibly through the back of the piston as it comes home. Which form
+     * to use is yours; naming the state is the engine's.
+     *
+     * What a renderer needs to animate a stroke, from the simulator that
+     * dispatched it. The block-change stream cannot answer this: it says a
+     * cell became a `moving_piston` placeholder, not which block set off,
+     * which cell it left, or which tick it arrives — so a host that
+     * reconstructs strokes from changes is reimplementing piston mechanics
+     * downstream of the engine, and animating on a clock the simulation
+     * does not share. That desync is what draws a block twice, leaves a
+     * gap where one should be, and shears a piston head off its load.
+     *
+     * `started` and `lands` are tick numbers in the engine's frame, where
+     * {@link Self::tick_count} counts *completed* ticks: after stepping to
+     * `tick_count == t`, a flight's progress is
+     * `(t - started) / (lands - started)`, clamped to 1. Draw it while it
+     * is listed and drop it when it stops being listed — the same call
+     * that stops reporting it is the tick the real block is written, so
+     * there is no frame with both and none with neither.
+     */
+    movingBlocksJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_moving_blocks_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Drop the recorded block changes without stopping recording.
+     *
+     * The log grows for as long as the simulation runs and nothing
+     * empties it, so a long-running host — a browser session driving
+     * thousands of ticks — accumulates every block change forever. A
+     * host that has already consumed {@link TickSimulation::changes_json}
+     * can say so here and keep recording on. A host holding a cursor
+     * into the change log must reset that cursor when it calls this, or
+     * it will read past the end of a log that is no longer the one it
+     * was walking — the same hazard {@link TickSimulation::record_timeline}
+     * names for its own reset of this log.
+     *
+     * Refuses — and leaves the log untouched — while
+     * {@link TickSimulation::record_timeline} is recording: a run timeline
+     * is a seed frame plus this same log, and every timeline reader
+     * trusts that the log describes every mutation since recording
+     * began. Clearing it out from under a live recording would make
+     * replay silently wrong rather than fail loudly. Returns `true` if
+     * the log was cleared, `false` if the call was refused — following
+     * {@link TickSimulation::run_until_quiescent}'s convention of reporting
+     * whether the call achieved what it was asked, rather than swallowing
+     * a no-op.
+     */
+    clearChanges() {
+
+        const result = wasm.TickSimulation_clear_changes(this.ffiValue);
+
+        try {
+            return result === 1;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
     changesJson() {
         const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
 
@@ -630,6 +1001,37 @@ export class TickSimulation {
         }
     }
 
+    /**
+     * The same JSON array {@link TickSimulation::changes_json} produces,
+     * but only the entries from index `start` onward.
+     *
+     * Exists for a host draining the log every frame while a run
+     * timeline recording refuses {@link TickSimulation::clear_changes}: the
+     * log only ever grows in that state, so without this,
+     * `changes_json` re-serialises the whole backlog on every single
+     * drain — a cost that climbs for as long as the recording runs,
+     * which is exactly when a session runs longest. Reading from a
+     * cursor keeps a drain's cost to what is actually new.
+     *
+     * `start` at or past the end of the log yields `[]`, not an error —
+     * a host racing a draining cursor against a growing log should not
+     * have to special-case "nothing new yet".
+     */
+    changesJsonFrom(start) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_changes_json_from(this.ffiValue, start, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
     /**
      * Live item entities and minecarts, as JSON:
      * `{"items":[{"id":N,"item":"...","count":N,"pos":[..],"vel":[..],

package/index.d.mts

@@ -48,6 +48,8 @@ export { DefinitionRegion } from "./DefinitionRegion.mjs"
 
 export { SchematicRegions } from "./SchematicRegions.mjs"
 
+export { Design } from "./Design.mjs"
+
 export { Diff } from "./Diff.mjs"
 
 export { Fingerprint } from "./Fingerprint.mjs"
@@ -58,6 +60,8 @@ export { Field3 } from "./Field3.mjs"
 
 export { Geo } from "./Geo.mjs"
 
+export { Hdl } from "./Hdl.mjs"
+
 export { TickSimulation } from "./TickSimulation.mjs"
 
 export { ChunkMeshResult } from "./ChunkMeshResult.mjs"
@@ -90,10 +94,14 @@ export { RenderConfig } from "./RenderConfig.mjs"
 
 export { Renderer } from "./Renderer.mjs"
 
+export { Routing } from "./Routing.mjs"
+
 export { BlockState } from "./BlockState.mjs"
 
 export { Schematic } from "./Schematic.mjs"
 
+export { SchematicSplitResult } from "./SchematicSplitResult.mjs"
+
 export { SchematicBuilder } from "./SchematicBuilder.mjs"
 
 export { Scripting } from "./Scripting.mjs"
@@ -104,6 +112,8 @@ export { FieldProgramBuilder } from "./FieldProgramBuilder.mjs"
 
 export { Sdf } from "./Sdf.mjs"
 
+export { CellExecutor } from "./CellExecutor.mjs"
+
 export { CircuitBuilder } from "./CircuitBuilder.mjs"
 
 export { ExecutionMode } from "./ExecutionMode.mjs"

package/index.d.ts

@@ -48,6 +48,8 @@ export { DefinitionRegion } from "./DefinitionRegion.mjs"
 
 export { SchematicRegions } from "./SchematicRegions.mjs"
 
+export { Design } from "./Design.mjs"
+
 export { Diff } from "./Diff.mjs"
 
 export { Fingerprint } from "./Fingerprint.mjs"
@@ -58,6 +60,8 @@ export { Field3 } from "./Field3.mjs"
 
 export { Geo } from "./Geo.mjs"
 
+export { Hdl } from "./Hdl.mjs"
+
 export { TickSimulation } from "./TickSimulation.mjs"
 
 export { ChunkMeshResult } from "./ChunkMeshResult.mjs"
@@ -90,10 +94,14 @@ export { RenderConfig } from "./RenderConfig.mjs"
 
 export { Renderer } from "./Renderer.mjs"
 
+export { Routing } from "./Routing.mjs"
+
 export { BlockState } from "./BlockState.mjs"
 
 export { Schematic } from "./Schematic.mjs"
 
+export { SchematicSplitResult } from "./SchematicSplitResult.mjs"
+
 export { SchematicBuilder } from "./SchematicBuilder.mjs"
 
 export { Scripting } from "./Scripting.mjs"
@@ -104,6 +112,8 @@ export { FieldProgramBuilder } from "./FieldProgramBuilder.mjs"
 
 export { Sdf } from "./Sdf.mjs"
 
+export { CellExecutor } from "./CellExecutor.mjs"
+
 export { CircuitBuilder } from "./CircuitBuilder.mjs"
 
 export { ExecutionMode } from "./ExecutionMode.mjs"

package/index.mjs

@@ -46,6 +46,8 @@ export { DefinitionRegion } from "./DefinitionRegion.mjs"
 
 export { SchematicRegions } from "./SchematicRegions.mjs"
 
+export { Design } from "./Design.mjs"
+
 export { Diff } from "./Diff.mjs"
 
 export { Fingerprint } from "./Fingerprint.mjs"
@@ -56,6 +58,8 @@ export { Field3 } from "./Field3.mjs"
 
 export { Geo } from "./Geo.mjs"
 
+export { Hdl } from "./Hdl.mjs"
+
 export { TickSimulation } from "./TickSimulation.mjs"
 
 export { ChunkMeshResult } from "./ChunkMeshResult.mjs"
@@ -88,10 +92,14 @@ export { RenderConfig } from "./RenderConfig.mjs"
 
 export { Renderer } from "./Renderer.mjs"
 
+export { Routing } from "./Routing.mjs"
+
 export { BlockState } from "./BlockState.mjs"
 
 export { Schematic } from "./Schematic.mjs"
 
+export { SchematicSplitResult } from "./SchematicSplitResult.mjs"
+
 export { SchematicBuilder } from "./SchematicBuilder.mjs"
 
 export { Scripting } from "./Scripting.mjs"
@@ -102,6 +110,8 @@ export { FieldProgramBuilder } from "./FieldProgramBuilder.mjs"
 
 export { Sdf } from "./Sdf.mjs"
 
+export { CellExecutor } from "./CellExecutor.mjs"
+
 export { CircuitBuilder } from "./CircuitBuilder.mjs"
 
 export { ExecutionMode } from "./ExecutionMode.mjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleation",
-  "version": "0.10.4",
+  "version": "0.10.7",
   "description": "A high-performance Minecraft schematic parser and utility library",
   "type": "module",
   "main": "index.mjs",
@@ -8,12 +8,17 @@
     ".": {
       "types": "./index.d.ts",
       "default": "./index.mjs"
+    },
+    "./design": {
+      "types": "./veneer/design.d.ts",
+      "default": "./veneer/design.mjs"
     }
   },
   "files": [
     "*.mjs",
     "*.d.ts",
     "*.d.mts",
+    "veneer/",
     "nucleation.wasm",
     "diplomat.config.mjs"
   ],