@adobe/ecs-persistence 0.0.0-stage → 0.1.0

package/src/decode.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Failure } from "./failure.js";
+import { decodeContents } from "./format/format.js";
+import { contents } from "./program/contents.js";
+import type { NamingTrait } from "./program/program.js";
+import type { Snapshot } from "./snapshot.js";
+
+/**
+ * The snapshot `bytes` holds, read by the trait `by`, its columns of bytes viewed where they are in `bytes`, copied once
+ * only when `bytes` doesn't start at a multiple of 8; or why it can't be read: it isn't one, `by` isn't a symbol, or it
+ * names a component or resource the trait doesn't cover, or covers with another schema.
+ */
+export const decode = (bytes: Uint8Array, options: { readonly by: NamingTrait }): Snapshot | Failure => {
+    const decoded = decodeContents(bytes, options.by);
+    return "failure" in decoded ? decoded : { [contents]: decoded };
+};

package/src/encode.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { encodeContents } from "./format/format.js";
+import { contents } from "./program/contents.js";
+import type { Snapshot } from "./snapshot.js";
+
+/**
+ * A snapshot as bytes, little-endian: a header naming each component and resource it holds by its trait's name for it,
+ * with its schema, then 8-byte-aligned blocks of each table's entities and columns, its bytes columns copied whole.
+ */
+export const encode = (snapshot: Snapshot): Uint8Array => encodeContents(snapshot[contents]);

package/src/failure.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/** Why a snapshot, a decoding or a spawn didn't happen. */
+export type Failure = { readonly failure: string };

package/src/format/format.ts

