@adobe/ecs 0.0.0-stage → 0.1.0

package/src/samples/todo/README.md

@@ -0,0 +1,174 @@
+# Todo sample
+
+A todo app whose world drives every change to the DOM through systems, while its elements know nothing about the ECS.
+It's the experiment for `ecs-dom.md`: vanilla custom elements, no framework, no persistence.
+
+`pnpm sample`, then open `/todo/`. Add, toggle, edit (double-click), delete, move (drag, or Alt+↑ and Alt+↓), mark all
+done or none, clear those done, filter, and generate 10 or 1,000 todos.
+
+## How the DOM is driven
+
+- **Elements** (`*/elements/`) take properties and dispatch DOM events. A property write that changes nothing is
+  dropped, and an element never changes a property its owner writes: a checkbox click dispatches `todo-toggle` and
+  leaves the row showing its `done` until the world writes it. State only the DOM owns stays there: the draft in the
+  entry, the editing state of a row, focus.
+- **Fixed elements**, those in `index.html`, are resources: each feature finds its own within the page's root when
+  the app starts. Every DOM system that uses one declares it in `resources.is`, so it's skipped in a world without it.
+- **Repeated elements** are component values on the entity they show, declared on `main`: a todo's `row`.
+  - *Created* by an ordinary system, `createRows`, over todos without a row, which adds the row by a command. It runs
+    on the tick after the run that added the todo, since observer systems can't issue commands.
+  - *Bound* by an observer system, `bindRows`, with the row and the values it shows in `changed`: it writes a new row
+    once and then only rows whose todo changed, after each run's and tick's sync point.
+  - *Placed* by an observer system, `placeRows`, which runs the rows whose row or order changed in list order, through
+    a sorted index, and puts each after the row before it, which is always placed already. A row already in place
+    isn't touched, and one in the list moves with `moveBefore`, never leaving it, so it keeps its focus; where the
+    browser has no `moveBefore`, it gets its focus back.
+  - *Filtered* by the filter feature's observer system, `filterRows`, which sets `hidden` on rows whose visibility
+    changes, as their todo or the filter changes, and moves focus off a row it hides to the nearest one shown.
+  - *Removed* by a finalizer on the row, which runs whatever ends the todo, `world.dispose()` included.
+  - Rows out of view skip their rendering (`content-visibility: auto`).
+- **Fixed elements showing counts** are bound by an observer system that runs only when an index's entries changed:
+  `bindCompletion` looks up `completion/byDone` with `changed: true`, so it writes the summary and the toggle-all box
+  after a pass in which a todo was added, removed or toggled, and is skipped before its body otherwise.
+- **Events become runs** in each feature's `events.ts`: listeners on the page's root call `world.run(system, input)`
+  and leave the promise; a rejected run goes unhandled, which the browser logs. An event from a row names its todo
+  through `entityOf(event)`, the entity the first target on its composed path shows: `createRows` attaches each row
+  to its todo (`attach`), and a move's `item` and `before` are read with `entityOfElement`. Systems acting on one
+  todo name it as their `target`, so they run on its row alone, writing it in place, and on nothing once it's gone.
+- **Failures** of runs and ticks alike are in their reports, entities the world keeps; the app adds `logFailures`, an
+  observer system with `changed: [Report.errors]` that logs them; each report's errors are written once, and an
+  observer pass's failures are in the next run's report.
+
+## Structure
+
+```
+index.html            the page: the fixed elements and their layout
+app/app.ts            defines the features' elements, creates the world through World.create and connects the events
+app/main.ts           starts the app on the page
+app/log-failures.ts   logFailures
+features/index.ts     exports every feature
+shared/feature.ts     Feature: what the app needs of a feature
+shared/connect.ts     on and all: listening for events, and stopping several listeners at once
+shared/attach.ts      attach, entityOf and entityOfElement: the entity an element shows, for its events
+shared/elements/      define: defining the elements features list
+features/<feature>/
+    data.ts           components, resources, archetypes and indexes: the feature's data
+    model.ts          systems with input, one per thing a user does: they change data and know no DOM
+    dom.ts            the components and resources holding elements, and the composite of the systems that drive them
+    events.ts         connect: DOM events to runs of the model's systems
+    elements/         custom elements, importing only each other
+    feature.ts        the feature as the app composes it
+```
+
+The features are `todos`; `filter`, `completion` and `generate` build on it. A feature imports only the layers of a
+feature it builds on, never one built on it, and never the app. Within one, `model` imports only `data`; `dom` imports
+`data` and its elements; `events` imports `model` and `dom`. Registration happens as modules load, so a feature's
+components, indexes and finalizers exist wherever one of its modules is imported, and `feature.ts` lists only what
+the app must do with it: its elements, by tag name, which the app defines; how it finds its fixed elements; its DOM
+systems as one composite, which the app adds; and how it connects its events. Elements are defined by the app rather
+than as their modules load: the package's `sideEffects: false` lets a bundle drop a module imported only for that.
+Adding a feature is a folder and a line in `features/index.ts`.
+
+## Tests
+
+- `*/model.test.ts`, in node: each feature's model systems against a world, read back through observer systems.
+- `*/elements/*.browser.test.ts`: elements alone, with no world: properties set, the render checked, events recorded.
+- `shared/attach.browser.test.ts`: the entity an element was attached to, found from an event on it or within its open
+  shadow root, and none for others.
+- `*/dom.browser.test.ts`: a feature's DOM systems driving real elements, after the loop ticks: rows inserted,
+  removed without a node left, moved with only the moved row touched and its focus kept, filtered with focus moved
+  off, edited; no rows without a list; none for a todo deleted before its tick; several runs before one tick; all
+  removed on dispose.
+- `app/app.browser.test.ts`: the whole app on the page's markup, used through DOM events as a user would, with no
+  console errors; edits committed on blur; a row's events after its todo is deleted; a tick's system's and observer
+  system's failures logged.
+- `app/proportional.browser.test.ts`: each operation's DOM mutations, and how often the DOM systems reach rows, are
+  the same with 100 todos as with 2,000, less what each row it changed costs.
+- `imports.test.ts`: the layer rules above, elements importing nothing but each other, and worlds, the tests' and
+  benchmarks' too, made only through `World.create` from the package root, never through the implementation.
+  `build.test.ts`: the page builds. `app/log-failures.test.ts`: a run's failures logged once each, an observer pass's at the next pass.
+- `app/todo.perf-browser-test.ts` and `app/profile.perf-browser-test.ts`, with `pnpm test:perf src/samples/todo`:
+  times, mutation counts and a profile, logged.
+
+## Performance
+
+Apple M1 Max, Chromium, with other benchmarks running on the machine. A run's time includes the observer systems
+after it; each is the median of 21 runs, each made after a rendered frame as an event's would be, unless it's a single
+pass. The tick after it is timed from its frame's start to the end of its observer systems. Mutations count the page's
+and its shadow roots' records until that tick ends.
+
+| Operation | 1K run ms | 10K run ms | Tick after, ms | Mutations |
+|---|---:|---:|---:|---:|
+| Run that changes nothing | 0.03–0.10 | 0.025 | 0.04–0.17 | 0 |
+| Toggle one | 0.15–0.41 | 0.14–0.18 | 0.05–0.19 | 2 |
+| Edit one | 0.10 | 0.06 | 0.03–0.06 | 1 |
+| Move last to first | 0.14 | 0.13–0.15 | 0.05 | 2 |
+| Add one, with its row | 0.27 | 0.26–0.31 | 0.05–0.08 | 4 |
+| Toggle all | 1.0 | 7.2–8.4 | 0.06 | 1 per todo, and 4 |
+| Filter half the rows | 0.28 | 2.1 | 0.05 | 1 per row hidden, and 2 |
+| Filter half the rows, laid out | 1.8 | 17 | 0.05 | 1 per row hidden, and 2 |
+| Generate N todos | 1.7 | 2.6–3.6 | — | not measured |
+| Create and place N rows | 9.8 | 94–114 | — | 3 per row |
+| Lay N rows out | 7.3 | 39 | — | — |
+
+Operations on one todo cost about the same at 1K and 10K; ranges are over runs on a busy machine. Moving a row by the
+DOM alone takes 0.075 ms of the move's 0.13. Back to back, runs cost far less than one made after a frame:
+`app/profile.perf-browser-test.ts` has a run that changes nothing at 2.5–3.7 µs in the app and 1.0 µs in an empty
+world, and toggling one at 26 µs with 1K todos, 62 µs with 10K and 400 µs with 100K (see Findings).
+
+## Findings
+
+What the current API does and doesn't offer the DOM path, each with the change it would take.
+
+- **Observer systems can't issue commands,** so a row is created by an ordinary system on the tick after the run that
+  added its todo. That tick runs at the next animation frame, before that frame is painted, so a row added in response
+  to an event shows in the frame that would have shown it anyway, at 0.05–0.08 ms. *No change needed.*
+- **Observer systems can't declare `up`.** A view entity of its own, `{ view, viewOf }`, can't be bound by an observer
+  through `up: { through: viewOf }`; as a ticking system, its writes come a tick late, and a new view's first only on
+  the tick after it's made. *Proposal:* allow `up` in observer systems, which only read through it.
+- **`order` can't go with `up`.** Views can't be placed in their models' order from a system over the views.
+  *Proposal:* let `order` take an index over the entity a reference names, or allow it with `up`.
+- **No index finds an entity by its element.** Object parts of index keys are interned by structure
+  (`index-keys.ts`, `canonical` is `JSON.stringify`), so every element is the same key `{}` and an index on `row`
+  can't tell rows apart. The sample attaches the entity to the element where the row is made, under a symbol only
+  `shared/attach.ts` holds, which costs one property per row and nothing per run. *No change needed.*
+- **A binding helper can't be typed** from the public types. A generic `bindProperties(element, { label, done })`
+  builds `components: { read: [element, ...keys] }` with keys widened to `keyof Components`, and `System.create`
+  rejects it: `Property '"error: its object components and resources live on different threads"' is missing`, since
+  any component might be on another thread; its body then reads by `Reflect`. *Proposal:* none unless bindings get
+  their own constructor; a binding is four to six lines.
+- **A run's fixed cost** in Chromium is small, and none of it is a task: a run that changes nothing takes 1.0 µs back
+  to back in an empty world, at most 0.3 µs more with the app's observer systems added, and 2.5 µs in the app
+  with 1K todos, where a
+  task round trip takes 7.6 µs. Node's `run idle` is 0.33 µs. A run made right after a frame, as an event's is, takes
+  0.02–0.10 ms, which is the CPU coming back from idle, not the ECS. Toggling one todo of 10K takes 62 µs, of which
+  the profile gives 64% to `mergeEntries` (`index-hash.ts`), keeping `completion/byDone`'s two buckets of 5K entries in
+  entity order, and 16% to `forEachPassingRange` (`ranges.ts`), the change filters scanning the 1024 row ticks of the
+  one chunk that changed, for each observer system with `changed`. The rest is the sync point, the observer pass and
+  the DOM writes, about 13 µs. *Proposals* in the next two findings.
+- **A low-cardinality hash index costs O(bucket) per change:** toggling one todo moves it between `byDone`'s buckets,
+  and each bucket's entries shift to stay in entity order: 26 µs a toggle at 1K, 62 at 10K, 400 at 100K. *Proposal:*
+  unordered buckets with swap-remove and a position per entity, sorted only when a list is read in entity order; or
+  a count-only index for what reads only `length`.
+- **A change filter scans a whole chunk for one changed row,** 1024 ticks for each system with `changed`. *Proposal:*
+  a second level of ticks per 32 or 64 rows, or a list of the rows changed per chunk.
+- **Nothing awaits the next tick.** Tests watch `clock` changes through an observer, after a first run that passes it
+  regardless, and a world ticks only while a system that isn't an observer is added. *Proposal:* none for consumers; a
+  test helper in `src/observe` would do.
+
+## Not kept
+
+- **Layers at the top**, one `data.ts`, `model.ts`, `dom.ts` and `events.ts` holding every feature's part: 27 files
+  instead of 47 and half the imports, but a feature's parts are spread over four files, its tests share files with
+  the others', nothing shows which feature builds on which, and removing one means editing every layer.
+- **The app composing each layer of each feature**, importing every feature's DOM systems, events, element
+  definitions and resource keys, and taking the fixed elements in a `Page`: the app knew every feature's insides, in
+  16 imports where it now has 4.
+- **Views as entities of their own**, `{ view, viewOf }`, bound through `up: { through: viewOf }`: the binding became
+  a ticking system (see Findings) whose creating system had to write a new view's first values itself, and placing
+  views in list order had to run over their todos. It was slower too: 107 ms instead of 98 to create 10K rows, 0.095
+  ms instead of 0.080 to toggle one. Nothing here shows a todo twice.
+- **Filtering by an attribute of the list**, which style sheets select rows by: one write instead of a pass over the
+  rows, 0.025 ms instead of 2.1 at 10K, but dearer once laid out, 25 ms against 17, since every row is restyled. It
+  also put the filter's meaning in the list's element.
+- **A helper building a binding**: see Findings.

