brs-js 2.1.3 → 3.0.1

package/README.md

@@ -1,10 +1,10 @@
 # brs.js
 
-Read and write Brickadia save files (.brs)
+Read and write Brickadia save files (.brs, .brz)
 
-Currently supports save versions <= 10
+Currently supports all BRS save versions. BRS Files are no longer supported as of Brickadia EA3.
 
-**Warning:** __Unreal Engine uses numbers potentially larger than Javascript can handle.__
+**Warning:** **Unreal Engine uses numbers potentially larger than Javascript can handle.**
 
 ## Install
 
@@ -134,47 +134,47 @@ Unsigned ints, while unlikely, may overflow.
 
 **Fields:** (optional fields during `brs.write(save)` will be set to default)
 
-| field                       | type   | default                              | optional | description                      |
-|-----------------------------|--------|--------------------------------------|----------|----------------------------------|
-| version                     | short  | Latest Save Version                  | auto     | Save file version                |
-| game_version                | int    | Game Version                         | &#9745;  | Saving version of the game       |
-| map                         | string | 'Unknown'                            | &#9745;  | Map where the save was generated |
-| author.id                   | uuid   | 00000000-0000-0000-0000-000000000000 | &#9745;  | Save author UUID                 |
-| author.name                 | string | 'Unknown'                            | &#9745;  | Save author name                 |
-| description                 | string | '' (Empty String)                    | &#9745;  | Save author name                 |
-| save_time                   | array  | [0, 0, 0, 0, 0, 0, 0, 0]             | &#9745;  | UTC in bytes of creation time    |
-| brick_count                 | int    | Number of bricks in `bricks`         | auto     | Number of bricks in save         |
-| mods                        | array  | []                                   | &#9745;  | In game mods required for load   |
-| brick_assets                | array  | ['PB_DefaultBrick']                  | &#9745;  | List of brick assets             |
-| colors                      | array  | []                                   | &#9745;  | List of colorset colors          |
-| materials                   | array  | ['BMC_Plastic']                      | &#9745;  | List of used materials           |
-| physical_materials          | array  | []                                   | &#9745;  | List of physical materials       |
-| brick_owners                | array  | [{}]                                 | &#9745;  | Brick owner list                 |
-| brick_owners[].id           | uuid   | 00000000-0000-0000-0000-000000000000 | &#9745;  | Brick owner list user uuid       |
-| brick_owners[].name         | string | 'Unknown'                            | &#9745;  | Brick owner list user name       |
-| brick_owners[].display_name | string | 'Unknown'                            | &#9745;  | Brick owner list display name    |
-| preview                     | array  | undefined                            | &#9745;  | 1280x720 png screenshot data     |
-| bricks                      | array  |                                      |          | List of bricks in the save       |
-| bricks[].asset_name_index   | int    | 0 (0 indexed)                        | &#9745;  | Index of asset in `brick_assets` |
-| bricks[].size               | array  |                                      |          | Brick size                       |
-| bricks[].position           | array  |                                      |          | Brick position                   |
-| bricks[].direction          | int    | 4 (Positive Z, Upward)               | &#9745;  | Brick axis / facing direction    |
-| bricks[].rotation           | int    | 0 (0 degrees)                        | &#9745;  | Brick rotation on axis           |
-| bricks[].collision          | bool   | true                                 | &#9745;  | Brick has collision with players |
-| bricks[].collision          | object |                                      | &#9745;  | Brick collision in general       |
-| bricks[].visibility         | bool   | true                                 | &#9745;  | Brick renders to players         |
-| bricks[].material_index     | int    | 0 (0 indexed)                        | &#9745;  | Index of material in `materials` |
-| bricks[].material_intensity | int    | 0 (0 indexed)                        | &#9745;  | Material intensity (0-10)        |
-| bricks[].physical_index     | int    | 0 (0 indexed)                        | &#9745;  | Index of physical material       |
-| bricks[].color *(colorset)* | int    | 0                                    | &#9745;  | Index of color in `colors`       |
-| bricks[].color *(rgba)*     | array  | [255, 255, 255, 255]                 | &#9745;  | Color in RGBA Bytes              |
-| bricks[].color *(rgb)*      | array  | [255, 255, 255] *(v9+)*              | &#9745;  | Color in RGBA Bytes              |
-| bricks[].owner_index        | int    | 1 (1 indexed)                        | &#9745;  | Index of owner in `brick_owners` |
-| bricks[].components         | object | {}                                   | &#9745;  | Components on this brick         |
-| components                  | object | {}                                   | &#9745;  | List of components in the save   |
-| components[].version        | int    |                                      |          | Game version for this component  |
-| components[].brick_indices  | array  |                                      |          | Indices of assigned bricks       |
-| components[].properties     | object |                                      |          | Map of properties names and types|
+| field                       | type   | default                              | optional | description                       |
+| --------------------------- | ------ | ------------------------------------ | -------- | --------------------------------- |
+| version                     | short  | Latest Save Version                  | auto     | Save file version                 |
+| game_version                | int    | Game Version                         | &#9745;  | Saving version of the game        |
+| map                         | string | 'Unknown'                            | &#9745;  | Map where the save was generated  |
+| author.id                   | uuid   | 00000000-0000-0000-0000-000000000000 | &#9745;  | Save author UUID                  |
+| author.name                 | string | 'Unknown'                            | &#9745;  | Save author name                  |
+| description                 | string | '' (Empty String)                    | &#9745;  | Save author name                  |
+| save_time                   | array  | [0, 0, 0, 0, 0, 0, 0, 0]             | &#9745;  | UTC in bytes of creation time     |
+| brick_count                 | int    | Number of bricks in `bricks`         | auto     | Number of bricks in save          |
+| mods                        | array  | []                                   | &#9745;  | In game mods required for load    |
+| brick_assets                | array  | ['PB_DefaultBrick']                  | &#9745;  | List of brick assets              |
+| colors                      | array  | []                                   | &#9745;  | List of colorset colors           |
+| materials                   | array  | ['BMC_Plastic']                      | &#9745;  | List of used materials            |
+| physical_materials          | array  | []                                   | &#9745;  | List of physical materials        |
+| brick_owners                | array  | [{}]                                 | &#9745;  | Brick owner list                  |
+| brick_owners[].id           | uuid   | 00000000-0000-0000-0000-000000000000 | &#9745;  | Brick owner list user uuid        |
+| brick_owners[].name         | string | 'Unknown'                            | &#9745;  | Brick owner list user name        |
+| brick_owners[].display_name | string | 'Unknown'                            | &#9745;  | Brick owner list display name     |
+| preview                     | array  | undefined                            | &#9745;  | 1280x720 png screenshot data      |
+| bricks                      | array  |                                      |          | List of bricks in the save        |
+| bricks[].asset_name_index   | int    | 0 (0 indexed)                        | &#9745;  | Index of asset in `brick_assets`  |
+| bricks[].size               | array  |                                      |          | Brick size                        |
+| bricks[].position           | array  |                                      |          | Brick position                    |
+| bricks[].direction          | int    | 4 (Positive Z, Upward)               | &#9745;  | Brick axis / facing direction     |
+| bricks[].rotation           | int    | 0 (0 degrees)                        | &#9745;  | Brick rotation on axis            |
+| bricks[].collision          | bool   | true                                 | &#9745;  | Brick has collision with players  |
+| bricks[].collision          | object |                                      | &#9745;  | Brick collision in general        |
+| bricks[].visibility         | bool   | true                                 | &#9745;  | Brick renders to players          |
+| bricks[].material_index     | int    | 0 (0 indexed)                        | &#9745;  | Index of material in `materials`  |
+| bricks[].material_intensity | int    | 0 (0 indexed)                        | &#9745;  | Material intensity (0-10)         |
+| bricks[].physical_index     | int    | 0 (0 indexed)                        | &#9745;  | Index of physical material        |
+| bricks[].color _(colorset)_ | int    | 0                                    | &#9745;  | Index of color in `colors`        |
+| bricks[].color _(rgba)_     | array  | [255, 255, 255, 255]                 | &#9745;  | Color in RGBA Bytes               |
+| bricks[].color _(rgb)_      | array  | [255, 255, 255] _(v9+)_              | &#9745;  | Color in RGBA Bytes               |
+| bricks[].owner_index        | int    | 1 (1 indexed)                        | &#9745;  | Index of owner in `brick_owners`  |
+| bricks[].components         | object | {}                                   | &#9745;  | Components on this brick          |
+| components                  | object | {}                                   | &#9745;  | List of components in the save    |
+| components[].version        | int    |                                      |          | Game version for this component   |
+| components[].brick_indices  | array  |                                      |          | Indices of assigned bricks        |
+| components[].properties     | object |                                      |          | Map of properties names and types |
 
 ### Function `brs.read(buffer, options)`
 