@@ -0,0 +1,185 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component, Resource, Schema, World } from "@adobe/ecs";
+import type { Failure } from "../failure.js";
+import type { Contents } from "../program/contents.js";
+import { programOf, type Persisted } from "../program/program.js";
+import { fromJson, toJson } from "../values/values.js";
+
+/**
+ * The binary form of a snapshot, little-endian:
+ * - 16 bytes: `ECSP`, the format's version as a u32, the header's length in bytes as a u32, and 4 bytes of zeros;
+ * - the header, JSON text padded with spaces to a multiple of 8 bytes: each component and resource by name with its
+ *   schema, and each table's count and where its entities and columns are;
+ * - blocks, each starting at a multiple of 8 bytes: a table's entities as f64s, a column's bytes as its components'
+ *   layout holds them, and a column of values as JSON text.
+ * A loader views the blocks of bytes where they are, in the buffer it's given.
+ */
+
+const magic = [0x45, 0x43, 0x53, 0x50];
+const version = 1;
+const prefix = 16;
+
+/** Where a column's data is. */
+type ColumnJson =
+    | { readonly kind: "bytes"; readonly offset: number; readonly length: number; readonly stride: number }
+    | { readonly kind: "values"; readonly offset: number; readonly length: number }
+    | { readonly kind: "value"; readonly value: unknown };
+
+type Header = {
+    readonly components: readonly { readonly name: string; readonly schema: Schema }[];
+    readonly resources: readonly { readonly name: string; readonly schema: Schema; readonly value: unknown }[];
+    readonly tables: readonly { readonly count: number; readonly entities: number; readonly columns: readonly ({ readonly component: number } & ColumnJson)[] }[];
+};
+
+const aligned = (offset: number): number => Math.ceil(offset / 8) * 8;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** A snapshot's contents as bytes. */
+export const encodeContents = (snapshot: Contents): Uint8Array => {
+    const blocks: Uint8Array[] = [];
+    let offset = 0;
+    /** Places a block, returning its offset from the first block. */
+    const place = (bytes: Uint8Array): number => {
+        const at = offset;
+        blocks.push(bytes);
+        offset = aligned(offset + bytes.byteLength);
+        return at;
+    };
+    const indexOf = new Map(snapshot.components.map((persisted, index) => [persisted.key, index]));
+    const tables = snapshot.tables.map(table => {
+        const entities = place(new Uint8Array(table.entities.buffer, table.entities.byteOffset, table.entities.byteLength));
+        const columns = snapshot.components.flatMap((persisted): ({ readonly component: number } & ColumnJson)[] => {
+            const key: symbol = persisted.key;
+            const column: World.Table.Column | undefined = Reflect.get(table.columns, key);
+            const component = indexOf.get(persisted.key) ?? -1;
+            if (column === undefined) return [];
+            if (column.kind === "bytes") return [{ component, kind: "bytes", offset: place(column.bytes), length: column.bytes.byteLength, stride: column.stride }];
+            if (column.kind === "value") return [{ component, kind: "value", value: toJson(persisted.schema, column.value) }];
+            const text = encoder.encode(JSON.stringify(column.values.map(value => toJson(persisted.schema, value))));
+            return [{ component, kind: "values", offset: place(text), length: text.byteLength }];
+        });
+        return { count: table.count, entities, columns };
+    });
+    const header: Header = {
+        components: snapshot.components.map(({ name, schema }) => ({ name, schema })),
+        resources: snapshot.resources.map(({ persisted, value }) => ({ name: persisted.name, schema: persisted.schema, value: toJson(persisted.schema, value) })),
+        tables,
+    };
+    const text = encoder.encode(JSON.stringify(header));
+    const headerLength = aligned(text.byteLength);
+    const bytes = new Uint8Array(prefix + headerLength + offset);
+    bytes.set(magic, 0);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(4, version, true);
+    view.setUint32(8, headerLength, true);
+    bytes.set(text, prefix);
+    bytes.fill(0x20, prefix + text.byteLength, prefix + headerLength);
+    let at = prefix + headerLength;
+    for (const block of blocks) {
+        bytes.set(block, at);
+        at = aligned(at + block.byteLength);
+    }
+    return bytes;
+};
+
+const isObject = (value: unknown): value is object => typeof value === "object" && value !== null;
+
+/** The header's JSON, checked enough to read it without casts, or null. */
+const headerOf = (json: unknown): Header | null => {
+    if (!isObject(json)) return null;
+    const components: unknown = Reflect.get(json, "components");
+    const resources: unknown = Reflect.get(json, "resources");
+    const tables: unknown = Reflect.get(json, "tables");
+    if (!Array.isArray(components) || !Array.isArray(resources) || !Array.isArray(tables)) return null;
+    const named = (item: unknown): boolean => isObject(item) && typeof Reflect.get(item, "name") === "string" && isObject(Reflect.get(item, "schema"));
+    if (!components.every(named) || !resources.every(named)) return null;
+    const isColumn = (item: unknown): boolean => {
+        if (!isObject(item) || typeof Reflect.get(item, "component") !== "number") return false;
+        const kind: unknown = Reflect.get(item, "kind");
+        if (kind === "value") return true;
+        const numbers = kind === "bytes" ? ["offset", "length", "stride"] : kind === "values" ? ["offset", "length"] : null;
+        return numbers !== null && numbers.every(name => typeof Reflect.get(item, name) === "number");
+    };
+    const isTable = (item: unknown): boolean => {
+        if (!isObject(item) || typeof Reflect.get(item, "count") !== "number" || typeof Reflect.get(item, "entities") !== "number") return false;
+        const columns: unknown = Reflect.get(item, "columns");
+        return Array.isArray(columns) && columns.every(isColumn);
+    };
+    if (!tables.every(isTable)) return null;
+    // Checked above: each item has the fields the header's type names, of their types.
+    const header = json as Header;
+    return header;
+};
+
+/** Whether two schemas are the same, by their JSON in their properties' order, which places a struct's fields. */
+const sameSchema = (a: Schema, b: Schema): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * The snapshot contents `bytes` holds, its components and resources by the names the trait `by` gives them, its blocks
+ * of bytes viewed where they are; or why it can't be read: it isn't one, or names what the trait doesn't cover, or
+ * covers with another schema.
+ */
+export const decodeContents = (bytes: Uint8Array, by: unknown): Contents | Failure => {
+    if (bytes.byteLength < prefix || magic.some((byte, at) => bytes[at] !== byte)) return { failure: "These bytes aren't a snapshot." };
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const found = view.getUint32(4, true);
+    if (found !== version) return { failure: `This snapshot's format is version ${found}; this package reads version ${version}.` };
+    const headerLength = view.getUint32(8, true);
+    let json: unknown;
+    try {
+        json = JSON.parse(decoder.decode(bytes.subarray(prefix, prefix + headerLength)));
+    }
+    catch {
+        return { failure: "This snapshot's header isn't JSON." };
+    }
+    const header = headerOf(json);
+    if (header === null) return { failure: "This snapshot's header isn't one this package writes." };
+    const program = programOf(by);
+    if (typeof program === "string") return { failure: program };
+    const components: Persisted<Component.Key>[] = [];
+    for (const { name, schema } of header.components) {
+        const persisted = program.components.get(name);
+        if (persisted === undefined) return { failure: `This snapshot holds component "${name}", which the trait doesn't cover.` };
+        if (!sameSchema(persisted.schema, schema)) return { failure: `Component "${name}" has another schema here than in this snapshot.` };
+        components.push(persisted);
+    }
+    const resources: { persisted: Persisted<Resource.Key>; value: unknown }[] = [];
+    for (const { name, schema, value } of header.resources) {
+        const persisted = program.resources.get(name);
+        if (persisted === undefined) return { failure: `This snapshot holds resource "${name}", which the trait doesn't cover.` };
+        if (!sameSchema(persisted.schema, schema)) return { failure: `Resource "${name}" has another schema here than in this snapshot.` };
+        resources.push({ persisted, value: fromJson(schema, value) });
+    }
+    // Blocks are 8-byte aligned in the buffer the format was written to; one given at another offset is copied once.
+    const blocks = (bytes.byteOffset + prefix + headerLength) % 8 === 0 ? bytes : bytes.slice();
+    const base = blocks.byteOffset + prefix + headerLength;
+    const end = blocks.byteOffset + blocks.byteLength;
+    const inBounds = (offset: number, length: number): boolean => offset >= 0 && length >= 0 && base + offset + length <= end;
+    const tables: World.Table[] = [];
+    for (const table of header.tables) {
+        if (!inBounds(table.entities, table.count * 8)) return { failure: "This snapshot's blocks are cut short." };
+        const columns: { [key: symbol]: World.Table.Column } = {};
+        for (const column of table.columns) {
+            const persisted = components[column.component];
+            if (persisted === undefined) return { failure: "This snapshot names a component it doesn't hold." };
+            if (column.kind === "value") columns[persisted.key] = { kind: "value", value: fromJson(persisted.schema, column.value) };
+            else if (!inBounds(column.offset, column.length)) return { failure: "This snapshot's blocks are cut short." };
+            else if (column.kind === "bytes") columns[persisted.key] = { kind: "bytes", bytes: new Uint8Array(blocks.buffer, base + column.offset, column.length), stride: column.stride };
+            else {
+                let values: unknown;
+                try {
+                    values = JSON.parse(decoder.decode(new Uint8Array(blocks.buffer, base + column.offset, column.length)));
+                }
+                catch {
+                    return { failure: `Component "${persisted.name}"'s values in this snapshot aren't JSON.` };
+                }
+                if (!Array.isArray(values)) return { failure: `Component "${persisted.name}"'s values in this snapshot aren't a list.` };
+                columns[persisted.key] = { kind: "values", values: values.map(value => fromJson(persisted.schema, value)) };
+            }
+        }
+        tables.push({ count: table.count, entities: new Float64Array(blocks.buffer, base + table.entities, table.count), columns });
+    }
+    return { by: program.by, components, tables, resources };
+};

