@adobe/ecs-persistence 0.0.1 → 0.1.0

package/dist/types/snapshot.d.ts

@@ -1,18 +1,28 @@
 import type { World } from "@adobe/ecs";
 import type { Failure } from "./failure.js";
 import { contents, type Contents } from "./program/contents.js";
+import { type NamingTrait } from "./program/program.js";
 import { type Selection } from "./selection/selection.js";
-/** The persisted part of some of a world's entities and its persisted resources, which `encode` and `spawn` take. */
+/**
+ * What a trait covers of some of a world's entities and of its resources, which `encode` and `spawn` take, and the
+ * trait it was taken or read by.
+ */
 export type Snapshot = {
     readonly failure?: undefined;
     readonly [contents]: Contents;
 };
 /**
- * A snapshot of some of `world`'s entities, read on its thread: by default every entity holding a persisted
- * component, and the persisted resources; with `with` and `not`, those a query matches, and the resources unless
- * `resources` is false; with `root`, it and every entity it owns, through persisted owner references, without
- * resources. Fails, as data, when the program's persisted keys can't be saved or the world can't be read.
+ * A snapshot of some of `world`'s entities, read on its thread, by the trait `by`: a trait of the application's own,
+ * whose value on a component's or resource's declaration is the name it's saved under. Of each entity it takes, it
+ * takes the components the trait covers. By default it takes every entity holding one of them, and the resources the
+ * trait covers; with `with` and `not`, those a query matches, and the resources unless `resources` is false; with
+ * `where`, those of the archetypes holding its values of shared components, as a system's `where` of values keeps it to
+ * them, read whole, so a snapshot of one value's entities costs what they hold, not the world; with `root`, it and every
+ * entity it owns, through owner references the trait covers, without resources. Fails, as data, when `by` isn't a
+ * symbol, what the trait covers can't be saved, `where` names what isn't a shared component or gives one a value not
+ * of its type, or the world can't be read.
  */
 export declare const snapshot: (input: {
     readonly world: World;
+    readonly by: NamingTrait;
 } & Selection) => Promise<Snapshot | Failure>;

package/dist/types/spawn.d.ts

@@ -1,10 +1,11 @@
 import { type Entity, type World } from "@adobe/ecs";
 import type { Failure } from "./failure.js";
+import { type Matching } from "./match/match.js";
 import type { Snapshot } from "./snapshot.js";
 /**
  * What `spawn` made: how many of the snapshot's entities it didn't spawn, those owned by an entity outside it; and,
- * unless asked not to, `entities`, each of the snapshot's entities to the one spawned for it, or null for one it
- * didn't spawn.
+ * unless asked not to, `entities`, each of the snapshot's entities to the one spawned for it, the one `match` found
+ * for it, or null for one it didn't spawn.
  */
 export type Spawned<Entities extends boolean = true> = {
     readonly failure?: undefined;
@@ -13,21 +14,29 @@ export type Spawned<Entities extends boolean = true> = {
     readonly entities: ReadonlyMap<Entity, Entity | null>;
 });
 /**
- * Spawns an entity in `world` for each of the snapshot's, with its persisted components, and sets the persisted
- * resources, on the world's thread, as the world's references would leave them had the entities outside the snapshot
+ * Spawns an entity in `world` for each of the snapshot's, with the components its trait covers, and sets the resources
+ * it holds, on the world's thread, as the world's references would leave them had the entities outside the snapshot
  * despawned: each entity value naming one of the snapshot's names the one spawned for it; an entity owned, directly
  * or through others, by an entity outside the snapshot isn't spawned, which the result counts; a weak reference to
- * one is left out; and any other entity value naming one is `Entity.none`. With `entities: false`, the result leaves
- * out its map of entities, which costs about 85 ms and 50 MB at a million. Fails, as data, for a column or
- * resource that doesn't fit, spawning nothing.
+ * one is left out; and any other entity value naming one is `Entity.none`.
+ * - `match`: unique indexes saying which of the snapshot's entities are already in `world`: one an index holds there,
+ *   with the key of one of the snapshot's it holds, stands for it, keeping its own values, and isn't spawned again. It
+ *   fails for an index whose key, `with` or `not` names a component the snapshot's trait doesn't cover, or two of the
+ *   snapshot's entities with one key.
+ * - `entities: false` leaves out the result's map of entities, which costs about 85 ms and 50 MB at a million.
+ *
+ * Fails, as data, for a column or resource that doesn't fit, spawning nothing.
  */
