nucleation 0.10.4 → 0.10.7

package/TickSimulation.d.mts

@@ -133,6 +133,50 @@ export class TickSimulation {
      */
     getBlock(x: number, y: number, z: number): string;
 
+    /**
+     * 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: string): string;
+
+    /**
+     * 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: number, y: number, z: number): string;
+
+    /**
+     * 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: Schematic): number;
+
     /**
      * Snapshot the entire simulation; returns a checkpoint id.
      */
@@ -192,6 +236,112 @@ export class TickSimulation {
      */
     clearUpdates(): void;
 
+    /**
+     * 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(): void;
+
+    /**
+     * 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(): void;
+
+    /**
+     * 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(): string;
+
+    /**
+     * 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(): string;
+
+    /**
+     * 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: number, endTick: number, tickMs: number): string;
+
+    /**
+     * 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: number, endTick: number): string;
+
     /**
      * How many updates have been recorded — page before pulling them.
      */
@@ -234,8 +384,89 @@ export class TickSimulation {
      */
     updatesWaveJson(tick: number): string;
 
+    /**
+     * 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(): string;
+
+    /**
+     * 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(): boolean;
+
     changesJson(): string;
 
+    /**
+     * 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: number): string;
+
     /**
      * Live item entities and minecarts, as JSON:
      * `{"items":[{"id":N,"item":"...","count":N,"pos":[..],"vel":[..],

package/TickSimulation.d.ts

@@ -133,6 +133,50 @@ export class TickSimulation {
      */
     getBlock(x: number, y: number, z: number): string;
 
+    /**
+     * 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: string): string;
+
+    /**
+     * 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: number, y: number, z: number): string;
+
+    /**
+     * 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: Schematic): number;
+
     /**
      * Snapshot the entire simulation; returns a checkpoint id.
      */
@@ -192,6 +236,112 @@ export class TickSimulation {
      */
     clearUpdates(): void;
 
+    /**
+     * 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(): void;
+
+    /**
+     * 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(): void;
+
+    /**
+     * 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(): string;
+
+    /**
+     * 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(): string;
+
+    /**
+     * 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: number, endTick: number, tickMs: number): string;
+
+    /**
+     * 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: number, endTick: number): string;
+
     /**
      * How many updates have been recorded — page before pulling them.
      */
@@ -234,8 +384,89 @@ export class TickSimulation {
      */
     updatesWaveJson(tick: number): string;
 
+    /**
+     * 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(): string;
+
+    /**
+     * 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(): boolean;
+
     changesJson(): string;
 
+    /**
+     * 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: number): string;
+
     /**
      * Live item entities and minecarts, as JSON:
      * `{"items":[{"id":N,"item":"...","count":N,"pos":[..],"vel":[..],