@adobe/ecs 0.1.0 → 0.2.1

package/src/observe/plans.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component, Entity } from '../interface/index.js';
 import { compare, compareNumbers } from './compare.js';
 

package/src/observe/query.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../interface/index.js';
 
 type Comparison<T> = {
@@ -9,7 +10,7 @@ type Comparison<T> = {
     readonly ">="?: T;
 };
 
-type ValuesOf<C extends readonly Component.Key[]> = { readonly [K in C[number]]: Component.Value<K> };
+type ValuesOf<C extends readonly Component.Key[]> = { readonly [K in C[number]]: Component<K> };
 
 /**
  * Entities that have every component in `required`, every entity but the resource entity without it, and none in

package/src/observe/resource.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { System, type Resource, type World } from '../interface/index.js';
 import type { Observe } from './observe.js';
-import { createEntry, give, giveFirst, none, noDelivery, ownName, passed, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed, type Entry, type Read, type Shape, type WorldState } from './world-state.js';
+import { createEntry, give, giveFirst, labelled, none, noDelivery, passed, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed, type Entry, type Read, type Shape, type WorldState } from './world-state.js';
 
 /**
  * A resource's observers, sharing one value: `notifier`, added, gives the value after each pass whose sync point
@@ -27,17 +28,17 @@ const shapes = new WeakMap<WorldState, Map<Resource.Key, ResourceShape>>();
 
 const createShape = (state: WorldState, byKey: Map<Resource.Key, ResourceShape>, key: Resource.Key): ResourceShape => {
     const entry = createEntry<unknown>(undefined);
-    const label = ownName(`Observe.resource(${key.description ?? "?"})`);
+    const label = `Observe.resource(${key.description ?? "?"})`;
     // On a joined thread, first values come once a run of this system resolved, never in its pass: none to skip.
     const { joined } = state;
-    const notifier = System.create({ name: label, observer: true, resources: { read: [key], changed: [key] } }, ({ resources }) => {
+    const notifier = System.create(labelled({ observer: true, resources: { changed: [key] } }, label, { resources: [key] }), ({ resources }) => {
         passed(state);
         entry.value = resources[key];
         entry.valid = true;
         if (entry.stopped > 0) sweepSubscribers(entry);
         throwFailed(give(entry, 0, true, state.pass, joined ? -1 : state.pass, none));
     });
-    const reader = System.create({ name: label, observer: true, resources: { read: [key] } }, ({ resources }) => {
+    const reader = System.create(labelled({ observer: true }, label, { resources: [key] }), ({ resources }) => {
         const through = shape.called.shift() ?? 0;
         entry.value = resources[key];
         entry.valid = true;

package/src/observe/select.ts

@@ -1,9 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Index, System, type Component, type Entity, type World } from '../interface/index.js';
 import { compare, predicateOf } from './compare.js';
 import type { Observe } from './observe.js';
 import { createAll, createCount, createHeap, createSorted, inEntityOrder, indexOf, type Gather, type Page, type Term, type Values } from './plans.js';
 import {
-    createEntry, deliverAlso, give, giveFirst, keysId, labelOf, none, noDelivery, numberOf, ownName, passed, scheduleDelivery, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed,
+    createEntry, deliverAlso, give, giveFirst, keysId, labelOf, labelled, none, noDelivery, numberOf, passed, scheduleDelivery, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed,
     type Entry, type Read, type Shape, type WorldState,
 } from './world-state.js';
 
@@ -71,8 +72,8 @@ const shapes = new WeakMap<WorldState, Map<string, QueryShape>>();
 type Rows = { readonly length: number; readonly changed: boolean; at(index: number): { readonly entity: Entity } & Values };
 
 /** Indexes the trackers look up through, by declaration: one each in the program. */
-const keyless = new Map<string, Index<{ readonly key: readonly []; readonly components: { readonly has: readonly Component.Key[]; readonly not: readonly Component.Key[] } }>>();
-const sortedIndexes = new Map<string, Index<{ readonly key: readonly Component.Key[]; readonly sorted: true; readonly components: { readonly has: readonly Component.Key[]; readonly not: readonly Component.Key[] } }> | null>();
+const keyless = new Map<string, Index<{ readonly key: readonly []; readonly components: { readonly with: readonly Component.Key[]; readonly not: readonly Component.Key[] } }>>();
+const sortedIndexes = new Map<string, Index<{ readonly key: readonly Component.Key[]; readonly sorted: true; readonly components: { readonly with: readonly Component.Key[]; readonly not: readonly Component.Key[] } }> | null>();
 
 /**
  * Whether `not` excludes none of `held`, an index's key parts and `has`: what an index declaration's type checks of
@@ -92,7 +93,7 @@ const excluding = (not: readonly Component.Key[], held: readonly Component.Key[]
 const keylessOf = (has: readonly Component.Key[], not: readonly Component.Key[]) => {
     const id = `${keysId(has)}|${keysId(not)}`;
     let index = keyless.get(id);
-    if (index === undefined) keyless.set(id, index = Index.create({ name: `Observe.query(${labelOf(has)})`, key: [], components: { has: [...has], not: excluding(not, has) } }));
+    if (index === undefined) keyless.set(id, index = Index.create(labelled({ key: [], components: { with: [...has], not: excluding(not, has) } }, `Observe.query(${labelOf(has)})`)));
     return index;
 };
 
@@ -102,7 +103,7 @@ const sortedOf = (key: readonly Component.Key[], has: readonly Component.Key[],
     let index = sortedIndexes.get(id);
     if (index === undefined) {
         try {
-            index = Index.create({ name: `Observe.query(${labelOf(has)}) by ${labelOf(key)}`, key: [...key], sorted: true, components: { has: [...has], not: excluding(not, [...key, ...has]) } });
+            index = Index.create(labelled({ key: [...key], sorted: true, components: { with: [...has], not: excluding(not, [...key, ...has]) } }, `Observe.query(${labelOf(has)}) by ${labelOf(key)}`));
         }
         catch {
             index = null;
@@ -160,7 +161,7 @@ const rangeOf = (condition: unknown): Range => {
     return bounds.length === 0 ? unbounded : { range, bounds, exact };
 };
 
-type Value = Component.Value<Component.Key>;
+type Value = Component<Component.Key>;
 
 /** A value or comparison a sorted index on one key part looks up by. */
 type Bound = Value | { readonly "<="?: Value; readonly ">="?: Value; readonly "=="?: Value };
@@ -178,7 +179,7 @@ const rangedOf = (key: Component.Key, has: readonly Component.Key[], not: readon
     let index = rangedIndexes.get(id);
     if (index === undefined) {
         try {
-            index = Index.create({ name: `Observe.query(${labelOf(has)}) by ${labelOf([key])}`, key: [key], sorted: true, components: { has: [...has], not: excluding(not, [key, ...has]) } });
+            index = Index.create(labelled({ key: [key], sorted: true, components: { with: [...has], not: excluding(not, [key, ...has]) } }, `Observe.query(${labelOf(has)}) by ${labelOf([key])}`));
         }
         catch {
             index = null;
@@ -187,12 +188,12 @@ const rangedOf = (key: Component.Key, has: readonly Component.Key[], not: readon
     }
     return index;
 };
-const rangedIndexes = new Map<string, Index<{ readonly key: readonly [Component.Key]; readonly sorted: true; readonly components: { readonly has: readonly Component.Key[]; readonly not: readonly Component.Key[] } }> | null>();
+const rangedIndexes = new Map<string, Index<{ readonly key: readonly [Component.Key]; readonly sorted: true; readonly components: { readonly with: readonly Component.Key[]; readonly not: readonly Component.Key[] } }> | null>();
 
 const createShape = (state: WorldState, byShape: Map<string, QueryShape>, id: string, counting: boolean, impossible: boolean, paged: boolean, required: readonly Component.Key[], not: readonly Component.Key[], where: readonly Component.Key[], terms: readonly Term[]): QueryShape => {
     const reads = unique([...where, ...terms.map(term => term.key)]);
     const has = unique([...required, ...reads]);
-    const name = ownName(`Observe.${counting ? "count" : "select"}(${labelOf(required)})`);
+    const name = `Observe.${counting ? "count" : "select"}(${labelOf(required)})`;
     const direction = terms.length > 0 && terms.every(term => term.ascending === terms[0].ascending) ? terms[0].ascending : null;
     const sortedKey = terms.map(term => term.key);
     // On a joined thread, a selection without a page sorts there, through an index without a key, rather than having
@@ -402,16 +403,16 @@ const createShape = (state: WorldState, byShape: Map<string, QueryShape>, id: st
     };
 
     const tracker = ordered !== null
-        ? System.create({ name, observer: true, lookup: { list: { index: ordered, read: reads, changed: reads } } }, ({ lookup }) => {
+        ? System.create(labelled({ observer: true, lookup: { list: { index: ordered, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
             track(lookup.list(), null, fromSorted);
         })
         : byRange !== null
-            ? System.create({ name, observer: true, lookup: { list: { index: byRange, read: reads, changed: reads } } }, ({ lookup }) => {
+            ? System.create(labelled({ observer: true, lookup: { list: { index: byRange, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
                 // A range is of a `where` condition on the index's key, which the query's type checked against its
                 // values.
                 track(null, entry => ownRange(entry, range => lookup.list(range as Parameters<typeof lookup.list>[0]), () => lookup.list()), fromSorted);
             })
-            : System.create({ name, observer: true, lookup: { list: { index: keylessOf(has, not), read: reads, changed: reads } } }, ({ lookup }) => {
+            : System.create(labelled({ observer: true, lookup: { list: { index: keylessOf(has, not), changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
                 track(lookup.list(), null, fromKeyless);
             });
 
@@ -465,7 +466,7 @@ const createShape = (state: WorldState, byShape: Map<string, QueryShape>, id: st
         for (const entry of scan.entries) entry.gather.start();
         accept = acceptOf(scan.entries);
     };
-    const scanner = System.create({ name, observer: true, components: { read: reads, has: required.filter(key => !reads.includes(key)), not } }, row => {
+    const scanner = System.create(labelled({ observer: true, components: { with: [...reads, ...required.filter(key => !reads.includes(key))], not } }, name, { components: reads }), row => {
         if (accept === null) start();
         if (direct === 0) {
             accept?.(row);

package/src/observe/to-promise.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Observe } from './observe.js';
 
 /** The first value an observer gets; it stops observing after it, even when that value comes during the subscribing call. */

package/src/observe/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../data/tsconfig-base.json",
+  "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "rootDir": "..",
     "outDir": "../../dist",

package/src/observe/values.ts

@@ -1,9 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component, Resource } from '../interface/index.js';
 
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 
 /** Component `K`'s value as observers give it: read-only, with branded primitives such as `Entity` as they are. */
-export type ReadonlyValue<K extends Component.Key> = Component.Value<K> extends Primitive ? Component.Value<K> : Readonly<Component.Value<K>>;
+export type ReadonlyType<K extends Component.Key> = Component<K> extends Primitive ? Component<K> : Readonly<Component<K>>;
 
 /** Resource `K`'s value as observers give it. */
-export type ReadonlyResourceValue<K extends Resource.Key> = Resource.Value<K> extends Primitive ? Resource.Value<K> : Readonly<Resource.Value<K>>;
+export type ReadonlyResourceType<K extends Resource.Key> = Resource<K> extends Primitive ? Resource<K> : Readonly<Resource<K>>;

package/src/observe/world-state.ts

@@ -1,4 +1,5 @@
-import { Report, System, type World } from '../interface/index.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System, type World } from '../interface/index.js';
 
 // What the factories keep for each world: the values observers share, their subscribers, and the observer systems that
 // read the world for them. Every shape of observer is one observer system, never one per subscriber or entity.
@@ -68,13 +69,6 @@ export type WorldState = {
     readonly deliver: System;
     /** What a rejected run of the factories' own does. */
     readonly rejected: (error: unknown) => void;
-    /**
-     * The factories' own runs, by number, with how many of each one's report's failures were rethrown; and the
-     * failures of the factories' systems in reports of runs not known to be theirs yet, by run.
-     */
-    /** Run with each of the factories' own systems, as a composite: what reads the reports their runs gave. */
-    readonly rethrow: System;
-    readonly composites: WeakMap<System, System>;
 };
 
 const states = new WeakMap<World, WorldState>();
@@ -84,16 +78,37 @@ export const rethrowLater = (error: unknown): void => {
     queueMicrotask(() => { throw error; });
 };
 
+/** The registry's map of labels (`@adobe/ecs/labels@1`), which the plugin fills for declarations made in functions. */
+const labels = Symbol.for("@adobe/ecs/labels@1");
+
+/** The registry's map of what bodies use (`@adobe/ecs/access@1`), which the plugin fills from bodies it can follow. */
+const access = Symbol.for("@adobe/ecs/access@1");
+
+/** What a factory's body reads: of its row, of resources, and of each lookup's rows. Factories' systems only read. */
+type Reads = {
+    readonly components?: readonly symbol[];
+    readonly resources?: readonly symbol[];
+    readonly lookup?: { readonly [name: string]: readonly symbol[] };
+};
+
 /**
- * The names of the systems the factories make. A run of theirs runs every observer system the world added too; only
- * these systems' failures are the factories' to rethrow.
+ * Labels a declaration of a system or index the factories make, gives it what its body reads, since the keys it reads
+ * are values the build can't follow, and returns it.
  */
-const ownNames = new Set<string>();
-
-/** Names a system the factories make. */
-export const ownName = (name: string): string => {
-    ownNames.add(name);
-    return name;
+export const labelled = <const D extends object>(declaration: D, label: string, reads: Reads = {}): D => {
+    let map: unknown = Reflect.get(globalThis, labels);
+    if (!(map instanceof WeakMap || map instanceof Map)) Reflect.set(globalThis, labels, map = new WeakMap<object, string>());
+    if (map instanceof WeakMap || map instanceof Map) map.set(declaration, label);
+    let uses: unknown = Reflect.get(globalThis, access);
+    if (!(uses instanceof WeakMap)) Reflect.set(globalThis, access, uses = new WeakMap<object, unknown>());
+    if (uses instanceof WeakMap) uses.set(declaration, {
+        components: { read: reads.components ?? [], write: [] },
+        resources: { read: reads.resources ?? [], write: [], reduce: [] },
+        lookup: reads.lookup ?? {},
+        up: [],
+        at: label,
+    });
+    return declaration;
 };
 
 const ignore = (): void => {
@@ -101,7 +116,7 @@ const ignore = (): void => {
 };
 
 /** Runs nothing: a run of it resolves while its world lives. */
-const alive = System.create({ name: ownName("Observe/alive"), observer: true }, () => {});
+const alive = System.create(labelled({ observer: true }, "Observe/alive"), () => {});
 
 /**
  * What a rejected run of the factories' own does: nothing for a disposed world, whose first values never come, and for
@@ -112,20 +127,18 @@ const rejectedOf = (world: World) => (error: unknown): void => {
 };
 
 /**
- * A run of the factories' own, whose report nothing reads: its failures of their systems, and its rejection, are
- * rethrown out of band.
+ * A run of the factories' own: its rejection, as when one of their systems failed, is rethrown out of band, and what
+ * observer systems the world added threw the world reports itself.
  */
 const runOwn = (state: WorldState, system: System): void => {
-    let composite = state.composites.get(system);
-    if (composite === undefined) state.composites.set(system, composite = System.create([system, state.rethrow]));
-    state.world.run(composite).then(undefined, state.rejected);
+    state.world.run(system).then(undefined, state.rejected);
 };
 
 const noTasks: readonly (() => void)[] = [];
 
 /**
- * A run of a joined thread's shape for first values: once it resolved, a post for it ran there, so `read` gives them.
- * What its system threw is in a later report of the world's.
+ * A run of a joined thread's shape for first values: once it resolved, a post for it ran there, so `read` gives them;
+ * what its system threw rejects it, rethrown out of band.
  */
 const runJoined = (state: WorldState, read: Read, batch: number): void => {
     state.world.run(read.system).then(() => read.delivered(batch), state.rejected);
@@ -173,7 +186,7 @@ const sweepShapes = (state: WorldState): void => {
 };
 
 /** A system no world adds, which only a joined thread's `remove` refuses, since it isn't an observer. */
-const probe = System.create({ name: "Observe/probe" }, () => {});
+const probe = System.create(labelled({}, "Observe/probe"), () => {});
 
 /** Whether `world` is a joined thread's: its `remove` takes only observer systems, where the world's ignores one never added. */
 const isJoined = (world: World): boolean => {
@@ -219,13 +232,7 @@ export const stateOf = (world: World): WorldState => {
         deliveries: [],
         idle: [],
         rejected: rejectedOf(world),
-        // Run with the factories' own systems, never added: what one of them throws is in a later report, whose errors
-        // are written once, which the next of the factories' runs sees.
-        rethrow: System.create({ name: ownName("Observe/rethrow"), observer: true, components: { read: [Report.errors], changed: [Report.errors] } }, row => {
-            for (const failure of row[Report.errors].failures) if (ownNames.has(failure.name)) rethrowLater(new Error(`${failure.name}: ${failure.message}`));
-        }),
-        composites: new WeakMap(),
-        deliver: System.create({ name: ownName("Observe/deliver"), observer: true }, () => {
+        deliver: System.create(labelled({ observer: true }, "Observe/deliver"), () => {
             const delivery = created.deliveries.shift();
             if (delivery === undefined) return;
             created.delivered = delivery.batch;
@@ -236,7 +243,7 @@ export const stateOf = (world: World): WorldState => {
     states.set(world, created);
     if (joined) return created;
     // Added before any shape's system, so in each pass it counts the pass before they run.
-    world.add(System.create({ name: ownName("Observe/maintain"), observer: true }, () => {
+    world.add(System.create(labelled({ observer: true }, "Observe/maintain"), () => {
         created.pass++;
         if (created.idle.length > 0) sweepShapes(created);
     }));
@@ -389,7 +396,7 @@ export const giveFirst = <T>(state: WorldState, entry: Entry<T>, through: number
     give(entry, through, false, state.pass, -1, none);
 };
 
-/** Throws what a notify threw, so its system's run reports it. */
+/** Throws what a notify threw, so its system fails. */
 export const throwFailed = (failed: unknown): void => {
     if (failed !== none) throw failed;
 };

package/src/observe-imports.test.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { readdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

package/src/perftest/benchmark.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /** A benchmark and what it stands for, so its results read without its code. */
 export type Benchmark = {
     /** Stable across runs: results are tracked by it. */

package/src/perftest/benchmarks.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from "../interface/component/component.js";
 import type { Entity } from "../interface/entity/entity.js";
 import { World } from "../interface/world/world.js";
@@ -20,14 +21,20 @@ import { readBenchmarks } from "./reads.js";
 import { observedBenchmarks } from "./observed.js";
 import { systemBenchmarks } from "./systems.js";
 import { indexBenchmarks } from "./indexes.js";
+import { editorBenchmarks } from "./editor.js";
 import { stringBenchmarks } from "./strings.js";
 import { structReplace, valueBenchmarks } from "./values.js";
+import { filterBenchmarks } from "./filters.js";
+import { optionalBenchmarks } from "./optional.js";
+import { sharedBenchmarks } from "./shared.js";
 import { createWorld } from "../implementation/index.js";
 import { workers } from "../interface/resources/workers.js";
 // Last, so the bundle orders the modules the benchmarks share as it did before these imports.
 import { System } from "../interface/system/system.js";
 import { Observe } from "../observe/index.js";
 import { entitiesWith } from "./observer.js";
+import { invariantBenchmarks } from "./invariants.js";
+import { journalBenchmarks } from "./journal.js";
 
 /** A world whose kernels run on this thread, which the benchmarks without a placement measure; `workers` ones use the pool. */
 const inline = (): World => createWorld({ [workers]: 0 });
@@ -49,14 +56,15 @@ const observed = async (world: World, writer: typeof poke | typeof pokeCluster):
     return best;
 };
 
-/** The fastest run of `measured` right after `before` runs, over `rounds` rounds after `warmup`. */
+/** The fastest run of `measured` right after `before` runs, over `rounds - warmup` rounds after a warmup of `warmup`. */
 const after = async (before: () => Promise<unknown>, measured: () => Promise<unknown>, rounds = 100, warmup = 20): Promise<number> => {
     let best = Infinity;
-    for (let i = 0; i < rounds; i++) {
+    const warm = warmup;
+    for (let i = 0; i < warm + rounds - warmup; i++) {
         await before();
         const start = performance.now();
         await measured();
-        if (i >= warmup) best = Math.min(best, performance.now() - start);
+        if (i >= warm) best = Math.min(best, performance.now() - start);
     }
     return best;
 };
@@ -99,10 +107,13 @@ const chunkScan = 8 / 1024;
 /** A run's fixed cost at best: it reads one cache line of its system's state. */
 const runBest = { bytes: 64, basis: "A run reads at least one cache line of its system's state." };
 
-/** Benchmarks shared by vitest (`*.perf-test.ts`) and the bundled node runner (`run.ts`). */
+/** Takes a rejection, as a benchmark of failing runs does. */
+const ignore = (): void => {};
+
 /** The pool's benchmarks node runs too, on `worker_threads`. */
 const pooledInNode = new Set(["move workers", "follow workers", "emit workers", "spawn bulk kernel workers", "sync point grow 100 archetypes workers"]);
 
+/** Benchmarks shared by vitest (`*.perf-test.ts`) and the bundled node runner (`run.ts`). */
 export const benchmarks: readonly Benchmark[] = [
     {
         name: "run idle",
@@ -120,15 +131,14 @@ export const benchmarks: readonly Benchmark[] = [
     },
     {
         name: "run failing",
-        operation: "Running one system that throws, in a world of 10K entities: each run spawns its report, and once runs pass the reports kept, despawns the oldest, against `run idle`.",
+        operation: "Running one system that throws, in a world of 10K entities: each run rejects with an Error naming it, against `run idle`.",
         per: "runs",
         n: 1,
         typical: [1, 1],
         best: runBest,
         run: async () => {
             const world = await seeded(() => inline(), 10_000);
-            // Past the reports kept, so each timed run despawns one too, as a failing run does in steady state.
-            const best = await fastest(() => world.run(failing), 1000, 300);
+            const best = await fastest(() => world.run(failing).then(undefined, ignore), 1000, 300);
             await world.dispose();
             return best;
         },
@@ -495,7 +505,7 @@ export const benchmarks: readonly Benchmark[] = [
         run: async () => {
             const { world, roots } = await filteredForest();
             const found: { child: Entity | null } = { child: null };
-            await world.run(System.create({ observer: true, components: { read: [hierarchyParent] } }, row => {
+            await world.run(System.create({ observer: true, components: { with: [hierarchyParent] } }, row => {
                 if (found.child === null && row[hierarchyParent] === roots[0]) found.child = row.entity;
             }));
             const { child } = found;
@@ -686,7 +696,13 @@ export const benchmarks: readonly Benchmark[] = [
     ...observedBenchmarks,
     ...systemBenchmarks,
     ...indexBenchmarks,
+    ...editorBenchmarks,
     ...stringBenchmarks,
     ...valueBenchmarks,
     structReplace("main", 0),
+    ...filterBenchmarks,
+    ...optionalBenchmarks,
+    ...sharedBenchmarks,
+    ...invariantBenchmarks,
+    ...journalBenchmarks,
 ];

package/src/perftest/editor.ts

@@ -0,0 +1,126 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity } from "../interface/entity/entity.js";
+import { Index } from "../interface/indexes/index-type.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { createWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+
+// A 2D editor loading a document: a tree of groups and leaves, a sorted paint-order index, a hash index of children
+// by parent, and `up` systems with change filters propagating transforms and opacity down the tree.
+
+const localX = Symbol("editor/localX");
+const localY = Symbol("editor/localY");
+const worldX = Symbol("editor/worldX");
+const worldY = Symbol("editor/worldY");
+const opacity = Symbol("editor/opacity");
+const worldOpacity = Symbol("editor/worldOpacity");
+const paintDepth = Symbol("editor/paintDepth");
+const parent = Symbol("editor/parent");
+const group = Symbol("editor/group");
+const shape = Symbol("editor/shape");
+const image = Symbol("editor/image");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [localX]: { type: number };
+        [localY]: { type: number };
+        [worldX]: { type: number };
+        [worldY]: { type: number };
+        [opacity]: { type: number };
+        [worldOpacity]: { type: number };
+        [paintDepth]: { type: number };
+        [parent]: { type: Entity; reference: "owner" };
+        [group]: { type: true };
+        [shape]: { type: true };
+        [image]: { type: true };
+    }
+}
+
+const node = [localX, localY, worldX, worldY, opacity, worldOpacity, paintDepth] as const;
+const Document = [...node, group] as const;
+const Group = [...node, parent, group] as const;
+const Shape = [...node, parent, shape] as const;
+const Image = [...node, parent, image] as const;
+
+const byPaintDepth = Index.create({ key: [paintDepth], sorted: true });
+const childrenOf = Index.create({ key: [parent] });
+
+/** Groups under the document, subgroups in each, and leaves in each subgroup: 50,201 nodes. */
+const groups = 200;
+const subgroups = 2;
+const leaves = 124;
+const nodes = 1 + groups * (1 + subgroups * (1 + leaves));
+
+/** Spawns the document depth first, as a file lists it, its paint depth its place in that order. */
+const load = System.create({}, ({ commands }) => {
+    let depth = 0;
+    const values = (x: number) => ({ [localX]: x, [localY]: 1, [worldX]: 0, [worldY]: 0, [opacity]: 0.99, [worldOpacity]: 1, [paintDepth]: depth++ });
+    const document = commands.spawn(Document)(values(0));
+    for (let g = 0; g < groups; g++) {
+        const outer = commands.spawn(Group)({ ...values(g), [parent]: document, [group]: true });
+        for (let s = 0; s < subgroups; s++) {
+            const inner = commands.spawn(Group)({ ...values(s), [parent]: outer, [group]: true });
+            for (let l = 0; l < leaves; l++) {
+                if (l % 2 === 0) commands.spawn(Shape)({ ...values(l), [parent]: inner, [shape]: true });
+                else commands.spawn(Image)({ ...values(l), [parent]: inner, [image]: true });
+            }
+        }
+    }
+});
+
+/** Each node's world position is its parent's plus its own. */
+const place = System.create({
+    kernel: false,
+    components: { with: [localX, localY, worldX, worldY], changed: [localX, localY] },
+    up: { through: parent },
+}, (row, { up }) => {
+    row[worldX] = (up === null ? 0 : up[worldX]) + row[localX];
+    row[worldY] = (up === null ? 0 : up[worldY]) + row[localY];
+});
+/** Each node's world opacity is its parent's times its own. */
+const fade = System.create({
+    kernel: false,
+    components: { with: [opacity, worldOpacity], changed: [opacity] },
+    up: { through: parent },
+}, (row, { up }) => {
+    row[worldOpacity] = (up === null ? 1 : up[worldOpacity]) * row[opacity];
+});
+let checksum = 0;
+/** Each group counts its children, as a layout does. */
+const layout = System.create({ components: { with: [group] }, lookup: { children: { index: childrenOf } } }, (row, { lookup }) => {
+    checksum += lookup.children(row.entity).length;
+});
+/** Visits every node in paint order, as drawing does. */
+const paint = System.create({ components: { with: [worldX, worldOpacity] }, order: byPaintDepth, after: [place, fade] }, row => {
+    checksum = (checksum * 31 + row[worldX] * row[worldOpacity]) % 1000003;
+});
+const frame = System.create({ systems: [place, fade, layout, paint] });
+
+const check = (condition: boolean, message: string): void => {
+    if (!condition) throw new Error(message);
+};
+
+export const editorBenchmarks: readonly Benchmark[] = [{
+    name: "editor load tick 50K",
+    operation: "A 2D editor's first tick after loading a 50K-node document of groups and leaves: two `up` systems with change filters propagate transforms and opacity down the tree, a layout looks up children through a hash index on the parent, and painting runs in a sorted index's order, so every `up` order and index is built from scratch.",
+    per: "nodes",
+    n: nodes,
+    typical: [1_000, 100_000],
+    best: { bytes: 100, basis: "Each node reads its parent link, its 7 values and its parent's 3, writes 3, and enters two indexes and two orders." },
+    run: async () => {
+        let best = Infinity;
+        for (let i = 0; i < 8; i++) {
+            const world = createWorld({ [workers]: 0 });
+            await world.run(frame);
+            await world.run(load);
+            checksum = 0;
+            const start = performance.now();
+            await world.run(frame);
+            best = Math.min(best, performance.now() - start);
+            check(checksum !== 0, "editor load tick: nothing ran");
+            await world.dispose();
+        }
+        return best;
+    },
+}];
+