@adobe/ecs 0.1.0 → 0.2.0

package/src/interface/trait/trait.ts

@@ -1,3 +0,0 @@
-export type Trait = never;
-
-export * as Trait from './index.js';

package/src/samples/particles/build.test.ts

@@ -1,23 +0,0 @@
-/// <reference types="node" />
-import { mkdtempSync, realpathSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { afterAll, expect, it } from "vitest";
-import { build, type Rollup } from "vite";
-
-const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
-const outDir = realpathSync(mkdtempSync(join(tmpdir(), "ecs-sample-")));
-afterAll(() => rmSync(outDir, { recursive: true, force: true }));
-
-it("the GPU sample builds as an application, with the world's worker and each kernel's create", async () => {
-    const output = await build({
-        configFile: join(packageRoot, "vite.sample.config.ts"), root: join(packageRoot, "src/samples/particles"), logLevel: "silent",
-        build: { outDir, emptyOutDir: true },
-    });
-    const items = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : []);
-    expect(items.some(item => item.fileName.includes("worker"))).toBe(true);
-    const kernels = items.filter((item): item is Rollup.OutputChunk => item.type === "chunk" && item.name.startsWith("kernel-"));
-    expect(kernels.length).toBeGreaterThan(0);
-    for (const kernel of kernels) expect(kernel.exports).toEqual(["create"]);
-}, 30000);

package/src/samples/particles/gpu/main.ts

@@ -1,96 +0,0 @@
-import { Gpu, System, World, gpuDevice } from '../../../index.js';
-import { createDraw, enabled, move, moveOnCpu, position, spawn, visible } from './particles.js';
-
-/**
- * The particles sample. `?mode=gpu` moves particles on the GPU, `cpu` on workers (uploading positions for drawing
- * each frame), and `static` only draws. `?count=` sets how many to spawn; a quarter are visible and enabled.
- */
-type Mode = "gpu" | "cpu" | "static";
-const modes: readonly Mode[] = ["gpu", "cpu", "static"];
-
-const parameters = new URLSearchParams(location.search);
-const mode = modes.find(candidate => candidate === parameters.get("mode")) ?? "gpu";
-const count = Number(parameters.get("count") ?? 1_000_000);
-
-/** Run times and frame intervals of the last frames, in milliseconds. */
-const kept = 600;
-const runs: number[] = [];
-const intervals: number[] = [];
-const percentile = (values: readonly number[], fraction: number): number => {
-    const sorted = [...values].sort((a, b) => a - b);
-    return sorted.length === 0 ? NaN : sorted[Math.min(sorted.length - 1, Math.floor(fraction * sorted.length))];
-};
-const push = (values: number[], value: number): void => {
-    values.push(value);
-    if (values.length > kept) values.shift();
-};
-
-/** For automated measurement. */
-const stats = () => ({
-    mode,
-    count,
-    frames: runs.length,
-    runMedian: percentile(runs, 0.5),
-    runP95: percentile(runs, 0.95),
-    intervalMedian: percentile(intervals, 0.5),
-});
-Reflect.set(globalThis, "sampleStats", stats);
-
-const overlay = (text: string): void => {
-    const element = document.querySelector("#stats");
-    if (element !== null) element.textContent = text;
-};
-
-const start = async (): Promise<void> => {
-    const adapter = await navigator.gpu?.requestAdapter();
-    if (adapter === null || adapter === undefined) return overlay("This browser has no WebGPU.");
-    const device = await adapter.requestDevice();
-    const canvas = document.querySelector("canvas");
-    if (canvas === null) return;
-    canvas.width = Math.floor(canvas.clientWidth * devicePixelRatio);
-    canvas.height = Math.floor(canvas.clientHeight * devicePixelRatio);
-    const context = canvas.getContext("webgpu");
-    if (context === null) return overlay("No WebGPU canvas context.");
-    const format = navigator.gpu.getPreferredCanvasFormat();
-    context.configure({ device, format, alphaMode: "opaque" });
-
-    const moving = mode === "gpu" ? [move] : mode === "cpu" ? [moveOnCpu] : [];
-    const world = World.create({ [gpuDevice]: device });
-    const { draw, ready } = createDraw(device, Gpu.layout(device), context, format);
-    await ready;
-    const frame = System.create({ name: "gpuParticles/frame", systems: [...moving, draw] });
-    await world.run(spawn, { count, width: canvas.width, height: canvas.height });
-    /** For automated checks: a few drawn particles' positions, which an observer system reads back from the GPU. */
-    const probed: (readonly number[])[] = [];
-    const probe = System.create({ name: "gpuParticles/probe", observer: true, components: { read: [position], has: [visible, enabled] } }, row => {
-        if (probed.length < 3) probed.push(row[position]);
-    });
-    Reflect.set(globalThis, "sampleProbe", async () => {
-        probed.length = 0;
-        await world.run(probe);
-        return [...probed];
-    });
-
-    // At most two frames of GPU work in flight, so the CPU can't run ahead of the GPU.
-    const inFlight: Promise<undefined>[] = [];
-    let last = performance.now();
-    let shown = 0;
-    const tick = async (now: number): Promise<void> => {
-        push(intervals, now - last);
-        last = now;
-        if (inFlight.length >= 2) await inFlight.shift();
-        const begin = performance.now();
-        await world.run(frame);
-        push(runs, performance.now() - begin);
-        inFlight.push(device.queue.onSubmittedWorkDone());
-        if (now - shown > 500) {
-            shown = now;
-            const { runMedian, runP95, intervalMedian } = stats();
-            overlay(`${mode}: ${(count / 4).toLocaleString()} of ${count.toLocaleString()} particles drawn · run ${runMedian.toFixed(3)} ms (p95 ${runP95.toFixed(3)}) · ${(1000 / intervalMedian).toFixed(0)} fps`);
-        }
-        requestAnimationFrame(tick);
-    };
-    requestAnimationFrame(tick);
-};
-
-void start();