@@ -182,15 +182,15 @@ Unsigned ints, while unlikely, may overflow.
 
 In node, the buffer can be obtained from `fs.readFile` without an encoding specified. In web, the buffer can be obtained via `File.arrayBuffer()`. Be sure to resolve promises where necessary.
 
-| parameter   | type                | description                             |
-|-------------|---------------------|-----------------------------------------|
-| `buffer`    | Uint8Array / Buffer | Input bytes to be parsed                |
-| `options`   | Object              | Options for the parser, see table below |
+| parameter | type                | description                             |
+| --------- | ------------------- | --------------------------------------- |
+| `buffer`  | Uint8Array / Buffer | Input bytes to be parsed                |
+| `options` | Object              | Options for the parser, see table below |
 
 #### Options
 
 | name      | type    | description              | default |
-|-----------|---------|--------------------------|---------|
+| --------- | ------- | ------------------------ | ------- |
 | `bricks`  | boolean | Whether to read bricks   | `true`  |
 | `preview` | boolean | Whether to copy previews | `false` |
 
@@ -200,154 +200,235 @@ In node, the buffer can be obtained from `fs.readFile` without an encoding speci
 
 In node, the buffer can be saved with from `fs.writeFile(fileName, buffer)`. In web, the buffer can be made into a `new Blob([buffer])`, and can be downloaded with an `<a download>` with `href` as `URL.createObjectURL(blob)`.
 