package/src/samples/todo/app/app.browser.test.ts

@@ -0,0 +1,215 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { System } from "../../../index.js";
+import { todo } from "../features/todos/data.js";
+import { row } from "../features/todos/dom.js";
+import { part } from "../shared/elements/elements.test-helper.js";
+import { nextTick, watchTicks } from "../shared/ticks.test-helper.js";
+import { createApp, type App } from "./app.js";
+
+/** The page's markup, as index.html has it. */
+const markup = `
+<header><todo-toggle-all></todo-toggle-all><todo-entry></todo-entry></header>
+<todo-list></todo-list>
+<footer><todo-summary></todo-summary><todo-filters></todo-filters></footer>
+<todo-generate></todo-generate>`;
+
+const found = <K extends keyof HTMLElementTagNameMap>(name: K): HTMLElementTagNameMap[K] => {
+    const element = document.querySelector(name);
+    if (element === null) throw new Error(`No ${name}.`);
+    return element;
+};
+
+let app: App;
+let errors: unknown[];
+const logged = console.error;
+
+beforeEach(async () => {
+    errors = [];
+    console.error = (...values: unknown[]) => errors.push(values);
+    document.body.innerHTML = markup;
+    app = createApp(document.body);
+    await watchTicks(app.world);
+});
+
+afterEach(async () => {
+    await app.dispose();
+    console.error = logged;
+    document.body.replaceChildren();
+    expect(errors).toEqual([]);
+});
+
+const rows = (): HTMLElementTagNameMap["todo-row"][] => [...found("todo-list").querySelectorAll("todo-row")];
+/** What a user sees in the list: each shown row, `x` when done. */
+const shown = (): string[] => rows().filter(row => row.checkVisibility()).map(row => `${row.done ? "x" : "-"} ${row.label}`);
+const left = (): string => part(found("todo-summary"), ".count", HTMLElement).textContent ?? "";
+
+/** Types `text` into the entry and presses Enter. */
+const enter = (text: string): void => {
+    const input = part(found("todo-entry"), "input", HTMLInputElement);
+    input.value = text;
+    input.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter" }));
+};
+
+/** Enters a todo, and waits for the tick that shows it. */
+const type = async (text: string): Promise<void> => {
+    enter(text);
+    await nextTick();
+};
+
+const rowPart = <E extends Element>(index: number, selector: string, kind: abstract new () => E): E => {
+    const row = rows()[index];
+    if (row === undefined) throw new Error(`No row ${index}.`);
+    return part(row, selector, kind);
+};
+
+describe("the todo app", () => {
+    it("adds, toggles, edits and deletes todos as a user does", async () => {
+        // A blank entry dispatches nothing.
+        enter("   ");
+        await type("Buy milk");
+        await type("Walk the dog");
+        expect(shown()).toEqual(["- Buy milk", "- Walk the dog"]);
+        expect(left()).toBe("2 items left");
+
+        rowPart(1, ".toggle", HTMLInputElement).click();
+        await nextTick();
+        expect(shown()).toEqual(["- Buy milk", "x Walk the dog"]);
+        expect(left()).toBe("1 item left");
+
+        rowPart(0, ".label", HTMLElement).dispatchEvent(new MouseEvent("dblclick"));
+        const edit = rowPart(0, ".edit", HTMLInputElement);
+        edit.value = "Buy oat milk";
+        edit.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter" }));
+        await nextTick();
+        expect(shown()).toEqual(["- Buy oat milk", "x Walk the dog"]);
+
+        rowPart(0, ".delete", HTMLButtonElement).click();
+        await nextTick();
+        expect(shown()).toEqual(["x Walk the dog"]);
+        expect(rows()).toHaveLength(1);
+    });
+
+    it("filters, toggles all and clears completed", async () => {
+        for (const text of ["a", "b", "c"]) await type(text);
+        rowPart(1, ".toggle", HTMLInputElement).click();
+        await nextTick();
+        const filter = (name: string): void => part(found("todo-filters"), `[data-filter=${name}]`, HTMLButtonElement).click();
+        filter("active");
+        await nextTick();
+        expect(shown()).toEqual(["- a", "- c"]);
+        filter("completed");
+        await nextTick();
+        expect(shown()).toEqual(["x b"]);
+        filter("all");
+        await nextTick();
+
+        part(found("todo-toggle-all"), "input", HTMLInputElement).click();
+        await nextTick();
+        expect(shown()).toEqual(["x a", "x b", "x c"]);
+        expect(found("todo-toggle-all").checked).toBe(true);
+        part(found("todo-toggle-all"), "input", HTMLInputElement).click();
+        await nextTick();
+        expect(shown()).toEqual(["- a", "- b", "- c"]);
+
+        rowPart(0, ".toggle", HTMLInputElement).click();
+        rowPart(2, ".toggle", HTMLInputElement).click();
+        await nextTick();
+        part(found("todo-summary"), ".clear", HTMLButtonElement).click();
+        await nextTick();
+        expect(shown()).toEqual(["- b"]);
+        expect(rows()).toHaveLength(1);
+    });
+
+    it("moves todos with the keyboard and by dragging", async () => {
+        for (const text of ["a", "b", "c"]) await type(text);
+        rows()[2]?.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowUp", altKey: true, bubbles: true }));
+        await nextTick();
+        expect(shown()).toEqual(["- a", "- c", "- b"]);
+        const [a, , b] = rows();
+        if (a === undefined || b === undefined) throw new Error("No rows.");
+        const dataTransfer = new DataTransfer();
+        a.dispatchEvent(new DragEvent("dragstart", { bubbles: true, composed: true, dataTransfer }));
+        const bounds = b.getBoundingClientRect();
+        b.dispatchEvent(new DragEvent("drop", { bubbles: true, cancelable: true, composed: true, dataTransfer, clientY: bounds.bottom - 1 }));
+        await nextTick();
+        expect(shown()).toEqual(["- c", "- b", "- a"]);
+    });
+
+    it("generates todos and clears them all, leaving no rows", async () => {
+        part(found("todo-generate"), "[data-count='1000']", HTMLButtonElement).click();
+        await nextTick();
+        expect(rows()).toHaveLength(1000);
+        expect(left()).toBe("1000 items left");
+        part(found("todo-toggle-all"), "input", HTMLInputElement).click();
+        await nextTick();
+        part(found("todo-summary"), ".clear", HTMLButtonElement).click();
+        await nextTick();
+        expect(rows()).toHaveLength(0);
+        expect(found("todo-summary").hasAttribute("empty")).toBe(true);
+    });
+
+    it("commits an edit when its field loses focus", async () => {
+        await type("Buy milk");
+        rowPart(0, ".label", HTMLElement).dispatchEvent(new MouseEvent("dblclick"));
+        const edit = rowPart(0, ".edit", HTMLInputElement);
+        edit.value = "Buy oat milk";
+        edit.blur();
+        await nextTick();
+        expect(shown()).toEqual(["- Buy oat milk"]);
+    });
+
+    it("ignores what a row asks once its todo is deleted", async () => {
+        await type("a");
+        await type("b");
+        // Both events come before the delete's run applies, so the edit and toggle find no todo.
+        rowPart(0, ".delete", HTMLButtonElement).click();
+        rowPart(0, ".toggle", HTMLInputElement).click();
+        rows()[0]?.dispatchEvent(new CustomEvent("todo-edit", { detail: { label: "late" }, bubbles: true, composed: true }));
+        await nextTick();
+        expect(shown()).toEqual(["- b"]);
+    });
+
+    it("removes every row and stops listening when disposed", async () => {
+        for (const text of ["a", "b"]) await type(text);
+        await app.dispose();
+        expect(rows()).toHaveLength(0);
+        // Events after disposal start no runs, which would reject.
+        part(found("todo-entry"), "input", HTMLInputElement).value = "c";
+        part(found("todo-entry"), "input", HTMLInputElement).dispatchEvent(new KeyboardEvent("keydown", { key: "Enter" }));
+        expect(rows()).toHaveLength(0);
+    });
+});
+
+// It runs in the tick that gives the todo its row, alongside createRows.
+const failing = System.create({ name: "test/failing", components: { has: [todo] } }, () => {
+    throw new Error("a tick's system failed");
+});
+const failingObserver = System.create({ name: "test/failingObserver", observer: true, components: { has: [row], changed: [row] } }, () => {
+    throw new Error("a tick's observer failed");
+});
+const pass = System.create({ name: "test/pass", observer: true }, () => {});
+
+describe("the todo app's failures", () => {
+    /** The messages of the failures logged. */
+    const tickFailures = (): string[] => errors.flatMap(values => Array.isArray(values) && values[0] === "A run failed" && Array.isArray(values[1])
+        ? values[1].flatMap((failure: unknown) => typeof failure === "object" && failure !== null && "message" in failure ? [String(failure.message)] : [])
+        : []);
+
+    it("are logged when a tick's system fails, once each", async () => {
+        app.world.add(failing);
+        await type("a");
+        app.world.remove(failing);
+        await app.world.run(pass);
+        expect(tickFailures()).toEqual(["a tick's system failed"]);
+        errors.length = 0;
+    });
+
+    it("are logged when a tick's observer fails, by the next pass", async () => {
+        app.world.add(failingObserver);
+        await type("a");
+        app.world.remove(failingObserver);
+        await app.world.run(pass);
+        expect(tickFailures()).toEqual(["a tick's observer failed"]);
+        errors.length = 0;
+    });
+});