package/src/guide/01-saving.md

@@ -0,0 +1,18 @@
+# Saving and loading
+
+Saved data names each component and resource by a name of its own, the same across versions and moves of its module.
+A trait of the application's own gives it: [`file`](01-saving.ts#L5-L6), a `Symbol()`
+[declared as a trait](01-saving.ts#L14-L16) whose value is a string, names a key on its declaration,
+[`[file]: "position"`](01-saving.ts#L18), as it's saved in a file. Only data is saved, a value with a schema, and never
+a derived component; `selected` here has no name, so it isn't saved.
+
+- `snapshot({ world, by: file })` takes every entity holding a component the trait covers, those components alone,
+  and the resources it covers, as columns.
+- `encode(snapshot)` writes them as bytes, and `decode(bytes, { by: file })` reads them back, viewing each column
+  where it is.
+- `spawn({ world, snapshot })` spawns an entity for each saved one and sets the resources. Entity values name the
+  entities spawned for theirs: the archer [targets the tower](01-saving.ts#L29-L30) again. Its result's `entities`
+  maps each saved entity to its new one.
+
+`snapshot`, `decode` and `spawn` each say why it didn't happen as `{ failure }`, rather than throwing, so
+`result.failure !== undefined` tells which. `encode` takes a snapshot one of them gave and always gives its bytes.

package/src/guide/01-saving.out

@@ -0,0 +1,4 @@
+saved bytes
+tower at [ 4, 0, 2 ]
+archer at [ 1, 0, 1 ] targets an entity
+level 3 of 2 entities

package/src/guide/01-saving.ts

@@ -0,0 +1,55 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, System, World, type Vec3 } from "@adobe/ecs";
+import { decode, encode, snapshot, spawn } from "../index.js";
+
+/** Saved in a file, under its name there. */
+const file = Symbol();
+const position = Symbol();
+const name = Symbol();
+const target = Symbol();
+const selected = Symbol();
+const level = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Traits<N> {
+        readonly [file]: string;
+    }
+    interface Components {
+        [position]: { type: Vec3; [file]: "position" };
+        [name]: { type: string; [file]: "name" };
+        [target]: { type: Entity; reference: "weak"; [file]: "target" };
+        [selected]: { type: true };
+    }
+    interface Resources {
+        [level]: { type: number; default: 1; [file]: "level" };
+    }
+}
+
+const build = System.create(({ commands, resources }) => {
+    const tower = commands.spawn([name, position, selected])({ [name]: "tower", [position]: [4, 0, 2] });
+    commands.spawn([name, position, target])({ [name]: "archer", [position]: [1, 0, 1], [target]: tower });
+    resources[level] = 3;
+});
+
+const report = System.create({ readonly: true, components: { with: [name, position], optional: [target, selected] } }, row => {
+    const notes = [...row[target] === undefined ? [] : ["targets an entity"], ...row[selected] === undefined ? [] : ["selected"]];
+    console.log(row[name], "at", row[position], ...notes);
+});
+const levelOf = System.create({ readonly: true }, ({ resources }) => resources[level]);
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(build);
+    const taken = await snapshot({ world, by: file });
+    if (taken.failure !== undefined) return console.log(taken.failure);
+    const bytes = encode(taken);
+    console.log("saved", bytes.length > 0 ? "bytes" : "nothing");
+
+    await using loaded = World.create();
+    const read = decode(bytes, { by: file });
+    if (read.failure !== undefined) return console.log(read.failure);
+    const spawned = await spawn({ world: loaded, snapshot: read });
+    if (spawned.failure !== undefined) return console.log(spawned.failure);
+    await loaded.run(report);
+    console.log("level", await loaded.run(levelOf), "of", spawned.entities.size, "entities");
+};