-export declare function spawn(input: {
-    readonly world: World;
-    readonly snapshot: Snapshot;
+export declare function spawn(input: Spawning & {
     readonly entities: false;
 }): Promise<Spawned<false> | Failure>;
-export declare function spawn(input: {
-    readonly world: World;
-    readonly snapshot: Snapshot;
+export declare function spawn(input: Spawning & {
     readonly entities?: true;
 }): Promise<Spawned | Failure>;
+/** What `spawn` takes: the world spawned into, the snapshot, and the indexes saying which of its entities are there already. */
+type Spawning = {
+    readonly world: World;
+    readonly snapshot: Snapshot;
+    readonly match?: readonly Matching[];
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/ecs-persistence",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Saving, loading and copying the entities of @adobe/ecs worlds, as binary columns",
   "license": "MIT",
   "type": "module",
@@ -19,13 +19,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@adobe/ecs": "0.2.3"
+    "@adobe/ecs": "0.2.4"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "typescript": "^5.8.3",
     "vite": "^8.3.4",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "ecs-guide-checks": "0.0.0"
   },
   "exports": {
     ".": {
@@ -33,6 +34,12 @@
       "types": "./dist/types/index.d.ts"
     }
   },
+  "guide": {
+    "files": [
+      "src/**/*.ts",
+      "dist/**/*.js"
+    ]
+  },
   "scripts": {
     "build": "cp ../../LICENSE . && tsc -p tsconfig.build.json && vite build",
     "typecheck": "tsc && tsc -p tsconfig.build.json",

package/src/decode.ts

@@ -2,14 +2,15 @@
 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, 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, or names a component or resource this
- * program doesn't persist, or persists with another schema.
+ * 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): Snapshot | Failure => {
-    const decoded = decodeContents(bytes);
+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

@@ -4,7 +4,7 @@ import { contents } from "./program/contents.js";
 import type { Snapshot } from "./snapshot.js";
 
 /**
- * A snapshot as bytes, little-endian: a header naming each persisted component and resource with its schema, then
- * 8-byte-aligned blocks of each table's entities and columns, its bytes columns copied whole.
+ * 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/format/format.ts

@@ -117,11 +117,11 @@ const headerOf = (json: unknown): Header | null => {
 const sameSchema = (a: Schema, b: Schema): boolean => JSON.stringify(a) === JSON.stringify(b);
 
 /**
- * The snapshot contents `bytes` holds, its components and resources by name as this program persists them, its blocks of
- * bytes viewed where they are; or why it can't be read: it isn't one, or names what this program doesn't persist, or
- * persists with another schema.
+ * 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): Contents | Failure => {
+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);
@@ -136,19 +136,19 @@ export const decodeContents = (bytes: Uint8Array): Contents | Failure => {
     }
     const header = headerOf(json);
     if (header === null) return { failure: "This snapshot's header isn't one this package writes." };
-    const program = programOf();
+    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 this program doesn't persist.` };
+        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 this program doesn't persist.` };
+        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) });
     }
@@ -181,5 +181,5 @@ export const decodeContents = (bytes: Uint8Array): Contents | Failure => {
         }
         tables.push({ count: table.count, entities: new Float64Array(blocks.buffer, base + table.entities, table.count), columns });
     }
-    return { components, tables, resources };
+    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

@@ -1,12 +1,11 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 /**
- * Saving, loading and copying the entities of `@adobe/ecs` worlds: snapshots of their persisted components and
- * resources, as binary columns.
+ * 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 { persist } from "./persist.js";
 export { snapshot, type Snapshot } from "./snapshot.js";
 export { spawn, type Spawned } from "./spawn.js";