@adobe/data-ai 0.9.82 → 0.9.84

package/.claude/rules/README.md

@@ -0,0 +1,42 @@
+# Rules
+
+Distributable Claude project rules for data-oriented architecture. Copy or
+symlink this directory into your project's `.claude/rules/` layout; Claude
+discovers `.md` files recursively and, for rules carrying a `paths:`
+frontmatter glob, injects them only when a matching file is in context.
+
+## Layout mirrors the feature-folder structure
+
+The `features/` subtree mirrors the four feature layers one-to-one, so the
+guidance for a folder lives at the same path shape as the code it governs. A
+folder's own `index.md` holds just enough to understand that folder; each
+child gets its own file (recursing wherever the source tree does):
+
+```
+features/
+  index.md            # the feature layering as a whole (ui → ecs → services → data)
+  data/
+    index.md          # data-type namespaces (foundation)
+    state.md          # the State aggregate: pure transforms & derivations
+  services/index.md   # service interfaces + service types
+  ecs/
+    index.md          # the ECS layer + layered database plugins
+    components.md  resources.md  archetypes.md
+    computed.md  indexes.md  transactions.md  services.md  actions.md
+    systems.md  conformance.md
+  ui/index.md         # UI (points to element / presentation / lazy-element file rules)
+```
+
+Alongside `features/`, the rules-root `.md` files hold the **cross-cutting**
+patterns the feature rules reference — `namespace.md`, `data-modelling.md`,
+`type-casts.md`, `function-references.md`, `cohesion.md`, `archetypes.md` (row
+iteration), `plugin-modelling.md`, and the UI file rules (`element.md`,
+`lazy-element.md`, `presentation.md`). They live here so the bundle is self-contained; this repo
+symlinks them into its own `.claude/rules/` (as it does `features/`).
+
+Each rule's `paths:` glob is scoped to `**/features/*/<layer>/…`, so these
+rules apply only once an application opts into the feature-folder pattern
+(source organized under `features/<name>/`). Editing
+`features/<name>/ecs/<layer>-database/components/foo.ts` pulls in both
+`ecs/index.md` (the layer overview) and `ecs/components.md` (the specifics) —
+at creation and at every later edit.

package/.claude/rules/archetypes.md

@@ -0,0 +1,60 @@
+---
+description: Authoring rules for ECS systems that iterate archetype rows.
+globs: "**/*.ts"
+---
+
+# Archetypes — iteration rules
+
+## Express selection in the query, not the loop
+
+`queryArchetypes(include, { exclude })` accepts both required and excluded
+component lists. Use them. Don't query a wider set and then skip rows or
+archetypes with an `if`.
+
+```ts
+// ❌ post-filter
+for (const arch of db.store.queryArchetypes(["position", "rotation"])) {
+    if (arch.components.has("_worldMatrix")) continue;
+    ...
+}
+
+// ✅ declarative
+for (const arch of db.store.queryArchetypes(
+    ["position", "rotation"],
+    { exclude: ["_worldMatrix"] },
+)) {
+    ...
+}
+```
+
+## When every row migrates out, iterate tail → head
+
+Archetypes are densely packed. Removing or migrating a row that isn't the
+last one triggers a hole-fill: the tail row is moved into the gap.
+Iterating `0 → rowCount-1` while migrating every row pays this cost on
+every iteration. Iterating `rowCount-1 → 0` means each removal is from
+the tail — no shift, indices ahead of the cursor stay valid.
+
+```ts
+// ❌ shifts the tail into every hole, and the snapshot allocation is
+//    only there to survive the shifts.
+const ids = [...];
+for (let i = 0; i < arch.rowCount; i++) ids[i] = arch.columns.id.get(i);
+for (const id of ids) db.store.update(id, { _worldMatrix: Mat4x4.identity });
+
+// ✅ no shifts, no allocation
+for (let i = arch.rowCount - 1; i >= 0; i--) {
+    db.store.update(arch.columns.id.get(i), { _worldMatrix: Mat4x4.identity });
+}
+```
+
+If only *some* rows migrate (filter inside the loop), snapshot the ids
+you'll touch — forward iteration is fine because rows you don't touch
+stay put.
+
+## Don't snapshot what the query already filters
+
+A snapshot of "all entity ids in this archetype right now" is only
+needed when forward iteration would invalidate. Reverse iteration
+removes the need; an `exclude` clause removes the need to look at rows
+that don't qualify in the first place.