package/src/guide/02-copying.md

@@ -0,0 +1,15 @@
+# Copying between worlds
+
+Copying entities from one world into another is a snapshot spawned there, without bytes.
+`snapshot({ world, by: file, root })` takes [`root`](02-copying.ts#L51) and every entity it owns, directly or through
+others, by owner references its trait covers; `with` and `not` take the entities a query matches.
+
+- **Entities outside:** an entity value naming one that's left out does what despawning it would. A copied entity
+  [owned by one left behind](02-copying.ts#L65-L67) isn't spawned, nor anything it owns, and `dropped` counts them; a
+  weak reference to one is left out; any other value naming one is `Entity.none`.
+- **The new entities:** `entities` maps each copied entity to its copy. `entities: false` leaves the map out, for a
+  large copy that doesn't need it.
+- **Merging:** `match` takes unique indexes saying which entities are the same in both worlds: one an index holds in
+  the world, with the key of one copied, stands for it and keeps its own values. Copying the fleet into the harbor
+  again with [`match: [byLabel]`](02-copying.ts#L59) copies nothing twice. Each part of a key must be one the
+  snapshot's trait covers, and two copied entities with one key fail the merge.

package/src/guide/02-copying.out

@@ -0,0 +1,4 @@
+harbor holds [ 'hull, owned', 'mast, owned', 'ship' ]
+entities gives the harbor's ship for the ship: true
+harbor holds, merged [ 'hull, owned', 'mast, owned', 'ship' ]
+dock holds [] and dropped 2

package/src/guide/02-copying.ts

@@ -0,0 +1,70 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity, Index, System, World } from "@adobe/ecs";
+import { snapshot, spawn } from "../index.js";
+
+/** Saved in a file, under its name there. */
+const file = Symbol();
+const label = Symbol();
+const parent = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Traits<N> {
+        readonly [file]: string;
+    }
+    interface Components {
+        [label]: { type: string; [file]: "label" };
+        [parent]: { type: Entity; reference: "owner"; [file]: "parent" };
+    }
+}
+
+/** Labels are unique here, so an entity with one is the same in every world. */
+const byLabel = Index.create({ key: [label], unique: true });
+
+let ship = Entity.none;
+let hull = Entity.none;
+
+const build = System.create(({ commands }) => {
+    ship = commands.spawn([label])({ [label]: "ship" });
+    hull = commands.spawn([label, parent])({ [label]: "hull", [parent]: ship });
+    commands.spawn([label, parent])({ [label]: "mast", [parent]: hull });
+    commands.spawn([label])({ [label]: "island" });
+});
+
+const labels: string[] = [];
+let shipFound = Entity.none;
+const list = System.create({ readonly: true, components: { with: [label], optional: [parent] } }, row => {
+    labels.push(row[parent] === undefined ? row[label] : `${row[label]}, owned`);
+    if (row[label] === "ship") shipFound = row.entity;
+});
+const listed = async (world: World): Promise<readonly string[]> => {
+    labels.length = 0;
+    await world.run(list);
+    return [...labels].sort();
+};
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(build);
+
+    // The ship and everything it owns, through owner references the trait covers, copied into another world.
+    await using harbor = World.create();
+    const fleet = await snapshot({ world, by: file, root: ship });
+    if (fleet.failure !== undefined) return console.log(fleet.failure);
+    const copied = await spawn({ world: harbor, snapshot: fleet });
+    if (copied.failure !== undefined) return console.log(copied.failure);
+    console.log("harbor holds", await listed(harbor));
+    console.log("entities gives the harbor's ship for the ship:", copied.entities.get(ship) === shipFound);
+
+    // The fleet again, matched by label: the harbor's own stand for its entities, so none is copied twice.
+    const merged = await spawn({ world: harbor, snapshot: fleet, match: [byLabel] });
+    if (merged.failure !== undefined) return console.log(merged.failure);
+    console.log("harbor holds, merged", await listed(harbor));
+
+    // The hull's subtree, its owner left behind: copied, the hull would belong to no one, so neither it nor its mast is.
+    await using dock = World.create();
+    const hullOnly = await snapshot({ world, by: file, root: hull });
+    if (hullOnly.failure !== undefined) return console.log(hullOnly.failure);
+    const docked = await spawn({ world: dock, snapshot: hullOnly, entities: false });
+    if (docked.failure !== undefined) return console.log(docked.failure);
+    console.log("dock holds", await listed(dock), "and dropped", docked.dropped);
+};