package/src/samples/todo/app/app.ts

@@ -0,0 +1,30 @@
+import { World, workers } from "../../../index.js";
+import * as exported from "../features/index.js";
+import { all } from "../shared/connect.js";
+import { define } from "../shared/elements/define.js";
+import type { Resources } from "../shared/feature.js";
+import { logFailures } from "./log-failures.js";
+
+/** The app's features, every one `features/index.ts` exports. Each knows only those it builds on; none knows the app. */
+const features = Object.values(exported);
+
+export type App = { readonly world: World; readonly dispose: () => Promise<void> };
+
+/**
+ * Starts the app on the page within `root`, its elements defined: a world whose DOM systems drive the page, holding
+ * the fixed elements its features find there, and whose runs the page's events start.
+ */
+export const createApp = (root: HTMLElement): App => {
+    for (const feature of features) define(feature.elements);
+    const world = World.create(features.reduce<Resources>((resources, feature) => ({ ...resources, ...feature.resources(root) }), { [workers]: 0 }));
+    for (const { system } of features) if (system !== null) world.add(system);
+    world.add(logFailures);
+    const disconnect = all(...features.map(feature => feature.connect(world, root)));
+    return {
+        world,
+        dispose: async () => {
+            disconnect();
+            await world.dispose();
+        },
+    };
+};

