nucleation 0.10.22 → 0.10.24

package/renderer/Schematic.d.ts

@@ -0,0 +1,977 @@
+// generated by diplomat-tool
+import type { BlockPos } from "./BlockPos.mjs"
+import type { BlockState } from "./BlockState.mjs"
+import type { Dimensions } from "./Dimensions.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { SchematicSplitResult } from "./SchematicSplitResult.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+export class Schematic {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Create a new, empty schematic with the given name.
+     */
+    static create(name: string): Schematic;
+
+    /**
+     * Release all block/entity storage immediately, keeping an empty valid
+     * schematic handle. JS consumers should call this when a parsed world or
+     * editing session is no longer needed instead of waiting for finalizers.
+     */
+    clearContents(): void;
+
+    /**
+     * Return an independent deep copy. Subsequent block, region, entity,
+     * metadata, or transform changes do not affect the original.
+     */
+    deepClone(): Schematic;
+
+    /**
+     * Inspect a versioned transform-plan JSON document without modifying
+     * this schematic. Writes a deterministic audit-report JSON document.
+     */
+    inspectTransformPlanJson(planJson: string): string;
+
+    /**
+     * Atomically apply a versioned transform-plan JSON document. Policy
+     * rejection is represented by `report.rejected == true` and leaves the
+     * schematic unchanged; malformed plans raise `InvalidArgument`.
+     */
+    applyTransformPlanJson(planJson: string): string;
+
+    /**
+     * Apply the bundled deterministic, lossless canonicalization preset.
+     */
+    canonicalizeJson(): string;
+
+    /**
+     * Inspect the bundled public-registry policy without modifying this
+     * schematic. Applications should review `rejected` and `quarantined`
+     * before choosing whether to call `apply_transform_plan_json`.
+     */
+    inspectRegistrySafeJson(): string;
+
+    /**
+     * 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: number, maxAirGap: number): SchematicSplitResult;
+
+    /**
+     * The allocated dimensions (width, height, length) of the schematic's
+     * bounding box.
+     */
+    dimensions(): Dimensions;
+
+    /**
+     * Returns `true` if a block was placed (out-of-range coordinates extend the
+     * schematic rather than erroring, matching `UniversalSchematic::set_block`).
+     */
+    setBlock(x: number, y: number, z: number, blockName: string): boolean;
+
+    /**
+     * The name of the block at a position. `NotFound` if the position is
+     * outside every region.
+     */
+    getBlockName(x: number, y: number, z: number): string;
+
+    /**
+     * Build a schematic from raw byte data, auto-detecting the format.
+     * Supports Litematic, Sponge Schematic, and McStructure (Bedrock) formats.
+     * `Parse` if a format was detected but failed to parse, `InvalidArgument` if
+     * no format was recognized.
+     */
+    static fromData(data: Array<number>): Schematic;
+
+    /**
+     * Decode untrusted bytes using a serialized `DecodeLimits` object.
+     * Empty JSON selects the conservative library defaults. Limits are
+     * enforced while decompressing/parsing and again before region
+     * allocations are accepted.
+     */
+    static fromDataBounded(data: Array<number>, limitsJson: string): Schematic;
+
+    /**
+     * Build a schematic from Litematic data.
+     */
+    static fromLitematic(data: Array<number>): Schematic;
+
+    /**
+     * The schematic as Litematic bytes, base64-encoded.
+     */
+    toLitematicB64(): string;
+
+    /**
+     * Build a schematic from classic `.schematic` data.
+     */
+    static fromSchematic(data: Array<number>): Schematic;
+
+    /**
+     * The schematic as classic `.schematic` bytes, base64-encoded.
+     */
+    toSchematicB64(): string;
+
+    /**
+     * Build a schematic from snapshot (fast binary) data.
+     */
+    static fromSnapshot(data: Array<number>): Schematic;
+
+    /**
+     * The schematic as snapshot (fast binary) bytes, base64-encoded.
+     */
+    toSnapshotB64(): string;
+
+    /**
+     * Build a schematic from McStructure (Bedrock) data.
+     */
+    static fromMcstructure(data: Array<number>): Schematic;
+
+    /**
+     * The schematic as McStructure (Bedrock) bytes, base64-encoded.
+     */
+    toMcstructureB64(): string;
+
+    /**
+     * Import from a single MCA region file.
+     */
+    static fromMca(data: Array<number>): Schematic;
+
+    /**
+     * Import from MCA with coordinate bounds.
+     */
+    static fromMcaBounded(data: Array<number>, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Schematic;
+
+    /**
+     * Import from a zipped world folder.
+     */
+    static fromWorldZip(data: Array<number>): Schematic;
+
+    /**
+     * Import from zipped world with coordinate bounds.
+     */
+    static fromWorldZipBounded(data: Array<number>, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Schematic;
+
+    /**
+     * Import from a Minecraft world directory path.
+     */
+    static fromWorldDirectory(path: string): Schematic;
+
+    /**
+     * Import from world directory with coordinate bounds.
+     */
+    static fromWorldDirectoryBounded(path: string, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Schematic;
+
+    /**
+     * Export the schematic as a Minecraft world: a JSON array of
+     * `{"path": <relative file path>, "data_b64": <base64 bytes>}` entries
+     * (the old `CFileMap`). `options_json` may be empty for defaults.
+     */
+    toWorldJson(optionsJson: string): string;
+
+    /**
+     * Export and write world files to a directory. `options_json` may be empty.
+     */
+    saveWorld(directory: string, optionsJson: string): void;
+
+    /**
+     * Export the schematic as a zipped Minecraft world, base64-encoded.
+     * `options_json` may be empty for defaults.
+     */
+    toWorldZipB64(optionsJson: string): string;
+
+    /**
+     * Set a block with properties given as a JSON object of string→string
+     * (the old `CProperty` array).
+     */
+    setBlockWithProperties(x: number, y: number, z: number, blockName: string, propertiesJson: string): void;
+
+    /**
+     * Set a block from a full block string, e.g.
+     * `minecraft:chest[facing=north]{Items:[...]}`.
+     */
+    setBlockFromString(x: number, y: number, z: number, blockString: string): void;
+
+    /**
+     * Pre-resolve a plain block name to a palette index for use with `place`.
+     * Pair them in hot loops with many unique block names to skip the per-call
+     * name → palette lookup.
+     */
+    prepareBlock(blockName: string): number;
+
+    /**
+     * Place a block by pre-resolved palette index (from `prepare_block`).
+     */
+    place(x: number, y: number, z: number, paletteIndex: number): void;
+
+    /**
+     * Batch-set blocks at multiple positions to the same block (name, block
+     * string with properties, or block string with NBT). `positions` is flat
+     * `[x0,y0,z0, x1,y1,z1, ...]` (length must be a multiple of 3).
+     * Returns the number of blocks set.
+     */
+    setBlocks(positions: Array<number>, blockName: string): number;
+
+    /**
+     * Sequentially hand-place the same block at many positions in one
+     * local simulated component. `positions` is flat
+     * `[x0,y0,z0, x1,y1,z1, ...]`; placements run in that order and each
+     * settles before the next. Returns the number of final cells written
+     * back, including neighbours changed by redstone or pistons.
+     *
+     * Nearby passive blocks are loaded as environmental context, but the
+     * write-back is confined to the active component's effect window. Its
+     * runtime is therefore independent of unrelated schematic volume.
+     * Use `set_blocks_simulated_full_world` to opt into global updates.
+     *
+     * This is the efficient bulk form of repeated `{simulate=true}`:
+     * structure conversion and simulator wiring happen once for the
+     * complete sequence. Propagation is not constant-time—a placement can
+     * affect an arbitrarily large circuit—but fixed setup is amortized.
+     */
+    setBlocksSimulated(positions: Array<number>, blockName: string): number;
+
+    /**
+     * Explicit full-world counterpart to `set_blocks_simulated`.
+     * Unrelated schematic volume participates in setup and any resulting
+     * changes anywhere in the loaded world are written back.
+     */
+    setBlocksSimulatedFullWorld(positions: Array<number>, blockName: string): number;
+
+    /**
+     * Batch-get block names at multiple positions. `positions` is flat
+     * `[x0,y0,z0, ...]` (length must be a multiple of 3). Writes a JSON array,
+     * one entry per position: the block name string, or `null` for
+     * empty/out-of-bounds positions.
+     */
+    getBlocksJson(positions: Array<number>): string;
+
+    /**
+     * Stamp a merged source box into the default region. Excluded blocks
+     * are skipped, preserving destination content. Empty string or `[]`
+     * means no exclusions.
+     */
+    stampBox(source: Schematic, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
+
+    /**
+     * Stamp one explicitly named source region into the default region.
+     * The region's minimum corner is mapped to the target position.
+     */
+    stampRegion(source: Schematic, sourceRegionName: string, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
+
+    /**
+     * Compatibility alias for `stamp_box`.
+     */
+    copyRegion(source: Schematic, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
+
+    /**
+     * The full block state at a position. `NotFound` if the position is
+     * outside every region.
+     */
+    getBlock(x: number, y: number, z: number): BlockState;
+
+    /**
+     * The block at a position with its properties, as a `BlockState`.
+     * Kept as an explicit alias for callers migrating from the older API.
+     */
+    getBlockWithProperties(x: number, y: number, z: number): BlockState;
+
+    /**
+     * The full block state at a position in one specific region. This
+     * avoids composite lookup ambiguity when regions overlap.
+     */
+    getBlockInRegion(regionName: string, x: number, y: number, z: number): BlockState;
+
+    /**
+     * The block string at a position in one specific region.
+     */
+    getBlockStringInRegion(regionName: string, x: number, y: number, z: number): string;
+
+    /**
+     * The full block string (name, properties, NBT) at a position.
+     */
+    getBlockString(x: number, y: number, z: number): string;
+
+    /**
+     * The block entity at a position as JSON
+     * `{"id": ..., "position": [x,y,z], "nbt": {...}}` (the old `CBlockEntity`).
+     */
+    getBlockEntityJson(x: number, y: number, z: number): string;
+
+    /**
+     * The block entity at a position in one specific region as JSON.
+     */
+    getBlockEntityJsonInRegion(regionName: string, x: number, y: number, z: number): string;
+
+    /**
+     * Every block entity as a JSON array of
+     * `{"id": ..., "position": [x,y,z], "nbt": {...}}`.
+     */
+    getAllBlockEntitiesJson(): string;
+
+    /**
+     * The number of mobile entities (not block entities).
+     */
+    entityCount(): number;
+
+    /**
+     * Every mobile entity as a JSON array of
+     * `{"id": ..., "position": [x,y,z], "nbt": {...}}` (the old `CEntityArray`).
+     */
+    getEntitiesJson(): string;
+
+    /**
+     * Add a mobile entity. `nbt_json` is a JSON object (may be empty).
+     */
+    addEntity(id: string, x: number, y: number, z: number, nbtJson: string): void;
+
+    /**
+     * Add an armor stand without hand-authoring entity NBT.
+     *
+     * `armor_material` accepts `diamond`, `netherite`, `iron`, etc.; an
+     * empty string creates an unarmored stand. `yaw` uses Minecraft degrees.
+     */
+    addArmorStand(x: number, y: number, z: number, yaw: number, armorMaterial: string): void;
+
+    /**
+     * Remove a mobile entity by index.
+     */
+    removeEntity(index: number): void;
+
+    /**
+     * The canonical in-memory data version (the forward-conversion target).
+     */
+    static canonicalDataVersion(): number;
+
+    /**
+     * Convert block/item/entity data between Minecraft data versions. Forward
+     * (`target >= source`) is lossless; reverse is lossy. Writes a JSON loss
+     * report (`[]` when lossless).
+     */
+    convertToDataVersion(targetDataVersion: number, sourceDataVersion: number): string;
+
+    /**
+     * Convert to `target_data_version` using the schematic's captured source
+     * version (else `mc_version`, else canonical) as origin, updating metadata
+     * to the target. Writes a JSON loss report (`[]` when lossless).
+     */
+    convertToVersion(targetDataVersion: number): string;
+
+    /**
+     * The Minecraft data version of the file this schematic was loaded from, or
+     * `-1` if none was captured (versionless / freshly built).
+     */
+    sourceDataVersion(): number;
+
+    /**
+     * Override the source data version for formats that carry no Java data
+     * version, so the converter knows what to convert *from*.
+     */
+    setSourceDataVersion(version: number): void;
+
+    /**
+     * Serialize a `.litematic` targeting a specific Minecraft data version. A
+     * COPY is converted and the matching Version header written; the schematic
+     * is left unchanged. Writes JSON
+     * `{"data_b64": <base64 .litematic>, "loss": <loss report>}`.
+     */
+    toLitematicForVersionJson(targetDataVersion: number): string;
+
+    /**
+     * The block entity's NBT as a typed SNBT string. Round-trips losslessly.
+     */
+    getBlockEntitySnbt(x: number, y: number, z: number): string;
+
+    /**
+     * Set (or replace) a block entity at a position from a typed SNBT string.
+     */
+    setBlockEntity(x: number, y: number, z: number, id: string, snbt: string): void;
+
+    /**
+     * Remove the block entity at a position. `NotFound` if none was there.
+     */
+    removeBlockEntity(x: number, y: number, z: number): void;
+
+    /**
+     * Every block entity as a JSON array of `{id, position: [x,y,z], snbt}`.
+     * The `snbt` is the inner data only (no `Id`/`Pos`).
+     */
+    getAllBlockEntitiesSnbtJson(): string;
+
+    /**
+     * Every mobile entity as a JSON array of typed SNBT strings (full compound
+     * incl. `id`/`Pos`).
+     */
+    getEntitiesSnbtJson(): string;
+
+    /**
+     * Add a mobile entity from a full SNBT entity compound (must contain `id`
+     * and `Pos`).
+     */
+    addEntityFromSnbt(snbt: string): void;
+
+    /**
+     * 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`.
+     *
+     * Prefer `get_non_air_blocks_json` for a block list,
+     * `count_blocks_json` for a material tally and
+     * `non_air_blocks_packed_b64` for bulk transfer. This method is
+     * kept for compatibility and is the wrong tool at any real size.
+     */
+    getAllBlocksJson(): string;
+
+    /**
+     * 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: string): string;
+
+    /**
+     * Every non-air block, same JSON shape as `get_all_blocks_json`.
+     * `block_count()`-sized regardless of the bounding volume.
+     */
+    getNonAirBlocksJson(): string;
+
+    /**
+     * Non-air blocks tallied by id: `{"minecraft:stone": 123, ...}`.
+     * One pass, no per block allocation, so a caller that only wants a
+     * material list never has to pull `get_non_air_blocks_json`. "Air"
+     * covers `minecraft:air`, `cave_air` and `void_air` alike.
+     */
+    countBlocksJson(): string;
+
+    /**
+     * Apply a `{"from id": "to id"}` map in place and return how many
+     * blocks changed. Keys match on block id only, ignoring block
+     * states; values may carry states (`minecraft:oak_stairs[facing=north]`),
+     * but not NBT: `parse_block_string` only returns a `BlockState`, so
+     * any `{...}` payload on a `to` value is silently dropped rather
+     * than copied onto the replaced block.
+     * A block whose id is not a key is left alone, and so is one that
+     * already equals its target: the count is the number of blocks
+     * actually changed, so a map that rewrites stone to stone returns 0.
+     * Errors with `Parse` on malformed JSON or an unparseable target id.
+     */
+    replaceBlocksJson(mapJson: string): bigint;
+
+    /**
+     * Every non-air block as a compact binary blob, base64 encoded
+     * (`DiplomatWrite` is UTF-8 only, see `to_litematic_b64`). Little
+     * endian throughout:
+     *
+     * ```text
+     * u32 count
+     * count * { i32 x, i32 y, i32 z, u16 palette_index }
+     * u32 palette_json_len
+     * u8[palette_json_len]   ["minecraft:stone", ...]
+     * ```
+     *
+     * Palette indices are assigned in first-seen order, so the same
+     * schematic always packs identically. About seven times smaller
+     * than `get_non_air_blocks_json` and free of per block JSON
+     * parsing on the far side.
+     *
+     * Palette indices are `u16`, so at most 65,535 distinct non-air
+     * block states can be addressed. A schematic with more than that
+     * writes **an empty string**, not a truncated palette: callers must
+     * treat an empty result as "too many distinct states, fall back to
+     * `get_non_air_blocks_json`". No real build has that many.
+     */
+    nonAirBlocksPackedB64(): string;
+
+    /**
+     * All blocks within a sub-region (chunk) of the schematic, as the same
+     * JSON array shape as `get_all_blocks_json`.
+     */
+    getChunkBlocksJson(offsetX: number, offsetY: number, offsetZ: number, width: number, height: number, length: number): string;
+
+    /**
+     * Non-air blocks inside a bounded box, retaining block-state properties.
+     * Visits only intersecting region cells, not the whole schematic. Bounds
+     * and arithmetic are checked; queries may scan at most 1,048,576 cells
+     * (including region overlaps) and emit at most 32 MiB of JSON. Renderers
+     * should request 16³ sections. Coordinates may be negative.
+     */
+    getChunkNonAirBlocksJson(offsetX: number, offsetY: number, offsetZ: number, width: number, height: number, length: number): string;
+
+    /**
+     * Storage metadata and full block states for palette-index streaming. Region order
+     * is default first, then sorted names (highest precedence first); indices are LOCAL to each region. Bounds
+     * describe allocated storage, never tight bounds. x is fastest, then z, then y.
+     * No block buffer is cloned or serialized here.
+     */
+    renderRegionsJson(): string;
+
+    /**
+     * A bounded window of a region's dense palette indices (including air).
+     * At most 65,536 cells per call; no full-world scan, coordinate tuples, or
+     * intermediate Rust allocation. JS bindings copy the borrowed slice before
+     * returning, so callers may mutate the schematic or grow WASM memory safely.
+     */
+    regionBlockIndices(regionName: string, start: number, count: number): Uint32Array;
+
+    /**
+     * Split the schematic into chunks (default bottom-up strategy). Writes a
+     * JSON array of `{"chunk_x", "chunk_y", "chunk_z", "blocks": [...]}` where
+     * blocks have the `get_all_blocks_json` shape (the old `CChunkArray`).
+     */
+    getChunksJson(chunkWidth: number, chunkHeight: number, chunkLength: number): string;
+
+    /**
+     * Split the schematic into chunks with a loading strategy: one of
+     * `distance_to_camera`, `top_down`, `bottom_up`, `center_outward`,
+     * `random` (anything else falls back to `bottom_up`). Camera coordinates
+     * are only used by `distance_to_camera`. Same JSON shape as
+     * `get_chunks_json`.
+     */
+    getChunksWithStrategyJson(chunkWidth: number, chunkHeight: number, chunkLength: number, strategy: string, cameraX: number, cameraY: number, cameraZ: number): string;
+
+    /**
+     * The total number of non-air blocks in the schematic.
+     */
+    blockCount(): number;
+
+    /**
+     * The total volume of the schematic's bounding box.
+     */
+    volume(): number;
+
+    /**
+     * The names of all regions, as a JSON array of strings.
+     */
+    regionNamesJson(): string;
+
+    /**
+     * Basic debug info about the schematic (name + region count).
+     */
+    debugInfo(): string;
+
+    /**
+     * A formatted schematic layout string (old `schematic_print`).
+     */
+    printString(): string;
+
+    /**
+     * A formatted schematic layout string (old `schematic_print_schematic`;
+     * same output as `print_string`).
+     */
+    printSchematicString(): string;
+
+    /**
+     * A detailed debug string, including a visual layout (old `debug_schematic`).
+     */
+    debugString(): string;
+
+    /**
+     * A detailed debug string with a JSON layout (old `debug_json_schematic`).
+     */
+    debugJsonString(): string;
+
+    /**
+     * The schematic name, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
+     */
+    name(): string;
+
+    /**
+     * Set the schematic name.
+     */
+    setName(name: string): void;
+
+    /**
+     * The schematic author, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
+     */
+    author(): string;
+
+    /**
+     * Set the schematic author.
+     */
+    setAuthor(author: string): void;
+
+    /**
+     * The schematic description, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
+     */
+    description(): string;
+
+    /**
+     * Set the schematic description.
+     */
+    setDescription(description: string): void;
+
+    /**
+     * The creation timestamp (milliseconds since epoch), or `-1` if not set.
+     */
+    created(): bigint;
+
+    /**
+     * Set the creation timestamp (milliseconds since epoch).
+     */
+    setCreated(created: bigint): void;
+
+    /**
+     * The modification timestamp (milliseconds since epoch), or `-1` if not set.
+     */
+    modified(): bigint;
+
+    /**
+     * Set the modification timestamp (milliseconds since epoch).
+     */
+    setModified(modified: bigint): void;
+
+    /**
+     * The Litematic format version, or `-1` if not set.
+     */
+    lmVersion(): number;
+
+    /**
+     * Set the Litematic format version.
+     */
+    setLmVersion(version: number): void;
+
+    /**
+     * The Minecraft data version, or `-1` if not set.
+     */
+    mcVersion(): number;
+
+    /**
+     * Set the Minecraft data version.
+     */
+    setMcVersion(version: number): void;
+
+    /**
+     * The WorldEdit version, or `-1` if not set.
+     */
+    weVersion(): number;
+
+    /**
+     * Set the WorldEdit version.
+     */
+    setWeVersion(version: number): void;
+
+    /**
+     * Standard embedded source provenance as canonical JSON. Returns an
+     * empty string when none is present.
+     */
+    provenanceJson(): string;
+
+    /**
+     * Validate and set standard embedded source provenance from JSON.
+     */
+    setProvenanceJson(json: string): void;
+
+    /**
+     * Remove embedded source provenance.
+     */
+    clearProvenance(): void;
+
+    /**
+     * Content-addressed processing history as a JSON array. This audit
+     * trail is deliberately separate from immutable source provenance.
+     */
+    transformationHistoryJson(): string;
+
+    /**
+     * Clear processing history without changing source provenance or
+     * schematic content. Intended for callers constructing a new artifact
+     * lineage, not for hiding registry audit records.
+     */
+    clearTransformationHistory(): void;
+
+    /**
+     * Mirror the default region along the X axis (in place). Block
+     * orientations, block entities, and entities are mirrored too.
+     */
+    flipX(): void;
+
+    /**
+     * Mirror the default region along the Y axis (in place).
+     */
+    flipY(): void;
+
+    /**
+     * Mirror the default region along the Z axis (in place).
+     */
+    flipZ(): void;
+
+    /**
+     * Rotate the default region about the X axis. +90° maps south (+Z)
+     * to down (-Y). Only multiples of 90 are accepted; invalid angles
+     * return `InvalidArgument` without changing the schematic. Negative
+     * values wrap.
+     */
+    rotateX(degrees: number): void;
+
+    /**
+     * Rotate the default region clockwise about the Y axis when viewed
+     * from above. +90° maps east (+X) to south (+Z).
+     */
+    rotateY(degrees: number): void;
+
+    /**
+     * Rotate the default region about the Z axis. +90° maps up (+Y) to
+     * west (-X).
+     */
+    rotateZ(degrees: number): void;
+
+    /**
+     * Move the default region and all attached block entities/entities.
+     */
+    translate(dx: number, dy: number, dz: number): void;
+
+    /**
+     * Mirror a named region along the X axis.
+     */
+    flipRegionX(regionName: string): void;
+
+    /**
+     * Mirror a named region along the Y axis.
+     */
+    flipRegionY(regionName: string): void;
+
+    /**
+     * Mirror a named region along the Z axis.
+     */
+    flipRegionZ(regionName: string): void;
+
+    /**
+     * Rotate a named region about the X axis by a multiple of 90 degrees.
+     */
+    rotateRegionX(regionName: string, degrees: number): void;
+
+    /**
+     * Rotate a named region clockwise about the Y axis by a multiple of
+     * 90 degrees.
+     */
+    rotateRegionY(regionName: string, degrees: number): void;
+
+    /**
+     * Rotate a named region about the Z axis by a multiple of 90 degrees.
+     */
+    rotateRegionZ(regionName: string, degrees: number): void;
+
+    /**
+     * Move one named region without affecting its siblings.
+     */
+    translateRegion(regionName: string, dx: number, dy: number, dz: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicX(degrees: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicY(degrees: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicZ(degrees: number): void;
+
+    /**
+     * Mirror every region across the shared schematic X bounds.
+     */
+    flipSchematicX(): void;
+
+    /**
+     * Mirror every region across the shared schematic Y bounds.
+     */
+    flipSchematicY(): void;
+
+    /**
+     * Mirror every region across the shared schematic Z bounds.
+     */
+    flipSchematicZ(): void;
+
+    /**
+     * Move every region by the same delta, preserving their relative layout.
+     */
+    translateSchematic(dx: number, dy: number, dz: number): void;
+
+    /**
+     * Fill a cuboid with a block.
+     */
+    fillCuboid(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, blockName: string): void;
+
+    /**
+     * Fill a sphere with a block.
+     */
+    fillSphere(cx: number, cy: number, cz: number, radius: number, blockName: string): void;
+
+    /**
+     * Serialize to a named format, base64-encoded. `version` and `settings`
+     * may be empty strings for defaults.
+     */
+    saveAsB64(format: string, version: string, settings: string): string;
+
+    /**
+     * Serialize as a Sponge schematic targeting a specific format version,
+     * base64-encoded.
+     */
+    toSchematicVersionB64(version: string): string;
+
+    /**
+     * The available Sponge schematic exporter versions, as a JSON array of
+     * strings.
+     */
+    static availableSchematicVersionsJson(): string;
+
+    /**
+     * Set a block with NBT data given as a JSON object of string→string
+     * (may be empty).
+     */
+    setBlockWithNbt(x: number, y: number, z: number, blockName: string, nbtJson: string): void;
+
+    /**
+     * Set a block (by name) in a named region.
+     */
+    setBlockInRegion(regionName: string, x: number, y: number, z: number, blockName: string): void;
+
+    /**
+     * Whether a default or named schematic region exists.
+     */
+    hasRegion(regionName: string): boolean;
+
+    /**
+     * Create an empty named region. Its first block anchors its bounds.
+     */
+    createRegion(regionName: string): void;
+
+    /**
+     * Remove a named region. The default region cannot be removed.
+     */
+    removeRegion(regionName: string): void;
+
+    /**
+     * Rename a named region. The default region cannot be renamed.
+     */
+    renameRegion(oldName: string, newName: string): void;
+
+    /**
+     * The schematic bounding box as a JSON array
+     * `[min_x, min_y, min_z, max_x, max_y, max_z]`.
+     */
+    boundingBoxJson(): string;
+
+    /**
+     * A named region's bounding box as a JSON array
+     * `[min_x, min_y, min_z, max_x, max_y, max_z]`. `"default"`/`"Default"`
+     * address the default region.
+     */
+    regionBoundingBoxJson(regionName: string): string;
+
+    /**
+     * The merged-region palette block names, as a JSON array of strings.
+     */
+    paletteJson(): string;
+
+    /**
+     * The tight (content) dimensions.
+     */
+    tightDimensions(): Dimensions;
+
+    /**
+     * The allocated dimensions (same as `dimensions`; named for parity with
+     * the old `schematic_get_allocated_dimensions`).
+     */
+    allocatedDimensions(): Dimensions;
+
+    /**
+     * Every sign in the schematic, as a JSON array of
+     * `{"pos": [x,y,z], "text": [...]}`.
+     */
+    extractSignsJson(): string;
+
+    /**
+     * Compile the schematic's insign annotations to JSON.
+     */
+    compileInsignJson(): string;
+
+    /**
+     * 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: string): void;
+
+    /**
+     * 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(): string;
+
+    /**
+     * 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(): string;
+
+    /**
+     * Parse the schematic's IO-contract insign annotations (`#cell`
+     * header, `bus.*` port annotations, `#route_zone` zones) to JSON:
+     * `{"cell": ..., "buses": [...], "route_zones": {...}}`.
+     */
+    compileIoContractsJson(): string;
+
+    /**
+     * Every region's palette, as a JSON object mapping region name → array of
+     * block names (the default region under `"default"`).
+     */
+    allPalettesJson(): string;
+
+    /**
+     * The default region's palette block names, as a JSON array of strings.
+     */
+    defaultRegionPaletteJson(): string;
+
+    /**
+     * A named region's palette block names, as a JSON array of strings.
+     * `"default"`/`"Default"` address the default region.
+     */
+    regionPaletteJson(regionName: string): string;
+
+    /**
+     * The minimum corner of the tight (content) bounds. `NotFound` when the
+     * schematic has no content.
+     */
+    tightBoundsMin(): BlockPos;
+
+    /**
+     * The maximum corner of the tight (content) bounds. `NotFound` when the
+     * schematic has no content.
+     */
+    tightBoundsMax(): BlockPos;
+}