package/src/guide/03-chunks.md

@@ -0,0 +1,15 @@
+# Saving chunks
+
+A world split into chunks by a [shared component](03-chunks.ts#L16), `shared: true`, holds each chunk's entities in archetypes of their
+own. `snapshot({ world, by, where })` takes the entities of the archetypes holding `where`'s values, as a system's `where`
+of values keeps it to them: [`where: { [chunk]: [2, 0] }`](03-chunks.ts#L57) reads chunk 2's archetype whole and
+nothing else, so a chunk's snapshot costs what the chunk holds, not the world.
+
+- **Values only:** `where` names shared components, each with a value of its type, which the archetype must hold.
+  Naming another component is a type error, and fails the snapshot as data.
+- **Unloading:** [`commands.despawnWhere`](03-chunks.ts#L32-L35) with a `where` of the chunk's coordinates despawns
+  its entities by one command, as a snapshot's `where` takes them.
+- **Loading back:** `spawn` puts each entity into the archetype of its saved shared values, so the chunk
+  [unloaded and loaded again](03-chunks.ts#L62-L66) is back where it was.
+- **Loading what's partly there:** with [`match: [byTree]`](03-chunks.ts#L72), the trees still standing keep their entities and
+  only those cut down are spawned again.

package/src/guide/03-chunks.out

@@ -0,0 +1,3 @@
+unloaded 0:0 0:1 0:2 1:10 1:11 1:12 3:30 3:31 3:32
+loaded   0:0 0:1 0:2 1:10 1:11 1:12 2:20 2:21 2:22 3:30 3:31 3:32
+merged   0:0 0:1 0:2 1:10 1:11 1:12 2:20 2:21 2:22 3:30 3:31 3:32

package/src/guide/03-chunks.ts

@@ -0,0 +1,75 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Index, System, World, type Vec2 } from "@adobe/ecs";
+import { decode, encode, snapshot, spawn } from "../index.js";
+
+/** Saved in a file, under its name there. */
+const file = Symbol();
+const chunk = Symbol();
+const tree = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Traits<N> {
+        readonly [file]: string;
+    }
+    interface Components {
+        // Shared: each chunk's entities are an archetype of their own, holding its coordinates once.
+        [chunk]: { type: Vec2.I32; shared: true; [file]: "chunk" };
+        [tree]: { type: number; [file]: "tree" };
+    }
+}
+
+/** Trees are numbered across the map, so one with a number is the same tree in every world. */
+const byTree = Index.create({ key: [tree], unique: true });
+
+/** Three trees in each of four chunks, `x` 0 to 3. */
+const grow = System.create(({ commands }) => {
+    for (let x = 0; x < 4; x++) {
+        const plant = commands.spawn([chunk, tree], { [chunk]: [x, 0] });
+        for (let k = 0; k < 3; k++) plant({ [tree]: 10 * x + k });
+    }
+});
+
+/** Unloads chunk `x`: despawns the trees of the archetype holding its coordinates, by one command. */
+const unload = System.create({}, ({ commands }, input: { readonly x: number }) => {
+    commands.despawnWhere({ with: [tree], where: { [chunk]: [input.x, 0] } });
+});
+
+/** Cuts the trees of chunk 2 down: those from `from` on. */
+const cut = System.create({ components: { with: [chunk, tree] } }, (row, { commands }, input: { readonly from: number }) => {
+    if (row[chunk][0] === 2 && row[tree] % 10 >= input.from) commands.despawn(row.entity);
+});
+
+const trees: string[] = [];
+const survey = System.create({ readonly: true, components: { with: [chunk, tree] } }, row => {
+    trees.push(`${row[chunk][0]}:${row[tree]}`);
+});
+const surveyed = async (world: World): Promise<string> => {
+    trees.length = 0;
+    await world.run(survey);
+    return [...trees].sort().join(" ");
+};
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(grow);
+
+    // Chunk 2 alone: only the archetype holding its coordinates is read.
+    const saved = await snapshot({ world, by: file, where: { [chunk]: [2, 0] }, resources: false });
+    if (saved.failure !== undefined) return console.log(saved.failure);
+    const bytes = encode(saved);
+
+    // Unloaded, then loaded back from its bytes, into the archetype of its coordinates.
+    await world.run(unload, { x: 2 });
+    console.log("unloaded", await surveyed(world));
+    const read = decode(bytes, { by: file });
+    if (read.failure !== undefined) return console.log(read.failure);
+    const loaded = await spawn({ world, snapshot: read });
+    if (loaded.failure !== undefined) return console.log(loaded.failure);
+    console.log("loaded  ", await surveyed(world));
+
+    // One tree cut since: loaded again with match, the two standing keep their entities and only the cut one returns.
+    await world.run(cut, { from: 2 });
+    const merged = await spawn({ world, snapshot: read, match: [byTree] });
+    if (merged.failure !== undefined) return console.log(merged.failure);
+    console.log("merged  ", await surveyed(world));
+};

package/src/guide/04-settings.md

@@ -0,0 +1,15 @@
+# Documents and settings
+
+An application saves to more than one place, each with a trait of its own: [`file`](04-settings.ts#L5-L8) for what a
+document holds, its voxels, their materials and its size, and `settings` for the user's own choices, the tool and
+whether a panel is open, which never go into a document. A key carries the trait of each place it's saved in, under the
+name it has there, and a name only has to be unique among the keys one trait covers.
+
+- **Taking each:** [`snapshot({ world, by: file })`](04-settings.ts#L46) takes the document, and
+  [`snapshot({ world, by: settings })`](04-settings.ts#L48) the settings. The settings
+  [are resources alone](04-settings.ts#L26-L27), so their snapshot holds no entity.
+- **Kept apart:** `decode` reads bytes by the trait it's given, and
+  [refuses a name](04-settings.ts#L53-L57) the trait doesn't cover, so settings can't be loaded as a document, nor a
+  document as settings.
+- **Loading each:** `spawn` takes no trait: a snapshot holds the one it was taken or read by. A document opened in
+  another world leaves that world's settings as they are.

package/src/guide/04-settings.out

@@ -0,0 +1,4 @@
+settings as a document: This snapshot holds resource "tool", which the trait doesn't cover.
+a document as settings: This snapshot holds component "voxel", which the trait doesn't cover.
+opened: 2 voxels, size 32, tool select, panel closed
+restored: 0 entities, size 16, tool brush, panel open

package/src/guide/04-settings.ts

@@ -0,0 +1,75 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, World, type Vec3 } from "@adobe/ecs";
+import { decode, encode, snapshot, spawn } from "../index.js";
+
+/** Saved in the document's file, under its name there. */
+const file = Symbol();
+/** Saved in the user's own settings, under its name there. */
+const settings = Symbol();
+const voxel = Symbol();
+const material = Symbol();
+const size = Symbol();
+const tool = Symbol();
+const panelOpen = Symbol();
+
+declare module "@adobe/ecs" {
+    interface Traits<N> {
+        readonly [file]: string;
+        readonly [settings]: string;
+    }
+    interface Components {
+        [voxel]: { type: Vec3.I32; [file]: "voxel" };
+        [material]: { type: string; [file]: "material" };
+    }
+    interface Resources {
+        [size]: { type: number; default: 16; [file]: "size" };
+        [tool]: { type: string; default: "select"; [settings]: "tool" };
+        [panelOpen]: { type: boolean; default: false; [settings]: "panel open" };
+    }
+}
+
+const edit = System.create(({ commands, resources }) => {
+    commands.spawn([voxel, material])({ [voxel]: [0, 0, 0], [material]: "stone" });
+    commands.spawn([voxel, material])({ [voxel]: [0, 1, 0], [material]: "grass" });
+    resources[size] = 32;
+    resources[tool] = "brush";
+    resources[panelOpen] = true;
+});
+
+const report = System.create({ readonly: true }, ({ resources }) => `size ${resources[size]}, tool ${resources[tool]}, panel ${resources[panelOpen] ? "open" : "closed"}`);
+let voxels = 0;
+const countVoxels = System.create({ readonly: true, components: { with: [voxel] } }, () => { voxels++; });
+
+export const main = async (): Promise<void> => {
+    await using world = World.create();
+    await world.run(edit);
+    const drawing = await snapshot({ world, by: file });
+    if (drawing.failure !== undefined) return console.log(drawing.failure);
+    const preferences = await snapshot({ world, by: settings });
+    if (preferences.failure !== undefined) return console.log(preferences.failure);
+    const fileBytes = encode(drawing);
+    const settingsBytes = encode(preferences);
+
+    // Each kind of bytes loads only as itself.
+    const settingsAsDocument = decode(settingsBytes, { by: file });
+    console.log("settings as a document:", settingsAsDocument.failure ?? "loaded");
+    const fileAsSettings = decode(fileBytes, { by: settings });
+    console.log("a document as settings:", fileAsSettings.failure ?? "loaded");
+
+    // A document opened on another machine, with that user's own settings.
+    await using opened = World.create();
+    const read = decode(fileBytes, { by: file });
+    if (read.failure !== undefined) return console.log(read.failure);
+    const spawned = await spawn({ world: opened, snapshot: read });
+    if (spawned.failure !== undefined) return console.log(spawned.failure);
+    await opened.run(countVoxels);
+    console.log("opened:", voxels, "voxels,", await opened.run(report));
+
+    // The settings alone, in a world of their own: resources, no entities.
+    await using restored = World.create();
+    const own = decode(settingsBytes, { by: settings });
+    if (own.failure !== undefined) return console.log(own.failure);
+    const applied = await spawn({ world: restored, snapshot: own });
+    if (applied.failure !== undefined) return console.log(applied.failure);
+    console.log("restored:", applied.entities.size, "entities,", await restored.run(report));
+};

package/src/guide/README.md

@@ -0,0 +1,10 @@
+# Guide
+
+How to save, load and copy worlds' entities with `@adobe/ecs-persistence`, in chapters, each its prose, `NN-name.md`,
+and a program, `NN-name.ts`, whose output is `NN-name.out`. The [interactive guide](../../../ecs-guide) shows them after
+the ECS's own chapters.
+
+1. [Saving and loading](01-saving.md)
+2. [Copying between worlds](02-copying.md)
+3. [Saving chunks](03-chunks.md)
+4. [Documents and settings](04-settings.md)

package/src/index.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Saving, loading and copying the entities of `@adobe/ecs` worlds: snapshots of the components and resources a trait of
+ * the application's own covers, as binary columns.
+ * @module @adobe/ecs-persistence
+ */
+export { decode } from "./decode.js";
+export { encode } from "./encode.js";
+export type { Failure } from "./failure.js";
+export { snapshot, type Snapshot } from "./snapshot.js";
+export { spawn, type Spawned } from "./spawn.js";