package/src/samples/todo/app/log-failures.test.ts

@@ -0,0 +1,28 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { System, World, workers } from "../../../index.js";
+import { logFailures } from "./log-failures.js";
+
+const fails = System.create({ name: "test/fails" }, () => {
+    throw new Error("broken");
+});
+const failsObserving = System.create({ name: "test/failsObserving", observer: true }, () => {
+    throw new Error("observer broken");
+});
+const nothing = System.create({ name: "test/nothing" }, () => {});
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+it("logs a run's failures once each, and an observer pass's at the next pass", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    await using world = World.create({ [workers]: 0 });
+    world.add(logFailures);
+    await world.run(fails);
+    expect(error).toHaveBeenCalledWith("A run failed", [expect.objectContaining({ kind: "system", message: "broken" })]);
+    world.add(failsObserving);
+    await world.run(nothing);
+    world.remove(failsObserving);
+    await world.run(nothing);
+    expect(error.mock.calls.map(([, failures]) => Array.isArray(failures) ? failures.map(failure => failure.message) : [])).toEqual([["broken"], ["observer broken"]]);
+});

package/src/samples/todo/app/log-failures.ts

@@ -0,0 +1,7 @@
+import { Report, System } from "../../../index.js";
+
+/** Logs what reports say failed, a run's an event started and a tick's alike: each report's errors are written once. */
+export const logFailures = System.create({ name: "app/logFailures", observer: true, components: { read: [Report.errors], changed: [Report.errors] } }, row => {
+    const { failures } = row[Report.errors];
+    if (failures.length > 0) console.error("A run failed", failures);
+});