package/src/samples/particles/gpu/particles.ts

@@ -1,138 +0,0 @@
-import { Archetype, Component, Gpu, System, Vec3 } from '../../../index.js';
-
-// The perf particles (src/perftest/particles.ts) on screen: 1M particles over four archetypes by visible and
-// enabled, with screen-space positions and velocities in pixels per frame. `move` is the perf move kernel, on the GPU.
-
-export const position = Symbol("gpuParticles/position");
-export const velocity = Symbol("gpuParticles/velocity");
-export const color = Symbol("gpuParticles/color");
-export const mass = Symbol("gpuParticles/mass");
-export const visible = Symbol("gpuParticles/visible");
-export const enabled = Symbol("gpuParticles/enabled");
-
-declare module '@adobe/ecs' {
-    interface Components {
-        [position]: { type: Vec3 };
-        [velocity]: { type: Vec3 };
-        [color]: { type: number };
-        [mass]: { type: number };
-        [visible]: { type: true };
-        [enabled]: { type: true };
-    }
-}
-
-Component.register(position, { type: Vec3.schema });
-Component.register(velocity, { type: Vec3.schema });
-Component.register(color, { type: { type: "integer", minimum: 0, maximum: 0xFFFFFFFF } });
-Component.register(mass, { type: { type: "number", precision: 1 } });
-Component.register(visible, { type: { const: true } });
-Component.register(enabled, { type: { const: true } });
-
-/** Entity i goes to archetype i % 4. */
-const archetypes = [
-    Archetype.create([color, mass, position, velocity, visible, enabled]),
-    Archetype.create([color, mass, position, velocity, visible]),
-    Archetype.create([color, mass, position, velocity, enabled]),
-    Archetype.create([color, mass, position, velocity]),
-] as const;
-
-/** A deterministic sequence in [0, 1), so every mode starts from the same particles. */
-const random = (seed: number): (() => number) => {
-    let state = seed >>> 0;
-    return () => {
-        state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
-        return state / 2 ** 32;
-    };
-};
-
-/** The particle count, and the field's width and height in pixels. Entity i goes to archetype i % 4. */
-export const spawn = System.create({
-    name: "gpuParticles/spawn",
-    input: { type: "object", properties: { count: { type: "integer" }, width: { type: "number" }, height: { type: "number" } } },
-}, ({ input: { count, width, height }, commands }) => {
-    const next = random(7);
-    for (let i = 0; i < count; i++) {
-        const p = [next() * width, next() * height, 0] as const;
-        const angle = next() * Math.PI * 2;
-        const speed = 0.25 + next() * 1.75;
-        const v = [Math.cos(angle) * speed, Math.sin(angle) * speed, 0] as const;
-        // Opaque, in the colors' upper half so they show on black: RGBA bytes, red lowest.
-        const rgb = 0x808080 | Math.floor(next() * 0x1000000);
-        commands.spawn(archetypes[i % 4])({ [color]: (0xff000000 | rgb) >>> 0, [mass]: 1, [position]: p, [velocity]: v });
-    }
-});
-
-export const move = System.create({
-    name: "gpuParticles/move",
-    kernel: "gpu",
-    components: { read: [velocity], write: [position], has: [visible, enabled] },
-}, row => {
-    row[position] = Vec3.add(row[position], row[velocity]);
-});
-
-/** The same move on the CPU, for comparison. */
-export const moveOnCpu = System.create({
-    name: "gpuParticles/moveOnCpu",
-    kernel: "cpu",
-    components: { read: [velocity], write: [position], has: [visible, enabled] },
-}, row => {
-    row[position] = Vec3.add(row[position], row[velocity]);
-});
-
-/** The vertex and fragment stages, after the world's declarations: each particle is a point, wrapped into the field. */
-const shader = `
-struct View { size: vec2f }
-@group(1) @binding(0) var<uniform> view: View;
-
-struct Point { @builtin(position) position: vec4f, @location(0) color: vec4f }
-
-@vertex fn vertexMain(@builtin(vertex_index) row: u32) -> Point {
-    let p = particlePosition(row).xy;
-    let wrapped = p - floor(p / view.size) * view.size;
-    let clip = wrapped / view.size * 2.0 - 1.0;
-    return Point(vec4f(clip.x, -clip.y, 0.0, 1.0), unpack4x8unorm(particleColor(row)));
-}
-
-@fragment fn fragmentMain(point: Point) -> @location(0) vec4f { return point.color; }
-`;
-
-const declaration = {
-    name: "gpuParticles/draw",
-    components: { has: [visible, enabled] },
-    shader: { group: 0, accessors: { particlePosition: position, particleColor: color } },
-    after: [move, moveOnCpu],
-} as const;
-
-/**
- * The render system for a canvas: it draws the visible and enabled particles as points, wrapping positions so
- * particles leaving one side of the field come back on the other. `layout` is the world's GPU layout.
- */
-export const createDraw = (device: GPUDevice, layout: GPUBindGroupLayout, context: GPUCanvasContext, format: GPUTextureFormat) => {
-    const viewLayout = device.createBindGroupLayout({ entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } }] });
-    const viewBuffer = device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-    const viewGroup = device.createBindGroup({ layout: viewLayout, entries: [{ binding: 0, resource: { buffer: viewBuffer } }] });
-    let pipeline: GPURenderPipeline | null = null;
-    const draw = System.render(declaration, ({ encoder, tables }) => {
-        if (pipeline === null) return;
-        const texture = context.getCurrentTexture();
-        device.queue.writeBuffer(viewBuffer, 0, new Float32Array([texture.width, texture.height]));
-        const pass = encoder.beginRenderPass({ colorAttachments: [{ view: texture.createView(), loadOp: "clear", storeOp: "store", clearValue: { r: 0, g: 0, b: 0, a: 1 } }] });
-        pass.setPipeline(pipeline);
-        pass.setBindGroup(1, viewGroup);
-        for (const table of tables) {
-            table.bind(pass);
-            pass.draw(table.count);
-        }
-        pass.end();
-    });
-    const module = device.createShaderModule({ code: `${Gpu.wgsl(draw)}${shader}` });
-    const ready = (async () => {
-        pipeline = await device.createRenderPipelineAsync({
-            layout: device.createPipelineLayout({ bindGroupLayouts: [layout, viewLayout] }),
-            vertex: { module, entryPoint: "vertexMain" },
-            fragment: { module, entryPoint: "fragmentMain", targets: [{ format }] },
-            primitive: { topology: "point-list" },
-        });
-    })();
-    return { draw, ready };
-};