-| parameter   | type        | description                            |
-|-------------|-------------|----------------------------------------|
-| `saveObj`   | Save Object | Save Object to be turned into a buffer |
+| parameter | type        | description                            |
+| --------- | ----------- | -------------------------------------- |
+| `saveObj` | Save Object | Save Object to be turned into a buffer |
 
 ### Brick Assets
 
 Notes:
 
-  - Size must be [0, 0, 0] for bricks using non-procedural brick assets
-  - Size must NOT be [0, 0, 0] for bricks using procedural brick assets
-  - 1x1 brick has size [5, 5, 6] and 'PB_DefaultBrick' brick asset
-  - 1x1F plate has size [5, 5, 2] and 'PB_DefaultBrick' brick asset
-
-
-| name | procedural |
-|------|------------|
-| PB_DefaultBrick | &#9745; |
-| PB_DefaultRamp | &#9745; |
-| PB_DefaultRampCrest | &#9745; |
-| PB_DefaultRampCrestCorner | &#9745; |
-| PB_DefaultRampCrestEnd | &#9745; |
-| PB_DefaultRampInnerCornerInverted | &#9745; |
-| PB_DefaultRampInverted | &#9745; |
-| PB_DefaultSideWedge | &#9745; |
-| PB_DefaultSideWedgeTile | &#9745; |
-| PB_DefaultTile | &#9745; |
-| PB_DefaultWedge | &#9745; |
-| PB_DefaultMicroBrick | &#9745; |
-| PB_DefaultMicroWedge | &#9745; |
-| B_1x1_Brick_Side | |
-| B_1x1_Brick_Side_Lip | |
-| B_1x1_Cone | |
-| B_1x1_Round | |
-| B_1x1F_Octo | |
-| B_1x1F_Round | |
-| B_1x2_Overhang | |
-| B_1x2f_Plate_Center | |
-| B_1x2f_Plate_Center_Inv | |
-| B_1x4_Brick_Side | |
-| B_1x_Octo | |
-| B_1x_Octo_90Deg | |
-| B_1x_Octo_90Deg_Inv | |
-| B_1x_Octo_T | |
-| B_1x_Octo_T_Inv | |
-| B_2x1_Slipper | |
-| B_2x2_Cone | |
-| B_2x2_Corner | |
-| B_2x2_Overhang | |
-| B_2x2_Round | |
-| B_2x2_Slipper | |
-| B_2x2F_Octo | |
-| B_2x2F_Octo_Converter | |
-| B_2x2F_Octo_Converter_Inv | |
-| B_2x2f_Plate_Center | |
-| B_2x2f_Plate_Center_Inv | |
-| B_2x2F_Round | |
-| B_2x4_Door_Frame | |
-| B_2x_Cube_Side | |
-| B_2x_Octo | |
-| B_2x_Octo_90Deg | |
-| B_2x_Octo_90Deg_Inv | |
-| B_2x_Octo_Cone | |
-| B_2x_Octo_T | |
-| B_2x_Octo_T_Inv | |
-| B_4x4_Round | |
-| B_8x8_Lattice_Plate | |
-| B_Bishop | |
-| B_Bone | |
-| B_BoneStraight | |
-| B_Branch | |
-| B_Bush | |
-| B_Cauldron | |
-| B_Chalice | |
-| B_CheckPoint | |
-| B_Coffin | |
-| B_Coffin_Lid | |
-| B_Fern | |
-| B_Flame | |
-| B_Flower | |
-| B_Gravestone | |
-| B_GoalPoint | |
-| B_Handle | |
-| B_Hedge_1x1 | |
-| B_Hedge_1x1_Corner | |
-| B_Hedge_1x2 | |
-| B_Hedge_1x4 | |
-| B_Inverted_Cone | |
-| B_Jar | |
-| B_King | |
-| B_Knight | |
-| B_Ladder | |
-| B_Pawn | |
-| B_Picket_Fence | |
-| B_Pine_Tree | |
-| B_Pumpkin | |
-| B_Pumpkin_Carved | |
-| B_Queen | |
-| B_Rook | |
-| B_Sausage | |
-| B_Small_Flower | |
-| B_SpawnPoint | |
-| B_Swirl_Plate | |
-| B_Turkey_Body | |
-| B_Turkey_Leg | |
-| B_1x1_Gate_Constant | |
-| B_1x1_Gate_Subtract | |
-| B_1x1_Gate_Multiply | |
-| B_1x1_Gate_ModFloored | |
-| B_1x1_Gate_Mod | |
-| B_1x1_Gate_Divide | |
-| B_1x1_Gate_Blend | |
-| B_1x1_Gate_Add | |
-| B_1x1_Gate_XOR | |
-| B_1x1_Gate_OR | |
-| B_1x1_Gate_NOR | |
-| B_1x1_Gate_NAND | |
-| B_1x1_Gate_EdgeDetector | |
-| B_1x1_Gate_Floor | |
-| B_1x1_Gate_Ceiling | |
-| B_1x1_EntityGate_ReadBrickGrid | |
-| B_1x1_Gate_NotEqual | |
-| B_1x1_Gate_LessThanEqual | |
-| B_1x1_Gate_LessThan | |
-| B_1x1_Gate_GreaterThanEqual | |
-| B_1x1_Gate_GreaterThan | |
-| B_1x1_Gate_XOR_Bitwise | |
-| B_1x1_Gate_ShiftRight_Bitwise | |
-| B_1x1_Gate_ShiftLeft_Bitwise | |
-| B_1x1_Gate_OR_Bitwise | |
-| B_1x1_Gate_NOR_Bitwise | |
-| B_1x1_Gate_NAND_Bitwise | |
-| B_1x1_Gate_AND_Bitwise | |
-| B_1x1_Reroute_Node | |
-| B_1x1_Gate_Timer_Tick | |
-| B_1x1_Gate_Timer | |
-| B_1x1_NOT_Gate | |
-| B_1x1_Gate_AND | |
-| B_1x1_Gate_Equal | |
-| B_1x1_Gate_NOT_Bitwise | |
+- Size must be [0, 0, 0] for bricks using non-procedural brick assets
+- Size must NOT be [0, 0, 0] for bricks using procedural brick assets
+- 1x1 brick has size [5, 5, 6] and 'PB_DefaultBrick' brick asset
+- 1x1F plate has size [5, 5, 2] and 'PB_DefaultBrick' brick asset
+
+| name                              | procedural |
+| --------------------------------- | ---------- |
+| PB_DefaultBrick                   | &#9745;    |
+| PB_DefaultRamp                    | &#9745;    |
+| PB_DefaultRampCrest               | &#9745;    |
+| PB_DefaultRampCrestCorner         | &#9745;    |
+| PB_DefaultRampCrestEnd            | &#9745;    |
+| PB_DefaultRampInnerCornerInverted | &#9745;    |
+| PB_DefaultRampInverted            | &#9745;    |
+| PB_DefaultSideWedge               | &#9745;    |
+| PB_DefaultSideWedgeTile           | &#9745;    |
+| PB_DefaultTile                    | &#9745;    |
+| PB_DefaultWedge                   | &#9745;    |
+| PB_DefaultMicroBrick              | &#9745;    |
+| PB_DefaultMicroWedge              | &#9745;    |
+| B_1x1_Brick_Side                  |            |
+| B_1x1_Brick_Side_Lip              |            |
+| B_1x1_Cone                        |            |
+| B_1x1_Round                       |            |
+| B_1x1F_Octo                       |            |
+| B_1x1F_Round                      |            |
+| B_1x2_Overhang                    |            |
+| B_1x2f_Plate_Center               |            |
+| B_1x2f_Plate_Center_Inv           |            |
+| B_1x4_Brick_Side                  |            |
+| B_1x_Octo                         |            |
+| B_1x_Octo_90Deg                   |            |
+| B_1x_Octo_90Deg_Inv               |            |
+| B_1x_Octo_T                       |            |
+| B_1x_Octo_T_Inv                   |            |
+| B_2x1_Slipper                     |            |
+| B_2x2_Cone                        |            |
+| B_2x2_Corner                      |            |
+| B_2x2_Overhang                    |            |
+| B_2x2_Round                       |            |
+| B_2x2_Slipper                     |            |
+| B_2x2F_Octo                       |            |
+| B_2x2F_Octo_Converter             |            |
+| B_2x2F_Octo_Converter_Inv         |            |
+| B_2x2f_Plate_Center               |            |
+| B_2x2f_Plate_Center_Inv           |            |
+| B_2x2F_Round                      |            |
+| B_2x4_Door_Frame                  |            |
+| B_2x_Cube_Side                    |            |
+| B_2x_Octo                         |            |
+| B_2x_Octo_90Deg                   |            |
+| B_2x_Octo_90Deg_Inv               |            |
+| B_2x_Octo_Cone                    |            |
+| B_2x_Octo_T                       |            |
+| B_2x_Octo_T_Inv                   |            |
+| B_4x4_Round                       |            |
+| B_8x8_Lattice_Plate               |            |
+| B_Bishop                          |            |
+| B_Bone                            |            |
+| B_BoneStraight                    |            |
+| B_Branch                          |            |
+| B_Bush                            |            |
+| B_Cauldron                        |            |
+| B_Chalice                         |            |
+| B_CheckPoint                      |            |
+| B_Coffin                          |            |
+| B_Coffin_Lid                      |            |
+| B_Fern                            |            |
+| B_Flame                           |            |
+| B_Flower                          |            |
+| B_Gravestone                      |            |
+| B_GoalPoint                       |            |
+| B_Handle                          |            |
+| B_Hedge_1x1                       |            |
+| B_Hedge_1x1_Corner                |            |
+| B_Hedge_1x2                       |            |
+| B_Hedge_1x4                       |            |
+| B_Inverted_Cone                   |            |
+| B_Jar                             |            |
+| B_King                            |            |
+| B_Knight                          |            |
+| B_Ladder                          |            |
+| B_Pawn                            |            |
+| B_Picket_Fence                    |            |
+| B_Pine_Tree                       |            |
+| B_Pumpkin                         |            |
+| B_Pumpkin_Carved                  |            |
+| B_Queen                           |            |
+| B_Rook                            |            |
+| B_Sausage                         |            |
+| B_Small_Flower                    |            |
+| B_SpawnPoint                      |            |
+| B_Swirl_Plate                     |            |
+| B_Turkey_Body                     |            |
+| B_Turkey_Leg                      |            |
+| B_1x1_Gate_Constant               |            |
+| B_1x1_Gate_Subtract               |            |
+| B_1x1_Gate_Multiply               |            |
+| B_1x1_Gate_ModFloored             |            |
+| B_1x1_Gate_Mod                    |            |
+| B_1x1_Gate_Divide                 |            |
+| B_1x1_Gate_Blend                  |            |
+| B_1x1_Gate_Add                    |            |
+| B_1x1_Gate_XOR                    |            |
+| B_1x1_Gate_OR                     |            |
+| B_1x1_Gate_NOR                    |            |
+| B_1x1_Gate_NAND                   |            |
+| B_1x1_Gate_EdgeDetector           |            |
+| B_1x1_Gate_Floor                  |            |
+| B_1x1_Gate_Ceiling                |            |
+| B_1x1_EntityGate_ReadBrickGrid    |            |
+| B_1x1_Gate_NotEqual               |            |
+| B_1x1_Gate_LessThanEqual          |            |
+| B_1x1_Gate_LessThan               |            |
+| B_1x1_Gate_GreaterThanEqual       |            |
+| B_1x1_Gate_GreaterThan            |            |
+| B_1x1_Gate_XOR_Bitwise            |            |
+| B_1x1_Gate_ShiftRight_Bitwise     |            |
+| B_1x1_Gate_ShiftLeft_Bitwise      |            |
+| B_1x1_Gate_OR_Bitwise             |            |
+| B_1x1_Gate_NOR_Bitwise            |            |
+| B_1x1_Gate_NAND_Bitwise           |            |
+| B_1x1_Gate_AND_Bitwise            |            |
+| B_1x1_Reroute_Node                |            |
+| B_1x1_Gate_Timer_Tick             |            |
+| B_1x1_Gate_Timer                  |            |
+| B_1x1_NOT_Gate                    |            |
+| B_1x1_Gate_AND                    |            |
+| B_1x1_Gate_Equal                  |            |
+| B_1x1_Gate_NOT_Bitwise            |            |
+
+## Brickadia Worlds (.brz)
+
+brs-js can write and read the Brickadia World archive format (`.brz`).
+Writing covers bricks, components, and wires; entities can be read but not
+yet written. `writeBrzLegacy` converts the same legacy `WriteSaveObject`
+that `write()` takes, except that `components` on bricks is a modern typed
+array (the legacy .brs component map is not converted) and `wires` on the
+save uses modern component and port names. A builder-style world API for
+authoring saves from scratch is planned:
+
+```js
+import { writeBrzLegacy, WorldReader } from 'brs-js';
+
+const brz = writeBrzLegacy({
+  description: 'my world',
+  bricks: [{ size: [5, 5, 6], position: [0, 0, 6], color: [255, 0, 0] }],
+});
+
+// WorldReader is lazy: schemas are parsed once and cached, and chunk
+// payloads are only decoded when you ask for them.
+const world = WorldReader.from(brz);
+world.bundle(); // Meta/Bundle.json
+world.brickAssets(); // basic asset names followed by procedural
+world.brickOwners(); // owner rows (PUBLIC excluded)
+world.gridIds(); // [1] plus any entity sub-grids
+for (const brick of world.bricks()) {
+  // decoded chunk by chunk
+}
+```
+
+Blobs are stored uncompressed by default, which is valid and matches the
+reference implementation byte for byte. To compress with zstd (Node 22.15
+or newer):
+
+```js
+import { zstdCompressSync, constants } from 'node:zlib';
+const brz = writeBrzLegacy(save, {
+  compress: data =>
+    zstdCompressSync(data, {
+      params: { [constants.ZSTD_c_compressionLevel]: 14 },
+    }),
+});
+```
+
+Reading applies a few normalizations:
+
+- Brick order round-trips per chunk rather than in global save order.
+- `collision.tool` always reads `true` because the format does not store it.
+- Palette color indices are resolved to `[r, g, b]` at write time.
+- `save.map` is not mapped; pass `{ environment }` in the options instead.
+
+The cross-language fixture tests skip unless fixtures have been generated.
+To enable them, run `just fixtures` with a crate checkout at `../brdb` (or
+set `BRDB_CRATE`).
+
+### .brdb (SQLite worlds)
+
+`.brdb` is the game's live world format: the same virtual filesystem as
+`.brz`, stored in SQLite with full revision history. Reading and writing
+requires `better-sqlite3` (an optional peer dependency, node only):
+
+    npm install better-sqlite3
+
+```js
+import { Brdb } from 'brs-js';
+
+const db = await Brdb.open('MyWorld.brdb');
+const reader = db.worldReader(); // same surface as WorldReader.from(brz)
+for (const brick of reader.bricks()) console.log(brick.position);
+
+const out = await Brdb.create('New.brdb');
+out.save('initial save', {
+  bricks: [{ size: [5, 5, 6], position: [0, 0, 6] }],
+});
+```
+
+Every `save`/`writePending` call is one revision: unchanged files are shared,
+changed files are soft-deleted and reinserted, and blobs are deduplicated by
+BLAKE3 hash. Blobs compress with zstd level 14 when node's zlib supports it
+(pass `compress: null` to store raw). Advanced: `new Brdb(db)` wraps any
+SQLite handle with a compatible synchronous API, with no dependency at all.
 
 ## Development
 
 NPM Scripts (`npm run <cmd>`)
 
-| name  | description                                              |
-|-------|----------------------------------------------------------|
-| build | Build library in development mode                        |
-| watch | Auto-build library in development mode when files change |
-| dist  | Build library in production mode                         |
-| test  | Run tests                                                |
-
+| name       | description                                          |
+| ---------- | ---------------------------------------------------- |
+| build      | Build all targets (web + node) and type declarations |
+| watch      | Rebuild the library when files change                |
+| dist       | Alias for `build`                                    |
+| test       | Run the test suite once                              |
+| test:watch | Run the test suite in watch mode                     |