package/src/samples/todo/app/main.ts

@@ -0,0 +1,4 @@
+import { createApp } from "./app.js";
+
+/** The todo sample's page: its markup holds the fixed elements, and the app's world drives them. */
+createApp(document.body);

package/src/samples/todo/app/profile.perf-browser-test.ts

@@ -0,0 +1,100 @@
+/// <reference types="@vitest/browser-playwright" />
+import { it } from "vitest";
+import { cdp } from "vitest/browser";
+import { Entity, System, World, workers } from "../../../index.js";
+import { bindCompletion } from "../features/completion/dom.js";
+import { bindFilters, filterRows } from "../features/filter/dom.js";
+import { addGenerated } from "../features/generate/model.js";
+import { bindRows, createRows, placeRows } from "../features/todos/dom.js";
+import { toggleTodo } from "../features/todos/model.js";
+import { entityOfElement } from "../shared/attach.js";
+import { createApp, type App } from "./app.js";
+import { logFailures } from "./log-failures.js";
+
+/**
+ * Where a run's fixed cost goes in Chromium: runs timed one at a time and back to back, in a world gaining the app's
+ * observer systems one by one and in the app at three sizes, then a sampled profile of toggling at 10K. Logged, never
+ * asserted: `pnpm test:perf src/samples/todo`.
+ */
+
+const nothing = System.create({ name: "profile/nothing" }, () => {});
+const median = (values: readonly number[]): number => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)] ?? NaN;
+
+/** The median of `repeats` runs awaited one at a time, and the mean of as many issued back to back. */
+const timeRuns = async (run: (repeat: number) => Promise<unknown>, repeats: number): Promise<string> => {
+    const times: number[] = [];
+    for (let repeat = 0; repeat < repeats; repeat++) {
+        const start = performance.now();
+        await run(repeat);
+        times.push(performance.now() - start);
+    }
+    const start = performance.now();
+    const pending: Promise<unknown>[] = [];
+    for (let repeat = 0; repeat < repeats; repeat++) pending.push(run(repeat));
+    await Promise.all(pending);
+    return `${median(times).toFixed(4)} | ${((performance.now() - start) / repeats).toFixed(4)}`;
+};
+
+const markup = "<todo-toggle-all></todo-toggle-all><todo-list></todo-list><todo-summary></todo-summary><todo-filters></todo-filters>";
+
+/** The app on the page with `n` todos and their rows, and its todos in list order. */
+const appWith = async (n: number): Promise<{ readonly app: App; readonly listed: readonly Entity[] }> => {
+    document.body.innerHTML = markup;
+    const app = createApp(document.body);
+    await app.world.run(addGenerated, { count: n });
+    await app.world.run(createRows);
+    return { app, listed: [...document.querySelectorAll("todo-row")].map(entityOfElement) };
+};
+
+/** The share of a profile's samples each function took, by itself, largest first. */
+const selfTimes = (profile: { readonly nodes: readonly { readonly id: number; readonly callFrame: { readonly functionName: string; readonly url: string; readonly lineNumber: number } }[]; readonly samples?: readonly number[] }): string[] => {
+    const nodes = new Map(profile.nodes.map(node => [node.id, node]));
+    const shares = new Map<string, number>();
+    const samples = profile.samples ?? [];
+    for (const sample of samples) {
+        const frame = nodes.get(sample)?.callFrame;
+        if (frame === undefined) continue;
+        const key = `${frame.functionName === "" ? "(anonymous)" : frame.functionName} ${frame.url.split("/").pop()?.split("?")[0] ?? ""}:${frame.lineNumber + 1}`;
+        shares.set(key, (shares.get(key) ?? 0) + 1);
+    }
+    return [...shares].sort((a, b) => b[1] - a[1]).slice(0, 12).map(([key, count]) => `${(100 * count / samples.length).toFixed(1)}% ${key}`);
+};
+
+it("profiles a run's fixed cost", async () => {
+    const lines = ["| Setup | one at a time, ms | back to back, ms per run |", "|---|---:|---:|"];
+    lines.push(`| await of a resolved promise | ${await timeRuns(() => Promise.resolve(), 2001)} |`);
+    lines.push(`| a task: MessageChannel round trip | ${await timeRuns(() => new Promise(resolve => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+            channel.port1.close();
+            resolve(null);
+        };
+        channel.port2.postMessage(null);
+    }), 2001)} |`);
+    {
+        await using world = World.create({ [workers]: 0 });
+        lines.push(`| empty world, a run that changes nothing | ${await timeRuns(() => world.run(nothing), 2001)} |`);
+        for (const system of [bindRows, placeRows, filterRows, bindFilters, bindCompletion, logFailures, createRows]) {
+            world.add(system);
+            lines.push(`| + ${system.name} | ${await timeRuns(() => world.run(nothing), 2001)} |`);
+        }
+    }
+    for (const n of [1000, 10000, 100000]) {
+        const { app, listed } = await appWith(n);
+        lines.push(`| app with ${n} todos, a run that changes nothing | ${await timeRuns(() => app.world.run(nothing), 1001)} |`);
+        lines.push(`| app with ${n} todos, toggle one | ${await timeRuns(repeat => app.world.run(toggleTodo, { entity: listed[(repeat * 7) % n] ?? Entity.none }), 1001)} |`);
+        await app.dispose();
+    }
+    console.log(lines.join("\n"));
+
+    const { app, listed } = await appWith(10000);
+    const session = cdp();
+    await session.send("Profiler.enable");
+    await session.send("Profiler.setSamplingInterval", { interval: 50 });
+    await session.send("Profiler.start");
+    for (let i = 0; i < 4000; i++) await app.world.run(toggleTodo, { entity: listed[(i * 7) % listed.length] ?? Entity.none });
+    const { profile } = await session.send("Profiler.stop");
+    console.log(["Toggling one of 10K, self time by function:", ...selfTimes(profile)].join("\n"));
+    await app.dispose();
+    document.body.replaceChildren();
+});