@adobe/ecs 0.0.0-stage → 0.1.0

package/src/samples/todo/features/todos/elements/todo-row.ts

@@ -0,0 +1,138 @@
+/**
+ * `<todo-row>`: one todo. Properties `label` and `done` drive it, and `done` is reflected as an attribute for styling;
+ * `hidden` hides it, as it does any element. It dispatches `todo-toggle`, `todo-delete` and `todo-edit`, and never
+ * changes its properties itself: whoever owns the todo writes them back. Editing is its own state, as focus is.
+ */
+
+const template = document.createElement("template");
+template.innerHTML = `
+<style>
+    :host { display: flex; align-items: center; gap: 12px; box-sizing: border-box; min-height: 44px; padding: 0 12px;
+        border-bottom: 1px solid var(--todo-line, #e5e7eb); background: var(--todo-surface, #fff); }
+    /* The display above would otherwise show a hidden row. */
+    /* Rows out of view skip their rendering: at 10K, laying them out takes a third of the time, and filtering a quarter. */
+    :host { content-visibility: auto; contain-intrinsic-size: auto 44px; }
+    :host([hidden]) { display: none; }
+    :host(:hover) { background: var(--todo-hover, #f9fafb); }
+    :host([done]) .label { text-decoration: line-through; color: var(--todo-muted, #9ca3af); }
+    .toggle { flex-shrink: 0; width: 18px; height: 18px; margin: 0; accent-color: var(--todo-accent, #2563eb); }
+    .label { flex: 1; padding: 10px 0; word-break: break-word; cursor: grab; }
+    .edit { flex: 1; font: inherit; padding: 6px 8px; border: 1px solid var(--todo-accent, #2563eb); border-radius: 4px; }
+    .delete { flex-shrink: 0; border: 0; background: none; font-size: 18px; line-height: 1; color: var(--todo-muted, #9ca3af);
+        cursor: pointer; opacity: 0; }
+    :host(:hover) .delete, .delete:focus-visible { opacity: 1; }
+    .delete:hover { color: var(--todo-danger, #dc2626); }
+    [hidden] { display: none; }
+</style>
+<input class="toggle" type="checkbox" aria-label="Toggle complete">
+<span class="label"></span>
+<input class="edit" aria-label="Edit todo" hidden>
+<button class="delete" aria-label="Delete todo">×</button>`;
+
+export type TodoRowEvents = {
+    readonly "todo-toggle": CustomEvent<null>;
+    readonly "todo-delete": CustomEvent<null>;
+    readonly "todo-edit": CustomEvent<{ readonly label: string }>;
+};
+
+const dispatch = <K extends keyof TodoRowEvents>(target: HTMLElement, type: K, detail: TodoRowEvents[K]["detail"]): void => {
+    target.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+};
+
+/** The row's parts, found once in its shadow root. */
+type Parts = { readonly toggle: HTMLInputElement; readonly label: HTMLElement; readonly edit: HTMLInputElement; readonly delete: HTMLButtonElement };
+
+const partsOf = (root: ShadowRoot): Parts => {
+    const toggle = root.querySelector(".toggle");
+    const label = root.querySelector(".label");
+    const edit = root.querySelector(".edit");
+    const remove = root.querySelector(".delete");
+    const found = toggle instanceof HTMLInputElement && label instanceof HTMLElement && edit instanceof HTMLInputElement && remove instanceof HTMLButtonElement;
+    if (!found) {
+        throw new Error("todo-row's template is missing a part.");
+    }
+    return { toggle, label, edit, delete: remove };
+};
+
+/** Starts editing. The row isn't draggable meanwhile, so the text being edited can be selected. */
+const startEditing = (host: HTMLElement, parts: Parts): void => {
+    parts.edit.value = parts.label.textContent ?? "";
+    parts.label.hidden = true;
+    parts.edit.hidden = false;
+    host.draggable = false;
+    parts.edit.focus();
+};
+
+/** Leaves editing, dispatching the new label when `commit` is set. */
+const stopEditing = (host: HTMLElement, parts: Parts, commit: boolean): void => {
+    if (parts.edit.hidden) return;
+    parts.edit.hidden = true;
+    parts.label.hidden = false;
+    host.draggable = true;
+    if (commit) dispatch(host, "todo-edit", { label: parts.edit.value });
+};
+
+const listen = (host: HTMLElement, parts: Parts, done: () => boolean): void => {
+    parts.toggle.addEventListener("change", () => {
+        // The owner writes `done` back; until then the checkbox shows the value it was given.
+        parts.toggle.checked = done();
+        dispatch(host, "todo-toggle", null);
+    });
+    parts.delete.addEventListener("click", () => dispatch(host, "todo-delete", null));
+    parts.label.addEventListener("dblclick", () => startEditing(host, parts));
+    parts.edit.addEventListener("keydown", event => {
+        // Enter while composing text picks the composition.
+        if (event.key === "Enter" && !event.isComposing) stopEditing(host, parts, true);
+        else if (event.key === "Escape") stopEditing(host, parts, false);
+    });
+    parts.edit.addEventListener("blur", () => stopEditing(host, parts, true));
+};
+
+export class TodoRow extends HTMLElement {
+    readonly #parts: Parts;
+    #label = "";
+    #done = false;
+
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: "open" });
+        root.append(template.content.cloneNode(true));
+        this.#parts = partsOf(root);
+        listen(this, this.#parts, () => this.#done);
+    }
+
+    /** Placing a row connects it again, so attributes are set only once. */
+    connectedCallback(): void {
+        if (this.hasAttribute("tabindex")) return;
+        this.tabIndex = 0;
+        this.draggable = true;
+    }
+
+    get label(): string {
+        return this.#label;
+    }
+
+    set label(value: string) {
+        if (value === this.#label) return;
+        this.#label = value;
+        this.#parts.label.textContent = value;
+    }
+
+    get done(): boolean {
+        return this.#done;
+    }
+
+    set done(value: boolean) {
+        if (value === this.#done) return;
+        this.#done = value;
+        this.#parts.toggle.checked = value;
+        this.toggleAttribute("done", value);
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "todo-row": TodoRow;
+    }
+    interface HTMLElementEventMap extends TodoRowEvents {}
+}

package/src/samples/todo/features/todos/events.ts

@@ -0,0 +1,11 @@
+import { entityOf, entityOfElement } from "../../shared/attach.js";
+import { all, on, type Connect } from "../../shared/connect.js";
+import { addTodo, deleteTodo, editTodo, moveTodo, toggleTodo } from "./model.js";
+
+export const connect: Connect = (world, root) => all(
+    on(root, "todo-add", event => void world.run(addTodo, { label: event.detail.label })),
+    on(root, "todo-toggle", event => void world.run(toggleTodo, { entity: entityOf(event) })),
+    on(root, "todo-edit", event => void world.run(editTodo, { entity: entityOf(event), label: event.detail.label })),
+    on(root, "todo-delete", event => void world.run(deleteTodo, { entity: entityOf(event) })),
+    on(root, "todo-move", event => void world.run(moveTodo, { entity: entityOfElement(event.detail.item), before: entityOfElement(event.detail.before) })),
+);

package/src/samples/todo/features/todos/feature.ts

@@ -0,0 +1,14 @@
+import type { Feature } from "../../shared/feature.js";
+import { dom, list } from "./dom.js";
+import { TodoEntry } from "./elements/todo-entry.js";
+import { TodoList } from "./elements/todo-list.js";
+import { TodoRow } from "./elements/todo-row.js";
+import { connect } from "./events.js";
+
+/** Todos: adding, toggling, editing, deleting and moving them, in the page's list. */
+export const todos: Feature = {
+    elements: { "todo-entry": TodoEntry, "todo-list": TodoList, "todo-row": TodoRow },
+    resources: root => ({ [list]: root.querySelector("todo-list") }),
+    system: dom,
+    connect,
+};

package/src/samples/todo/features/todos/model.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../../../index.js";
+import { addTodo, deleteTodo, editTodo, moveTodo, toggleTodo } from "./model.js";
+import { entityOf, labelsOf, todosOf, withTodos } from "./todos.test-helper.js";
+import { runReported } from "../../../../implementation/world/reports.test-helper.js";
+
+describe("todos", () => {
+    it("adds todos at the end, trimmed, and ignores blank labels", async () => {
+        await using world = await withTodos(" milk ", "eggs", "   ", "");
+        expect(await todosOf(world)).toEqual([
+            expect.objectContaining({ label: "milk", done: false }),
+            expect.objectContaining({ label: "eggs", done: false }),
+        ]);
+    });
+
+    it("toggles a todo", async () => {
+        await using world = await withTodos("milk", "eggs");
+        const milk = await entityOf(world, "milk");
+        await world.run(toggleTodo, { entity: milk });
+        expect((await todosOf(world)).map(item => item.done)).toEqual([true, false]);
+        await world.run(toggleTodo, { entity: milk });
+        expect((await todosOf(world)).map(item => item.done)).toEqual([false, false]);
+    });
+
+    it("edits a label, trimmed, and deletes a todo edited to blank", async () => {
+        await using world = await withTodos("milk", "eggs");
+        await world.run(editTodo, { entity: await entityOf(world, "milk"), label: " oat milk " });
+        expect(await labelsOf(world)).toEqual(["oat milk", "eggs"]);
+        await world.run(editTodo, { entity: await entityOf(world, "eggs"), label: "  " });
+        expect(await labelsOf(world)).toEqual(["oat milk"]);
+    });
+
+    it("deletes a todo, and ignores entities that aren't todos", async () => {
+        await using world = await withTodos("milk", "eggs");
+        const milk = await entityOf(world, "milk");
+        await world.run(deleteTodo, { entity: milk });
+        expect(await labelsOf(world)).toEqual(["eggs"]);
+        const report = await runReported(world, deleteTodo, { entity: milk });
+        expect(report.failures).toEqual([]);
+        await world.run(toggleTodo, { entity: milk });
+        expect(await labelsOf(world)).toEqual(["eggs"]);
+    });
+
+    it("moves a todo before another, or to the end", async () => {
+        await using world = await withTodos("a", "b", "c", "d");
+        await world.run(moveTodo, { entity: await entityOf(world, "d"), before: await entityOf(world, "b") });
+        expect(await labelsOf(world)).toEqual(["a", "d", "b", "c"]);
+        await world.run(moveTodo, { entity: await entityOf(world, "a"), before: Entity.none });
+        expect(await labelsOf(world)).toEqual(["d", "b", "c", "a"]);
+        await world.run(moveTodo, { entity: await entityOf(world, "c"), before: await entityOf(world, "d") });
+        expect(await labelsOf(world)).toEqual(["c", "d", "b", "a"]);
+        // Moving before itself, or to where it already is, changes nothing.
+        await world.run(moveTodo, { entity: await entityOf(world, "d"), before: await entityOf(world, "d") });
+        await world.run(moveTodo, { entity: await entityOf(world, "d"), before: await entityOf(world, "b") });
+        await world.run(moveTodo, { entity: await entityOf(world, "a"), before: Entity.none });
+        expect(await labelsOf(world)).toEqual(["c", "d", "b", "a"]);
+    });
+
+    it("numbers todos again when no order lies between two neighbours", async () => {
+        await using world = await withTodos("a", "b", "c");
+        // Each move halves the gap before b, until no number is left in it.
+        for (let i = 0; i < 60; i++) {
+            const moving = i % 2 === 0 ? "c" : "a";
+            await world.run(moveTodo, { entity: await entityOf(world, moving), before: await entityOf(world, "b") });
+        }
+        const todos = await todosOf(world);
+        expect(todos.map(item => item.label)).toEqual(["c", "a", "b"]);
+        expect(new Set(todos.map(item => item.order)).size).toBe(3);
+    });
+
+    it("adds after the last todo, wherever moves left it", async () => {
+        await using world = await withTodos("a", "b");
+        await world.run(moveTodo, { entity: await entityOf(world, "b"), before: await entityOf(world, "a") });
+        await world.run(addTodo, { label: "c" });
+        expect(await labelsOf(world)).toEqual(["b", "a", "c"]);
+    });
+});

package/src/samples/todo/features/todos/model.ts

@@ -0,0 +1,80 @@
+import { Entity, System } from "../../../../index.js";
+import { Todo, done, label, order, orderAfter, ordered, todo } from "./data.js";
+
+const text = { type: "string" } as const;
+
+/** Adds a todo at the end of the list, with its label trimmed; a blank label adds nothing. */
+export const addTodo = System.create({
+    name: "todos/add",
+    input: { type: "object", properties: { label: text } },
+    lookup: { ordered: { index: ordered, read: [order] } },
+}, ({ input, lookup, commands }) => {
+    const trimmed = input.label.trim();
+    if (trimmed === "") return;
+    commands.spawn(Todo)({ [label]: trimmed, [done]: false, [order]: orderAfter(lookup.ordered()) });
+});
+
+const one = { entity: Entity.schema } as const;
+
+export const toggleTodo = System.create({
+    name: "todos/toggle",
+    input: { type: "object", properties: one },
+    target: "entity",
+    components: { write: [done], has: [todo] },
+}, row => {
+    row[done] = !row[done];
+});
+
+/** Gives a todo a new label, trimmed; a blank one deletes it. */
+export const editTodo = System.create({
+    name: "todos/edit",
+    input: { type: "object", properties: { ...one, label: text } },
+    target: "entity",
+    components: { write: [label], has: [todo] },
+}, (row, { input, commands }) => {
+    const trimmed = input.label.trim();
+    if (trimmed === "") commands.despawn(row.entity);
+    else row[label] = trimmed;
+});
+
+export const deleteTodo = System.create({
+    name: "todos/delete",
+    input: { type: "object", properties: one },
+    target: "entity",
+    components: { has: [todo] },
+}, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+
+/**
+ * Moves a todo to just before `before`, or to the end for `Entity.none`, by giving it an order between its new
+ * neighbours'. When no number lies between them, every todo is numbered again.
+ */
+export const moveTodo = System.create({
+    name: "todos/move",
+    input: { type: "object", properties: { entity: Entity.schema, before: Entity.schema } },
+    lookup: { todos: { read: [order], has: [todo] }, ordered: { index: ordered, read: [order] } },
+}, ({ input, lookup, commands }) => {
+    const { entity, before } = input;
+    if (entity === before || lookup.todos(entity) === null) return;
+    const next = before === Entity.none ? null : lookup.todos(before);
+    if (before !== Entity.none && next === null) return;
+    const earlier = next === null ? lookup.ordered() : lookup.ordered({ "<": next[order] });
+    if (earlier.length > 0 && earlier.at(earlier.length - 1).entity === entity) return;
+    const low = earlier.length === 0 ? (next === null ? 0 : next[order] - 1) : earlier.at(earlier.length - 1)[order];
+    const high = next === null ? low + 2 : next[order];
+    const middle = (low + high) / 2;
+    if (middle > low && middle < high) {
+        commands.add(entity, order, middle);
+        return;
+    }
+    const all = lookup.ordered();
+    let position = 0;
+    for (let i = 0; i < all.length; i++) {
+        const row = all.at(i);
+        if (row.entity === entity) continue;
+        if (row.entity === before) commands.add(entity, order, position++);
+        commands.add(row.entity, order, position++);
+    }
+    if (next === null) commands.add(entity, order, position);
+});

package/src/samples/todo/features/todos/todos.test-helper.ts

@@ -0,0 +1,34 @@
+import { Entity, System, workers, World } from "../../../../index.js";
+import { done, label, order, ordered } from "./data.js";
+import { addTodo } from "./model.js";
+
+/** A todo as tests read it. */
+export type Listed = { readonly entity: Entity; readonly label: string; readonly done: boolean; readonly order: number };
+
+const listed: Listed[] = [];
+const readTodos = System.create({ name: "test/readTodos", observer: true, components: { read: [label, done, order] }, order: ordered }, row => {
+    listed.push({ entity: row.entity, label: row[label], done: row[done], order: row[order] });
+});
+
+/** The todos, in list order. */
+export const todosOf = async (world: World): Promise<Listed[]> => {
+    listed.length = 0;
+    await world.run(readTodos);
+    return [...listed];
+};
+
+export const labelsOf = async (world: World): Promise<string[]> => (await todosOf(world)).map(item => item.label);
+
+/** A world without a kernel pool, holding todos with these labels, in this order. */
+export const withTodos = async (...labels: string[]): Promise<World> => {
+    const world = World.create({ [workers]: 0 });
+    for (const text of labels) await world.run(addTodo, { label: text });
+    return world;
+};
+
+/** The entity of the todo with this label. */
+export const entityOf = async (world: World, text: string): Promise<Entity> => {
+    const found = (await todosOf(world)).find(item => item.label === text);
+    if (found === undefined) throw new Error(`No todo "${text}".`);
+    return found.entity;
+};

package/src/samples/todo/imports.test.ts

@@ -0,0 +1,113 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/** The sample's folder, the package root it imports the ECS from, and the implementation's index, which it never does. */
+const sample = dirname(fileURLToPath(import.meta.url));
+const packageIndex = resolve(sample, "../../index.js");
+const implementationIndex = resolve(sample, "../../implementation/index.js");
+
+/** The features each feature builds on. */
+const builtOn: { readonly [feature: string]: readonly string[] } = { todos: [], filter: ["todos"], completion: ["todos"], generate: ["todos"] };
+
+/** Every TypeScript file under a directory. */
+const filesOf = (directory: string): string[] => readdirSync(directory, { withFileTypes: true }).flatMap(entry =>
+    entry.isDirectory() ? filesOf(join(directory, entry.name)) : entry.name.endsWith(".ts") ? [join(directory, entry.name)] : []);
+
+/** A path's segments within the sample, or null for one outside it. */
+const segmentsOf = (path: string): readonly string[] | null => {
+    const inside = relative(sample, path);
+    return inside.startsWith("..") || inside === "" ? null : inside.split(sep);
+};
+
+/** Whether a path is inside one of the sample's `elements` folders. */
+const inElements = (path: string): boolean => segmentsOf(path)?.slice(0, -1).includes("elements") ?? false;
+
+/** The feature a path is in, or null, as for `features/index.ts`, which exports them all. */
+const featureOf = (path: string): string | null => {
+    const segments = segmentsOf(path);
+    return segments !== null && segments[0] === "features" && segments.length > 2 ? segments[1] : null;
+};
+
+/** The specifiers a file imports or re-exports, statically or dynamically, and the modules its declarations augment. */
+const specifiersOf = (code: string): string[] => [
+    ...code.matchAll(/(?:^|[\s;])(?:import|export)\s[^'"]*?\sfrom\s*["']([^"']+)["']/g),
+    ...code.matchAll(/(?:^|[\s;])import\s*["']([^"']+)["']/g),
+    ...code.matchAll(/import\s*\(\s*["']([^"']+)["']\s*\)/g),
+    ...code.matchAll(/declare\s+module\s+["']([^"']+)["']/g),
+].map(match => match[1] ?? "");
+
+/** Why `file` may not import `specifier`, or null when it may. */
+const broken = (file: string, specifier: string): string | null => {
+    const test = /\.test(-helper)?\.ts$|\.perf-browser-test\.ts$/.test(file);
+    if (!specifier.startsWith(".")) {
+        if (inElements(file)) return specifier === "vitest" && test ? null : "an element imports a package";
+        return null;
+    }
+    const target = resolve(dirname(file), specifier);
+    if (inElements(file)) return inElements(target) ? null : "an element imports what isn't an element";
+    const from = segmentsOf(file);
+    const to = segmentsOf(target);
+    if (to === null) return target === packageIndex || (test && target !== implementationIndex) ? null : "imports the package other than by its root";
+    if (to[0] === "app" && from?.[0] !== "app") return "imports the app";
+    if (from?.[0] === "shared" && to[0] === "features") return "shared code imports a feature";
+    const feature = featureOf(file);
+    const imported = featureOf(target);
+    if (feature !== null && imported !== null && imported !== feature && !(builtOn[feature] ?? []).includes(imported)) {
+        return `${feature} imports ${imported}, which it doesn't build on`;
+    }
+    if (feature !== null && from?.[from.length - 1] === "model.ts" && to[to.length - 1] !== "data.js") return "a model imports what isn't data";
+    return null;
+};
+
+/** Every import in the sample that breaks a rule, with the rule. */
+const violations = (files: readonly string[], codeOf: (file: string) => string): string[] => files.flatMap(file =>
+    specifiersOf(codeOf(file)).flatMap(specifier => {
+        const reason = broken(file, specifier);
+        return reason === null ? [] : [`${relative(sample, file)}: ${specifier}: ${reason}`];
+    }));
+
+describe("the todo sample's imports", () => {
+    it("keep to its layers: elements import nothing but each other, models only data, and no feature imports one built on it or the app", () => {
+        const files = filesOf(sample);
+        expect(files.filter(inElements).length).toBeGreaterThan(5);
+        expect(violations(files, file => readFileSync(file, "utf8"))).toEqual([]);
+    });
+
+    it("create worlds through World.create from the package root, never through the implementation", () => {
+        const at = (...path: string[]): string => join(sample, ...path);
+        expect(violations([at("app", "app.ts"), at("app", "app.test.ts")], () => `import { create } from "../../../implementation/index.js";`)).toEqual([
+            `app/app.ts: ../../../implementation/index.js: imports the package other than by its root`,
+            `app/app.test.ts: ../../../implementation/index.js: imports the package other than by its root`,
+        ]);
+    });
+
+    it("find each kind of import that breaks a rule", () => {
+        const at = (...path: string[]): string => join(sample, ...path);
+        const imports = new Map<string, string>([
+            [at("features", "todos", "elements", "todo-row.ts"), `
+                import { System } from "../../../../../index.js";
+                import "@adobe/ecs";
+                const later = import("../dom.js");
+                import { on } from "../../../../other/elements/thing.js";`],
+            [at("features", "todos", "elements", "elements.browser.test.ts"), `import { it } from "vitest"; import { part } from "../../../shared/elements/elements.test-helper.js";`],
+            [at("features", "todos", "model.ts"), `import { filter } from "../filter/data.js"; import { list } from "./dom.js"; import { done } from "./data.js";`],
+            [at("features", "filter", "dom.ts"), `import { row } from "../todos/dom.js"; import { summary } from "../completion/dom.js";`],
+            [at("shared", "connect.ts"), `import { todos } from "../features/todos/feature.js";`],
+            [at("features", "generate", "events.ts"), `import { createApp } from "../../app/app.js"; import { thing } from "../../../implementation/world/create.js";`],
+        ]);
+        expect(violations([...imports.keys()], file => imports.get(file) ?? "")).toEqual([
+            "features/todos/elements/todo-row.ts: ../../../../../index.js: an element imports what isn't an element",
+            "features/todos/elements/todo-row.ts: ../../../../other/elements/thing.js: an element imports what isn't an element",
+            "features/todos/elements/todo-row.ts: @adobe/ecs: an element imports a package",
+            "features/todos/elements/todo-row.ts: ../dom.js: an element imports what isn't an element",
+            "features/todos/model.ts: ../filter/data.js: todos imports filter, which it doesn't build on",
+            "features/todos/model.ts: ./dom.js: a model imports what isn't data",
+            "features/filter/dom.ts: ../completion/dom.js: filter imports completion, which it doesn't build on",
+            "shared/connect.ts: ../features/todos/feature.js: shared code imports a feature",
+            "features/generate/events.ts: ../../app/app.js: imports the app",
+            "features/generate/events.ts: ../../../implementation/world/create.js: imports the package other than by its root",
+        ]);
+    });
+});

package/src/samples/todo/index.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Todos</title>
+    <link rel="icon" href="data:,">
+    <style>
+        :root {
+            --todo-accent: #2563eb; --todo-danger: #dc2626; --todo-line: #e5e7eb; --todo-muted: #9ca3af;
+            --todo-surface: #fff; --todo-hover: #f9fafb; --todo-page: #f3f4f6; --todo-text: #111827;
+        }
+        @media (prefers-color-scheme: dark) {
+            :root {
+                --todo-accent: #60a5fa; --todo-danger: #f87171; --todo-line: #374151; --todo-muted: #6b7280;
+                --todo-surface: #1f2937; --todo-hover: #273244; --todo-page: #111827; --todo-text: #f3f4f6;
+            }
+        }
+        body { margin: 0; padding: 32px 16px; display: flex; flex-direction: column; align-items: center; gap: 12px;
+            background: var(--todo-page); color: var(--todo-text); font: 15px/1.4 system-ui, sans-serif; }
+        h1 { margin: 0; font-weight: 300; font-size: 40px; color: var(--todo-accent); }
+        .app { box-sizing: border-box; width: 100%; max-width: 520px; display: flex; flex-direction: column; overflow: hidden;
+            border: 1px solid var(--todo-line); border-radius: 10px; background: var(--todo-surface);
+            box-shadow: 0 1px 3px rgb(0 0 0 / 0.08); }
+        header { display: flex; border-bottom: 1px solid var(--todo-line); }
+        todo-list { max-height: 60vh; }
+        footer { display: flex; align-items: center; gap: 12px; padding: 8px 12px; font-size: 13px; color: var(--todo-muted);
+            border-top: 1px solid var(--todo-line); }
+        footer todo-filters { margin: 0 auto; }
+        .app:has(todo-summary[empty]) footer { display: none; }
+        .hint { font-size: 12px; color: var(--todo-muted); }
+    </style>
+</head>
+<body>
+    <h1>todos</h1>
+    <div class="app">
+        <header>
+            <todo-toggle-all empty></todo-toggle-all>
+            <todo-entry></todo-entry>
+        </header>
+        <todo-list></todo-list>
+        <footer>
+            <todo-summary empty></todo-summary>
+            <todo-filters></todo-filters>
+        </footer>
+    </div>
+    <todo-generate></todo-generate>
+    <p class="hint">Double-click a todo to edit it. Drag it, or press Alt+↑ and Alt+↓, to move it.</p>
+    <script type="module" src="./app/main.ts"></script>
+</body>
+</html>

package/src/samples/todo/shared/attach.browser.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { Entity, System, workers, World } from "../../../index.js";
+import { attach, entityOf, entityOfElement } from "./attach.js";
+
+afterEach(() => {
+    document.body.replaceChildren();
+});
+
+/** Two live entities of a world, for elements to show. */
+const twoEntities = async (): Promise<readonly [Entity, Entity]> => {
+    const spawned: Entity[] = [];
+    await using world = World.create({ [workers]: 0 });
+    await world.run(System.create({ name: "attachTest/spawn" }, ({ commands }) => {
+        spawned.push(commands.spawn([])({}), commands.spawn([])({}));
+    }));
+    const [first, second] = spawned;
+    if (first === undefined || second === undefined) throw new Error("Nothing spawned.");
+    return [first, second];
+};
+
+/** The entity `entityOf` finds for an event of `type` dispatched at `target`, as a listener on the body reads it. */
+const foundFor = (target: EventTarget, type = "attach-test"): Entity => {
+    let found: Entity | null = null;
+    const listener = (event: Event): void => { found = entityOf(event); };
+    document.body.addEventListener(type, listener);
+    target.dispatchEvent(new CustomEvent(type, { bubbles: true, composed: true }));
+    document.body.removeEventListener(type, listener);
+    if (found === null) throw new Error("The event didn't reach the body.");
+    return found;
+};
+
+describe("attach and entityOf", () => {
+    it("give the entity an element was attached to, returning the element", async () => {
+        const [first] = await twoEntities();
+        const element = document.createElement("div");
+        expect(attach(element, first)).toBe(element);
+        expect(entityOfElement(element)).toBe(first);
+        document.body.append(element);
+        expect(foundFor(element)).toBe(first);
+    });
+
+    it("find the first target on the composed path showing one, from where it was dispatched, through open shadow roots", async () => {
+        const [outer, inner] = await twoEntities();
+        /** A host showing `outer`, with a shadow root holding a span showing `inner`, its button, and a paragraph. */
+        const shadowed = (mode: ShadowRootMode) => {
+            const host = attach(document.createElement("div"), outer);
+            const root = host.attachShadow({ mode });
+            const button = document.createElement("button");
+            const plain = document.createElement("p");
+            root.append(attach(document.createElement("span"), inner), plain);
+            root.firstElementChild?.append(button);
+            document.body.append(host);
+            return { host, button, plain };
+        };
+        const open = shadowed("open");
+        expect([foundFor(open.button), foundFor(open.plain), foundFor(open.host)]).toEqual([inner, outer, outer]);
+        // A closed root's nodes aren't on the path a listener outside it sees.
+        const closed = shadowed("closed");
+        expect([foundFor(closed.button), foundFor(closed.plain), foundFor(closed.host)]).toEqual([outer, outer, outer]);
+    });
+
+    it("give none for elements and events showing none, and for null", () => {
+        const element = document.createElement("div");
+        document.body.append(element);
+        expect(entityOfElement(element)).toBe(Entity.none);
+        expect(entityOfElement(null)).toBe(Entity.none);
+        expect(foundFor(element)).toBe(Entity.none);
+        // After dispatch the composed path is empty.
+        const event = new CustomEvent("attach-test", { bubbles: true, composed: true });
+        attach(element, Entity.none).dispatchEvent(event);
+        expect(entityOf(event)).toBe(Entity.none);
+    });
+});

package/src/samples/todo/shared/attach.ts

@@ -0,0 +1,32 @@
+import { Entity } from "../../../index.js";
+
+/** The key an element holds the entity it shows under: only `attach` writes it. */
+const shown: unique symbol = Symbol("shown");
+
+/** An element showing an entity. */
+type Attached = { readonly [shown]: Entity };
+
+/**
+ * Records on `element` the entity it shows, for events from it, where the element is made for that entity, and
+ * returns it. Elements are never reused, so it's written once and lives as long as the element.
+ */
+export const attach = <E extends Element>(element: E, entity: Entity): E & Attached => Object.assign(element, { [shown]: entity });
+
+/** The entity a target shows, or none for one that shows none. */
+const shownBy = (target: EventTarget | Attached | null): Entity => target !== null && shown in target ? target[shown] : Entity.none;
+
+/** The entity an element shows, as `todo-move`'s `item` and `before` name them, or none for null or one that shows none. */
+export const entityOfElement = (element: Element | null): Entity => shownBy(element);
+
+/**
+ * The entity the first target on an event's composed path shows, from where it was dispatched outward, or none when no
+ * target shows one. Read while the event dispatches, as listeners do: the path is empty after.
+ */
+export const entityOf = (event: Event): Entity => {
+    const path = event.composedPath();
+    for (let k = 0; k < path.length; k++) {
+        const found = shownBy(path[k]);
+        if (found !== Entity.none) return found;
+    }
+    return Entity.none;
+};

package/src/samples/todo/shared/connect.ts

@@ -0,0 +1,21 @@
+import type { World } from "../../../index.js";
+
+/** Stops what `connect` started. */
+export type Disconnect = () => void;
+
+/**
+ * Connects a feature's events, dispatched within `root`, to runs of `world`. A run's failures are in its report, which
+ * the app logs; a rejected run goes unhandled, which the browser logs.
+ */
+export type Connect = (world: World, root: HTMLElement) => Disconnect;
+
+/** Stops every one of `disconnects`. */
+export const all = (...disconnects: readonly Disconnect[]): Disconnect => () => {
+    for (const disconnect of disconnects) disconnect();
+};
+
+/** Listens for one event type on `root` until the returned function is called. */
+export const on = <K extends keyof HTMLElementEventMap>(root: HTMLElement, type: K, listener: (event: HTMLElementEventMap[K]) => void): Disconnect => {
+    root.addEventListener(type, listener);
+    return () => root.removeEventListener(type, listener);
+};