package/src/samples/particles/index.html

@@ -1,22 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>GPU Particles</title>
-    <style>
-        html, body { margin: 0; height: 100%; background: #000; color: #ddd; font: 13px/1.4 system-ui, sans-serif; }
-        canvas { display: block; width: 100%; height: 100%; }
-        #panel { position: fixed; top: 8px; left: 8px; padding: 6px 10px; background: rgb(0 0 0 / 0.7); border-radius: 6px; }
-        #panel a { color: #8cf; margin-right: 8px; }
-    </style>
-</head>
-<body>
-    <canvas></canvas>
-    <div id="panel">
-        <div id="stats">Starting…</div>
-        <div><a href="?mode=gpu">GPU move</a><a href="?mode=cpu">CPU move</a><a href="?mode=static">draw only</a></div>
-    </div>
-    <script type="module" src="./gpu/main.ts"></script>
-</body>
-</html>

package/src/samples/particles/particles.test.ts

@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { System, World, workers } from "../../index.js";
-import { count, frame } from "./particles.js";
-
-/** The same simulation in plain f64 JS. */
-const reference = (frames: readonly number[]): number[][] => {
-    const particles = Array.from({ length: 100 }, (_, i) => ({ position: [0, 0, 0], velocity: [1, i, 0] }));
-    for (const seconds of frames.slice(1)) {
-        for (const particle of particles) {
-            particle.velocity[1] -= 9.8 * seconds;
-            particle.position = particle.position.map((value, axis) => value + particle.velocity[axis] * seconds);
-        }
-    }
-    return particles.map(particle => particle.position);
-};
-
-describe("particles", () => {
-    it("matches a plain JS simulation within storage precision", async () => {
-        // Kernels run here: under Vitest's module runner, node workers can't load the sources.
-        await using world = World.create({ [workers]: 0 });
-        const frames = [0.5, 0.25, 1 / 60, 1 / 60];
-        let positions: readonly (readonly number[])[] = [];
-        for (const seconds of frames) positions = await frame(world, seconds);
-        let spawned = 0;
-        await world.run(System.create({ observer: true, resources: { read: [count] } }, ({ resources }) => { spawned = resources[count]; }));
-        expect(spawned).toBe(100);
-        const expected = reference(frames);
-        expect(positions).toHaveLength(expected.length);
-        positions.forEach((position, i) => position.forEach((value, axis) => expect(value).toBeCloseTo(expected[i][axis], 3)));
-    });
-});

package/src/samples/particles/particles.ts

@@ -1,85 +0,0 @@
-import { Component, Resource, System, Vec3, type World } from '../../index.js';
-
-export const position = Symbol("particles/position");
-export const velocity = Symbol("particles/velocity");
-export const delta = Symbol("particles/delta");
-export const count = Symbol("particles/count");
-
-declare module '@adobe/ecs' {
-    interface Components {
-        [position]: { type: Vec3 };
-        [velocity]: { type: Vec3 };
-    }
-    interface Resources {
-        [delta]: { type: number };
-        [count]: { type: number };
-    }
-}
-
-Component.register(position, { type: Vec3.schema });
-Component.register(velocity, { type: Vec3.schema });
-Resource.register(delta, { type: { type: "number", precision: 1, default: 0 } });
-Resource.register(count, { type: { type: "integer", minimum: 0, default: 100 } });
-
-// Main thread: resource-only, runs when `count` changes, including the first run.
-export const spawn = System.create({
-    name: "particles/spawn",
-    resources: { read: [count], changed: [count] },
-}, ({ resources, commands }) => {
-    for (let i = 0; i < resources[count]; i++) {
-        commands.spawn([position, velocity])({ [position]: [0, 0, 0], [velocity]: [1, i, 0] });
-    }
-});
-
-// Kernels: linear components and read-only resources, so they can run in chunks across workers.
-export const gravity = System.create({
-    name: "particles/gravity",
-    kernel: "cpu",
-    components: { write: [velocity] },
-    resources: { read: [delta] },
-}, (row, { resources }) => {
-    const [x, y, z] = row[velocity];
-    row[velocity] = [x, y - 9.8 * resources[delta], z];
-});
-
-export const integrate = System.create({
-    name: "particles/integrate",
-    kernel: "cpu",
-    components: { read: [velocity], write: [position] },
-    resources: { read: [delta] },
-    after: [gravity],
-}, (row, { resources }) => {
-    const [px, py, pz] = row[position];
-    const [vx, vy, vz] = row[velocity];
-    const t = resources[delta];
-    row[position] = [px + vx * t, py + vy * t, pz + vz * t];
-});
-
-// Transaction carrying frame time into the ECS.
-export const setDelta = System.create({
-    name: "particles/setDelta",
-    input: { type: "object", properties: { seconds: { type: "number" } } },
-    resources: { write: [delta] },
-}, ({ resources, input }) => {
-    resources[delta] = input.seconds;
-});
-
-export const main = System.create({ name: "particles/main", systems: [spawn, gravity, integrate] });
-
-// Reads every position the frame left, in spawn order.
-const positions: Vec3[] = [];
-const read = System.create({
-    name: "particles/read",
-    observer: true,
-    components: { read: [position] },
-}, row => {
-    positions.push(row[position]);
-});
-
-export const frame = async (world: World, seconds: number): Promise<readonly Vec3[]> => {
-    await world.run(setDelta, { seconds });
-    await world.run(main);
-    positions.length = 0;
-    await world.run(read);
-    return [...positions];
-};

package/src/samples/particles/particles.type-test.ts

@@ -1,7 +0,0 @@
-import { Resource } from '../../index.js';
-import { count } from './particles.js';
-
-// @ts-expect-error a resource schema requires a default
-Resource.register(count, { type: { type: "integer" } });
-// @ts-expect-error the default must match the resource type
-Resource.register(count, { type: { type: "integer", default: "none" } });

package/src/samples/todo/README.md

@@ -1,174 +0,0 @@
-# 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.