package/.claude/rules/cohesion.md

@@ -0,0 +1,66 @@
+---
+paths:
+  - 'packages/**/*.ts'
+  - 'packages/**/*.tsx'
+---
+
+# Cohesion — make related code share a name
+
+Code that serves one purpose should be reachable through one name.
+Cohesion that exists only in the reader's head is a smell — make it
+visible by extracting a function, a hook, or a folder.
+
+## Within a file (statement cohesion)
+
+When adjacent statements share a single purpose — same dependencies,
+same lifetime, same conceptual job — collapse them behind one named
+local helper. The surrounding scope should read at one level of
+abstraction; the lower-level mechanics live inside the helper.
+
+This is *Composed Method* / *SLAP*. The fix is local: a private
+function or local hook in the same file, no public API, no claim of
+reusability. Naming makes the cohesion structural instead of leaving
+it for the reader to assemble.
+
+```ts
+// Smell: two statements that are one concept ("owned controller")
+const controller = useMemo(() => createController(svc, cfg), [svc, cfg]);
+useEffect(() => () => controller.dispose(), [controller]);
+
+// Fix: cohesion has a name
+const controller = useDisposableController(svc, cfg);
+```
+
+## Across files (folder cohesion)
+
+One public export per file. Private declarations inside the file are
+fine — they are implementation detail and are tested indirectly
+through the public export. Only the public export gets a sibling
+`*.test.ts`.
+
+**Exception: barrels.** An `index.ts` (and a namespace's `public.ts`)
+exists precisely to re-export a folder's public surface, so it carries
+many exports. That is the barrel's whole job — it declares nothing of its
+own, only `export … from "./…"`. The one-export rule governs files that
+*declare*, not files that *re-export*.
+
+When a public file wants *helper sibling files*, promote the cluster
+into a folder named after the concept. Helpers never sit at peer
+level with unrelated public files; the folder is the new boundary.
+
+```
+ok                  smell                       fix
+foo.ts              foo.ts                      foo/
+foo.test.ts         foo-helper.ts                 foo.ts
+bar.ts              foo.test.ts                   foo-helper.ts
+bar.test.ts         bar.ts                        foo.test.ts
+                    bar.test.ts                 bar.ts
+                                                bar.test.ts
+```
+
+## Heuristic
+
+For any pair of symbols — two statements, two files — ask: "is their
+relationship visible in the structure, or only in the reader's
+head?" If the latter, give the cohesion a name: a function, a hook,
+or a folder.

package/.claude/rules/data-modelling.md

@@ -0,0 +1,71 @@
+---
+---
+
+# Data modelling — locality of knowledge
+
+A type's identity (its members) is named only inside its own folder.
+Every other module either accepts members as parameters, narrows broader
+input with the type's `is` guard, or iterates `Type.values`.
+
+This applies to any closed set: enums, role tags, status codes,
+discriminated unions.
+
+## Example
+
+```ts
+// types/http-method/schema.ts
+export const schema = { type: "string", enum: ["GET", "POST", "PUT", "DELETE"] }
+    as const satisfies Schema;
+
+// In an unrelated request-counter plugin:
+
+// ❌ Members spelled outside the type folder
+const counts = { GET: 0, POST: 0, PUT: 0, DELETE: 0 };
+function record(m: string) {
+    if (m === "GET" || m === "POST" || m === "PUT" || m === "DELETE") counts[m]++;
+}
+
+// ✅ HttpMethod owns its identity; this file owns the counter
+const counts: Partial<Record<HttpMethod, number>> = {};
+function record(m: unknown) {
+    if (!HttpMethod.is(m)) return;
+    counts[m] = (counts[m] ?? 0) + 1;
+}
+```
+
+## Shape of keyed collections
+
+- `Record<EnumKey, T>` — every key required at all times. Default lists
+  every member. Use only when state is genuinely dense.
+- `Partial<Record<EnumKey, T>>` — keys appear and disappear over the
+  lifecycle. Default `{}`. Use for sparse / per-actor state.
+
+If the value can be meaningfully absent for a present member (a peer
+exists but hasn't moved yet, an entry hasn't loaded), use `Partial`.
+Reserve `Record` for descriptors where every member must have a value.
+
+Sibling fields (`{ countGET, countPOST, countPUT, countDELETE }`) duplicate
+the type's identity into field names — always replace with a keyed
+collection.
+
+## Per-member variation lives with the type
+
+When something *genuinely differs* per member (colours, labels, icons),
+the descriptor lives in the type's folder as a `Record<EnumKey, V>`,
+named for its purpose:
+
+```ts
+// types/http-method/method-color.ts
+export const methodColor: Record<HttpMethod, string> = {
+    GET: "#06f", POST: "#0a0", PUT: "#fa0", DELETE: "#f00",
+};
+```
+
+A per-member string built at the call site (`"req-${method.toLowerCase()}"`,
+`<HttpMethod>` BEM modifiers, SVG ids) is the same leak in derivation form:
+the *mapping rule* belongs in the type's folder, not at the call site.
+
+A static stylesheet that lists `.row--get { … } .row--post { … } …` is
+the same leak in CSS form. Drive per-member visuals from the descriptor
+(inline `style`, a CSS custom property, or a generated stylesheet) so
+the enum is not re-encoded at the rendering layer.

package/.claude/rules/element.md

@@ -0,0 +1,130 @@
+---
+paths:
+  - 'packages/**/*-element.ts'
+---
+
+# Container element authoring
+
+A *container element* is a UI element whose only job is to bridge an
+ECS / data service to a pure presentation function: subscribe to state,
+hand it down, wire actions back up. It owns no business logic.
+
+This rule is framework-agnostic. The framework-specific bindings are in
+the table at the bottom.
+
+> **Out of scope:** sibling `*presentation.ts`, `*.css.ts`, `*.test.ts`,
+> and `*.stories.ts` files in the same folder are governed by their own
+> rules. Pure UI primitives that take all of their inputs through props
+> (no service subscription) are not container elements either.
+
+## The discipline
+
+A container element fits on screen. Its body contains:
+
+1. Optional styles assignment.
+2. Zero or more locator-shaped inputs (`entityId`, `userId`, `route`)
+   that identify *where* to load this instance's data.
+3. One subscription read of the bound data service.
+4. Action callbacks — one-line invocations of service transactions or
+   actions, never logic.
+5. One delegation to the matching presentation function.
+
+That is the entire surface. No internal state, no event handlers, no
+lifecycle overrides, no derivation math, no timers, no event emitters,
+no broadcast channels, no synchronous data reads.
+
+### Bootstrap exception
+
+A *bootstrap container* — one that constructs its service rather than
+consuming a pre-existing one (e.g. an element that owns a WebRTC
+handshake before mounting a child app) — may also accept dependency-
+injection props that configure that construction (the plugin to use,
+a child tag name, mapping functions). Those props feed a sibling
+controller invoked from a `useMemo` / `useEffect` hook; they never
+appear inside render branching. Use sparingly.
+
+### Imperative / canvas containers
+
+A container whose "presentation" is an imperative surface (a `<canvas>` /
+WebGL context) can't render reactively — a real-time feature mutates
+component columns in place each frame, which fires no observers. Such a
+container may:
+
+- run a `requestAnimationFrame` draw loop inside a `useEffect` (cancelled in
+  its cleanup) that reads the live store synchronously and calls a pure
+  `draw(ctx, scene)`;
+- read the **full** database for those reads via the base class's protected
+  accessor (`this.database` on a Lit `DatabaseElement`) — never cast the
+  restricted `service` back to the full surface;
+- hold ephemeral input-hardware state (a held-key `useRef`, pointer state)
+  gathered by `useWindowEvent` and forwarded to a transaction.
+
+The discipline still holds otherwise: no game/derivation logic (it lives in
+`data/` and systems), the draw function is pure, and the reactive HUD around
+the canvas is a normal subscribe-and-delegate presentation.
+
+## Subscription reads must be raw
+
+Each value in the subscription block is a direct read of a service
+observable or computed — no `.map`, `.filter`, no inline composition.
+If derivation is needed, it lives as a service computed; if used only
+by this element, define the computed in a sibling file and import it.
+
+## Action callbacks are one-liners
+
+Each callback assembles arguments and invokes one service action or
+transaction. No clamping, normalisation, branching, or shape-building.
+Logic belongs in the action / transaction layer.
+
+Transactions and actions are pure, already-bound functions — when a
+callback would just forward the same arguments to one of them, pass the
+function **by reference**, don't wrap it in an identity arrow:
+
+```ts
+// ❌ identity wrapper — adds nothing
+setOperation: (op) => this.service.transactions.setOperation(op),
+// ✅ same signature, pass it through
+setOperation: this.service.transactions.setOperation,
+```
+
+Only write an arrow when you genuinely adapt the call (drop an event
+arg, reorder, supply a captured locator).
+
+## Lifecycle goes through hooks
+
+Mount / unmount / update behaviour routes through a hook abstraction
+(`useEffect`, `useFocus`, etc.) called inside the render body — never
+through a framework lifecycle method (`connectedCallback`, `componentDidMount`,
+`onMount`).
+
+## Action returns are not consumed
+
+Actions are fire-and-forget. If a caller needs a result, that's a
+transaction the binding invokes directly, *or* a new observable to
+subscribe to — never a return value awaited in render.
+
+## Deletion test
+
+Strip the file to its essentials. What remains should be: optional
+styles, locator props, one subscription call, callbacks, and one render
+delegation. Anything else is a violation — find the missing computed,
+transaction, or hook.
+
+## Framework bindings
+
+| Framework | Container is             | Subscription hook     | Locator inputs       | Render delegation                                |
+| --------- | ------------------------ | --------------------- | -------------------- | ------------------------------------------------ |
+| Lit       | `DatabaseElement<P>`     | `useObservableValues` | `@property` only     | `presentation.render({ ...values, ...callbacks })` |
+| React     | function component       | `useObservableValues` | function arguments   | `<Presentation {...values} {...callbacks} />`    |
+| Solid     | component function       | framework-specific    | function arguments   | `<Presentation {...values} {...callbacks} />`    |
+
+Lit-only: `static styles = styles` from a sibling `*.css.ts`. `@property`
+exists *only* for locator inputs — never for state, never for derived
+values, never for parent-forwarded flags. The `P` in `DatabaseElement<P>` (and
+the `get plugin()` it returns) is the surface the element *consumes* — never the
+varying topmost-layer name (see `features/ecs/index.md`): `typeof
+FeatureDatabase.plugin` for a self-contained feature. **Exception:** an element
+meant to be *extended* — injected with various databases that build on this
+feature (a peer app that adds an agent, a p2p/presence build) — types on the
+minimal base layer it consumes (e.g. `ComputedDatabase.plugin`) so every
+extending database is assignable.

package/.claude/rules/features/data/index.md

@@ -0,0 +1,35 @@
+---
+paths:
+  - '**/features/*/data/**/*.ts'
+---
+
+# data/ — the data model
+
+The foundation layer: the feature's **data types**. A data type is a
+readonly, JSON-serializable value suitable for persistence and for
+communication over the wire — no functions, no handles, just plain data.
+It depends on nothing but `@adobe/data` and other `data/` declarations, and
+needs no knowledge of anything built on top of it.
+
+Each data type is its own namespace folder (see `namespace.md`), holding
+its schema, its derived type, and its pure synchronous helpers together:
+
+```
+data/player-mark/
+  player-mark.ts   # type alias + `export * as PlayerMark from "./public.js"`
+  schema.ts        # `export const schema = { … } as const satisfies Schema`
+  public.ts        # re-exports schema + helpers
+  is.ts  values.ts  opponent.ts  …   # one pure helper per file
+```
+
+- The **type is derived from the schema** (`Schema.ToType<typeof schema>`),
+  never hand-written alongside it.
+- The **schema is the single source of truth** for the shape; the derived
+  type and every consumer flow from it.
+- Helpers are synchronous and pure; each has a sibling `*.test.ts`.
+- Objects with only numeric 32 bit values/sub-structs should use Schema.fromStructProperties
+  It guarantees a valid struct schema which will be stored in linear memory.
+
+One folder is special: **`data/state/`** holds the feature's single `State`
+aggregate and its pure transforms/derivations (its own rule, `state.md`);
+the individual type folders here are its building blocks.

package/.claude/rules/features/data/state.md

@@ -0,0 +1,54 @@
+---
+paths:
+  - '**/features/*/data/state/**/*.ts'
+---
+
+# data/state/ — the State specification
+
+`State` is the whole feature modelled as **one immutable object** — the
+pure, fully-tested source of truth for the feature. Modelling everything as
+a single value keeps each transform a small, trivially-testable function of
+state: collections of entity sub-types plus scalar fields.
+
+```ts
+// state.ts — the aggregate, plus the namespace of transforms/derivations.
+export type State = {
+    readonly todos: readonly Todo[];        // a collection of entity sub-types
+    readonly displayCompleted: boolean;     // a scalar field
+};
+export * as State from "./public.js";
+```
+
+## Transforms — one per file, `(state, …args) => state`
+
+- **Pure.** No I/O, no framework, no mutation — return a new value.
+- **Narrow in, same shape out.** Write on the smallest slice the transform
+  needs and keep the input generic over that slice so it lifts to
+  full-state-in / full-state-out:
+
+  ```ts
+  export const playMove = <T extends Pick<State, "board" | "firstPlayer">>(
+      state: T,
+      input: PlayMoveArgs,
+  ): T => { /* … return { ...state, board: … } */ };
+  ```
+
+  A whole-`State` transform (`restartGame(state: State): State`) is fine when
+  it genuinely touches everything.
+- Args may be **narrowed or omitted** (`toggleDisplayCompleted(state)`).
+- Guard and **return `state` unchanged** on a no-op / illegal input rather
+  than throwing — this keeps transforms idempotent under repeated application.
+- Each transform has a sibling `*.test.ts`; performance is irrelevant here,
+  correctness is everything. Keep its cases in a sibling `<transform>.cases.ts`
+  typed `ConformanceCase<Args>[]` (the shared `conformance-case.ts` type) —
+  spec-owned truth the matching ecs conformance test imports unchanged (see
+  `ecs/conformance.md`). Author `before`/`after` as full `State`
+  (`{ ...State.create(), …overrides }`); the generic-slice signature lets them
+  flow through. Tolerant full-`State` equality is the shared
+  `expect-state-matches.ts`, alongside the cases here.
+
+## Derivations — `(state) => value`
+
+Pure selectors (`visibleTodos(state)`). Sub-type math (a winner, a status)
+lives on the relevant `data/<type>` namespace; `state/` only composes over
+the whole aggregate.

package/.claude/rules/features/ecs/actions.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - '**/features/*/ecs/**/actions/**/*.ts'
+---
+
+# ecs/actions/ — async orchestration
+
+One action per file: a function taking the **whole database** as its first
+argument and pure `data/` args. Actions orchestrate anything *outside* a
+single transaction — awaiting a `services/` port, sequencing calls, deriving
+timing — and then commit the result through a transaction.
+
+```ts
+import type { ServiceDatabase } from "../../service-database/service-database.js";
+
+export const addRandomTodo = async (db: ServiceDatabase) => {
+    const name = await db.services.nameGenerator.generateName(); // await a services/ port
+    db.transactions.createTodo({ name });                        // then exactly one commit
+};
+```
+
+- Type the `db` parameter on the lowest database layer exposing what the
+  action touches — usually `ServiceDatabase` (services **and**
+  transactions). Never the action layer itself (that would be a cycle).
+- **Call at most one transaction** per action, so undo/redo stays one step
+  per operation.
+- **Fire-and-forget.** An action's return value is not consumed; results flow
+  back through observables. `db.services.*` calls are `void` or
+  awaited-internally, never surfaced to the caller.
+- Do the outside-world work here: await/sequence `services/` calls, and if a
+  slow call needs timing, compute it here around the call.
+- An `index.ts` barrel feeds the `actions` plugin facet.

package/.claude/rules/features/ecs/archetypes.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - '**/features/*/ecs/**/core-database/archetypes.ts'
+---
+
+# core-database/archetypes.ts — the feature's archetypes
+
+An archetype is a named, ordered set of component keys — a kind of entity. One
+file, one export: `archetypes`, built with `Database.archetypes(components, …)`,
+which validates every key against the component map and preserves each
+archetype's literal tuple (so no per-archetype `as const satisfies`):
+
+```ts
+import { Database } from "@adobe/data/ecs";
+import { components } from "./components.js";
+
+export const archetypes = Database.archetypes(components, {
+  Todo: ["todo", "name", "complete", "order", "dragPosition", "assignees"],
+});
+```
+
+- `UpperCase` archetype names — an archetype names a *shape*, the way a class
+  name does.
+- Archetypes may **span scopes**: a document entity can include an ephemeral
+  `session` column (e.g. a live `dragPosition` slot) — the `components` map
+  already merges every scope, so keys from any scope validate.
+- Archetypes are a packing / iteration convenience, **not** part of the
+  serialized data model.
+
+## Drift guard against the data-type
+
+An archetype that mirrors a `data/` row type carries a **non-exported**
+compile-time check — infer the row shape from the archetype and assert it equals
+that data-type — so the two can't drift apart:
+
+```ts
+import { Schema } from "@adobe/data/schema";
+import type { Assert, Equal } from "@adobe/data/types";
+import type { PlacedMark } from "../../data/placed-mark/placed-mark.js";
+
+const _schema = Schema.fromArchetype(components, archetypes.PlacedMark);
+type _Check = Assert<Equal<Schema.ToType<typeof _schema>, PlacedMark>>;
+```
+
+Iterating archetype **rows** at runtime is a separate concern — see the
+rules-root `archetypes.md`.

package/.claude/rules/features/ecs/components.md

@@ -0,0 +1,41 @@
+---
+paths:
+  - '**/features/*/ecs/**/core-database/components.ts'
+---
+
+# core-database/components.ts — the feature's components
+
+One file, one export: `components`, built with `Database.components(...)`. A
+component binds a `data/` type into ECS column storage, grouped by schema scope.
+The scope groups are optional — declare only the ones you use.
+
+Bind each schema straight from its `data/` type (or a primitive schema); don't
+author shapes here. Component entries are any `Schema` — no `default` required
+(that's resources):
+
+```ts
+import { Database } from "@adobe/data/ecs";
+import { Boolean, True } from "@adobe/data/schema";
+import { PlayerMark } from "../../data/player-mark/player-mark.js";
+import { DragPosition } from "../../data/drag-position/drag-position.js";
+
+export const components = Database.components({
+  document: { mark: PlayerMark.schema, complete: Boolean.schema },
+  session:  { dragPosition: DragPosition.schema },
+});
+```
+
+- A component name may differ from the type it stores (`position` of a `Vec3`,
+  `mark` of a `PlayerMark`) — the field name describes the role, the schema the
+  shape.
+- **Scope = which group it sits in** (see `ecs/index.md` for the four scopes and
+  their flags). `document` is the common case; hover a scope key for its
+  meaning. Never write `nonShared` / `nonPersistent` by hand — the group applies
+  them.
+- **Shared cross-feature columns live in `data/`** and go in `document` (which
+  preserves schema identity) so `combinePlugins` dedupes them.
+- Struct vs. object storage and schema selection are properties of the `data/`
+  type, decided there.
+- Don't infer entity type based upon component membership.
+  Consider using a const: true "tag" component or a type/kind enumerated value if needed.
+  Note that *many* good ecs designs don't care the type of the entity and only act on components.

package/.claude/rules/features/ecs/computed.md

@@ -0,0 +1,26 @@
+---
+paths:
+  - '**/features/*/ecs/**/computed/**/*.ts'
+---
+
+# database/computed/ — derived observable values
+
+One derived value per file: a `cached` function of a database layer that
+returns an `Observe` of state projected through pure `data/` helpers.
+Derivation logic itself lives in `data/`; a computed only wires a db
+observable to it.
+
+```ts
+import { cached } from "@adobe/data/cache";
+import { Observe } from "@adobe/data/observe";
+import { BoardState } from "../../../data/board-state/board-state.js";
+import type { IndexDatabase } from "../../index-database/index-database.js";
+
+export const status = cached((db: IndexDatabase) =>
+    Observe.withFilter(db.observe.resources.board, BoardState.deriveStatus),
+);
+```
+
+Type the parameter on the lowest database layer that exposes what it
+reads. An `index.ts` barrel re-exports every computed; `computed-database.ts`
+registers it under the `computed` facet.