@adobe/data-ai 0.9.83 → 0.9.84

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

@@ -0,0 +1,34 @@
+---
+paths:
+  - '**/features/*/services/**/*.ts'
+---
+
+# services/ — async capability contracts
+
+Async ports: processing, persistence, observation, generation. A service
+is the boundary between pure feature code and the outside world, which is
+why its members are async — enabling cross-process portability and lazy
+loading (`AsyncDataService.createLazy`).
+
+This layer holds **service interfaces**, one per `<name>-service/` folder;
+the export and folder both carry the `-service` suffix. Each is a
+namespace folder (`namespace.md`).
+
+- The contract is an `interface` — the only place `interface` is used in
+  the codebase — validated immediately with
+  `Assert<AsyncDataService.IsValid<typeof MyService>>`.
+- Members are async only: `void | Promise<T> | AsyncGenerator<T> | Observe<T>`.
+- Provide `create*` factories.
+
+## Where the I/O types live
+
+Most input/output types belong to a single service — declare them **on
+that service's namespace** (`MyService.SomeInput`) and expose them only
+when something external actually references them; not everything does.
+
+A **service type** may be non-serializable (callbacks, function
+signatures) — that's what distinguishes it from a `data/` type. If an I/O
+value is a plain serializable value, prefer a `data/` type instead.
+
+A non-service type sits *directly* in `services/` **only** when it is
+genuinely shared across more than one service — rare, but it happens.

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

@@ -0,0 +1,31 @@
+---
+paths:
+  - '**/features/*/ui/**/*.ts'
+---
+
+# ui/ — user interface
+
+The top layer: UI that binds the `ecs/` database to what the user sees. It
+owns no business logic — it subscribes to state, hands it to a pure
+presentation, and wires actions back to transactions.
+
+The folder name is framework-neutral; its contents are framework-specific
+(Lit elements, React components, …). Each UI unit is its own folder, named
+for the concept, exposed through a single lazy wrapper so consumers pay no
+bundle cost for what they never render:
+
+```
+<name>/
+  <name>.ts               # PUBLIC: lazy wrapper — the only external import
+  <name>-element.ts       # PRIVATE: the container (subscribe + delegate)
+  <name>-presentation.ts  # PRIVATE: pure render(props) function
+  <name>.css.ts           # PRIVATE: styles
+```
+
+The detailed rules for each file kind (Lit bindings shown; React/Solid
+tables inside each):
+
+- `lazy-element.md` — the folder layout and lazy-wrapper mechanics.
+- `element.md` — the container discipline (subscribe, callbacks, one
+  delegation; no logic).
+- `presentation.md` — the pure `render` function.

package/.claude/rules/function-references.md

@@ -0,0 +1,35 @@
+---
+paths:
+  - 'packages/**/*.ts'
+  - 'packages/**/*.tsx'
+---
+
+# Pass functions by reference — don't wrap them
+
+When a value is already a function with the signature the callee wants, pass it
+**by reference**. Never re-wrap it in an arrow that only forwards its arguments:
+
+```ts
+// ❌ identity wrappers — the arrow adds nothing
+expectConforms({ spec: (s, dt) => State.resolveBulletHits(s, dt), apply: (store, a) => hitAsteroid(store, a) });
+onClick={() => save()}
+todos.map((t) => render(t))
+
+// ✅ pass the function itself
+expectConforms({ spec: State.resolveBulletHits, apply: hitAsteroid });
+onClick={save}
+todos.map(render)
+```
+
+Fewer parameters than the callee supplies is fine — extra args are ignored — so a
+`(store) => void` transaction passes directly where `(store, args) => void` is
+expected. Wrap **only** when the call genuinely *adapts*: drops or reorders args
+(`(_state, bounds) => createInitial(bounds)`), reaches into one (`(s, a) =>
+del(s, a.id)`), or supplies a captured value.
+
+**The lone real exception — unbound methods.** A method pulled off a class type or
+an unbound instance loses its `this` when passed bare, so it needs a wrapper (or
+`.bind`). This is *exceptionally rare here*: everything in this codebase is pure
+functions and closures — every database's `transactions` / `actions` / `computed`
+and every `data/` helper is an already-bound standalone function. So before
+reaching for a wrapper, confirm you're not just forwarding args.

package/.claude/rules/lazy-element.md

@@ -0,0 +1,127 @@
+---
+paths:
+  - 'packages/**/ui/**/*.ts'
+---
+
+# Lazy Lit element pattern
+
+Each Lit custom element lives in its own folder and is exposed to
+external code through a single lazy wrapper function. The element class
+itself is loaded only on first invocation, so consumers pay no bundle
+cost for elements they never render.
+
+## Folder layout
+
+For an element conceptually named `foo`:
+
+```
+foo/
+  foo.ts                # PUBLIC: lazy wrapper Foo()
+  foo-element.ts        # PRIVATE: the LitElement class
+  foo-presentation.ts   # PRIVATE: pure render(props) function
+  foo.css.ts            # PRIVATE: styles
+```
+
+External code only ever imports `foo.ts`. The other three are
+implementation detail of the folder.
+
+## The lazy wrapper (`foo.ts`)
+
+A PascalCase function that returns an `html` template fragment. It
+fires a dynamic `import()` of the element file on every call (the
+import promise is intentionally unawaited — the browser deduplicates
+and Lit upgrades the unknown element once the class registers).
+
+```ts
+import { html } from "lit";
+import type { TemplateResult } from "lit";
+
+export const Foo = (args: { count: number }): TemplateResult => {
+    void import("./foo-element.js");
+    return html`<my-foo .count=${args.count}></my-foo>`;
+};
+```
+
+Rules:
+
+- Exactly one public export: the wrapper function.
+- Argument shape is a single typed object (or omitted entirely).
+- The custom-element tag is hardcoded as a literal — no shared `tagName`
+  symbol crosses the wrapper / element boundary.
+- The wrapper passes typed args via `.prop=${args.prop}` bindings, never
+  attribute strings.
+- **Injecting a database:** a `DatabaseElement` receives its live database
+  through the `.service` setter — that is the one DI property it exposes
+  (`set service(db)`; there is no *public* `.database` binding target — the
+  `protected get database()` is a subclass's own read path, not a DI property).
+  A wrapper over a `DatabaseElement` binds `.service=${args.service}`. Binding
+  any other name (`.database=`) is silently inert: the setter never runs, so the element
+  falls back to `connectedCallback` self-creating from `this.plugin` and the
+  injected database is discarded.
+
+## The element file (`foo-element.ts`)
+
+```ts
+import { customElement } from "lit/decorators.js";
+import * as presentation from "./foo-presentation.js";
+import { styles } from "./foo.css.js";
+
+const tagName = "my-foo";
+
+declare global {
+    interface HTMLElementTagNameMap {
+        [tagName]: FooElement;
+    }
+}
+
+@customElement(tagName)
+export class FooElement extends LitElement {
+    static styles = styles;
+    render() { return presentation.render({ /* … */ }); }
+}
+```
+
+- `tagName` is a private const; the global `HTMLElementTagNameMap`
+  declaration uses it so the wrapper's `html\`<my-foo></my-foo>\``
+  template is type-checked.
+- One public export: the class.
+- Side-effect imports of *other* element files are forbidden — invoke
+  their lazy wrappers from inside the presentation instead, so children
+  are tree-shaken too.
+
+## Composition: render children via wrappers
+
+Inside a presentation, render child elements by calling their lazy
+wrappers, not by writing their tag literals or by importing their
+classes. This is what keeps the lazy graph honest end-to-end.
+
+```ts
+import { html } from "lit";
+import { Bar } from "../bar/bar.js";
+
+export const render = (props: { … }) => html`
+    <section>${Bar({ kind: props.kind })}</section>
+`;
+```
+
+## Dynamic-tag rendering
+
+Do not use `lit/static-html` / `unsafeStatic` to switch between
+elements. Take a render-callback prop instead:
+
+```ts
+@property({ attribute: false })
+renderChild!: (args: { service: SomeDb }) => TemplateResult;
+
+// caller passes:
+.renderChild=${({ service }) => Bar({ service })}
+```
+
+This keeps the child's lazy wrapper as the single point of contact and
+preserves type checking across the boundary.
+
+## Entry-point mounting
+
+Even the top-level element is mounted through its lazy wrapper. A
+`main.ts` calls `render(Foo(args), document.getElementById("app")!)` —
+no side-effect import, no `document.createElement`.

package/.claude/rules/namespace.md

@@ -0,0 +1,179 @@
+---
+paths:
+  - 'packages/**/src/**/*.ts'
+---
+
+# Type namespace pattern
+
+Each type lives in its own folder. The folder's eponymous file is the only
+public import surface; a `<Type>` namespace re-exports every helper.
+
+```
+src/types/<type-name>/
+  <type-name>.ts   # type alias + `export * as <Type> from "./public.js"`
+  schema.ts        # `export const schema = { ... } as const satisfies Schema`
+  public.ts        # re-exports every public helper
+  <helper>.ts      # one declaration per file, camelCase
+```
+
+## Example
+
+```ts
+// types/log-level/schema.ts
+export const schema = { type: "string", enum: ["debug", "info", "warn", "error"] }
+    as const satisfies Schema;
+
+// types/log-level/log-level.ts
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+export type LogLevel = Schema.ToType<typeof schema>;
+export * as LogLevel from "./public.js";
+
+// types/log-level/public.ts
+export { schema } from "./schema.js";
+export { is } from "./is.js";          // when external code narrows broader input
+export { values } from "./values.js";  // when external code iterates the set
+```
+
+Consumers import only `LogLevel` from `log-level/log-level.ts` and use it
+as both type and namespace (`LogLevel.is(x)`, `LogLevel.values`).
+
+## Rules
+
+- Never import `schema.ts` or `public.ts` from outside the folder.
+- Consumers use one import: `import { LogLevel } from "./log-level.js"`.
+  The same identifier serves as type *and* namespace — a separate
+  `import type` is unnecessary and produces a duplicate-identifier error.
+- Helper files use `import type` from the sibling `<type-name>.ts` to
+  avoid cycling through `public.ts`.
+- Add `is` / `values` / per-member descriptors only when a consumer
+  actually needs them — not preemptively. A consumer in a not-yet-built
+  higher layer counts: a presentational descriptor the `ui/` will need
+  (per-member glyphs, a keypad `values` list) may be authored with the
+  data type, but give it a one-line doc naming the intended consumer (as
+  `player-mark/mark-color.ts` does) so the need is recorded, not guessed.
+
+## Strict single public export per file
+
+**One public export per file** — this is strict, not a preference. A file
+that *declares* exports exactly one public symbol (private declarations
+inside it are fine and are tested through the public export). The reason is
+cohesion: when several declarations share one file, each pulls its own
+external imports to the top and the file becomes a jumble that belongs to no
+single concept. One declaration → one file → imports that are about that one
+thing.
+
+More than one public export in a file is allowed **only when explicitly
+approved on a per-file or per-file-type basis** — the deliberate, named
+patterns below, nothing else. There is no "shared imports" or "cohesive set"
+escape hatch: a folder of sibling pure functions over one type (e.g. the
+`vec3`/`vec4`/`mat4x4` math) is one function per file, collected by the
+folder's `public.ts` barrel — dozens of one-line files is the intended shape,
+not a reason to lump.
+
+- **Barrels** — `index.ts` and a namespace's `public.ts` *only* re-export
+  (`export … from "./…"`); they never declare. Many re-exports is their job.
+- **The eponymous namespace file** (`<type>.ts`) — the type alias plus
+  `export * as <Type> from "./public.js"` (a type and its namespace value).
+- **The single-file pattern** (below) — one value export plus type-only
+  exports, for a trivial namespace not worth a folder.
+- **`<format>-schema.ts`** — a borrowed data-format projection (plain
+  `interface`s), next to its parser/emitter.
+- **Explicit authoring-cohesion files** — where two exports are genuinely one
+  unit to author, e.g. a presentation's `render` plus a co-located fixture
+  bundle (`unlocalized`). Rare; the pair must truly belong together.
+
+Everything else is one-per-file. In particular, **ECS facet folders
+(`components/`, `resources/`, `archetypes/`, `indexes/`, …) are not exempt**:
+one component / resource / archetype / index per file, collected by the
+folder's `index.ts` barrel. Collapsing several into one `index.ts` is exactly
+the anti-pattern this rule exists to prevent.
+
+Never `*-types.ts`. "Types" is a meta-word the `.ts` extension already
+implies; the name has to predict the contents. If you can't beat
+`-types`, the file isn't a real lump — split per type, or inline at use
+site.
+
+## Casing: `PascalCase` for types, `camelCase` for everything else
+
+Capitalize a name **only** when it is a type, or a value that *represents a
+type*. Everything else — functions, values, methods — is `camelCase`.
+
+A `Schema` is a runtime type, so this extends to schema helpers:
+
+- A **schema value that is a type** is `PascalCase`: the namespace schemas
+  `F32`, `Boolean`, `Guid`, `True` (each *is* a type's schema).
+- A **higher-order schema function that returns a new type-representing
+  schema** is a runtime **type constructor** — the value-level analogue of
+  `Readonly<T>` / `Partial<T>` — and is `PascalCase`: `Nullable(schema)`,
+  `Tuple(item, n)`, `SuccessResultSchema(v)`, `ProgressiveResultSchema(v, e)`.
+- Everything else stays `camelCase`, even when it touches schemas: functions
+  that **annotate the same type** (`withValidation`), **build from a spec**
+  (`fromArchetype`, `fromObjectProperties`, `fromStructProperties`),
+  **resolve/transform** (`getDynamicSchema`, `toVertexBufferLayout`), or hang
+  off a namespace (`Guid.create`, `FractionalIndex.between`).
+
+The test: *does calling it yield a new runtime type?* Yes → `PascalCase`
+constructor. No → `camelCase`.
+
+## Domain namespaces (for types you don't own)
+
+When utility functions operate on a platform or third-party type (e.g.
+`GPUDevice`, `GPUTexture`), use a **domain namespace** instead: a folder
+named after the concept, with a namespace export but *no type re-export*.
+
+```
+src/gpu/
+  gpu.ts       # `export * as GPU from "./public.js"` — no type alias
+  public.ts    # re-exports every public helper
+  <helper>.ts  # one declaration per file
+```
+
+```ts
+// gpu/gpu.ts
+export * as GPU from "./public.js";
+
+// gpu/public.ts
+export { createCubemap } from "./create-cubemap.js";
+export { cubeFaceView }  from "./cube-face-view.js";
+```
+
+Consumers import the namespace and get discoverability without shadowing
+the platform type:
+
+```ts
+import { GPU } from "@adobe/data-graphics";
+GPU.createCubemap(device, 256, "rgba16float");
+```
+
+**Name by purpose, not by the external type.** `GPU`, not `GPUDevice`.
+
+**Tree-shaking still works**: bundlers (Rollup/Rolldown) trace static
+property accesses (`GPU.createCubemap`) and exclude unused helpers.
+Dynamic access (`GPU[name]`) defeats this — avoid it.
+
+**When NOT to use a domain namespace**: if a utility is only useful as
+an internal implementation detail of a specific plugin (not callable by
+consumers), keep it private to that plugin's folder instead.
+
+## Single file pattern
+
+This pattern is ONLY allowed if there is only a single value export and every other export is just a type.
+As soon as there is more than one value type it MUST be promoted to the full namespace pattern.
+
+Example:
+
+    // core-database.ts
+
+    const coreDatabasePlugin = Database.Plugin.create({
+        components,
+        resources,
+        archetypes,
+    });
+
+    export type CoreDatabase = Database.Plugin.ToDatabase<typeof coreDatabasePlugin>;
+
+    export namespace CoreDatabase {
+        export const plugin = coreDatabasePlugin;
+        export type Store = Database.Plugin.ToStore<typeof coreDatabasePlugin>;
+    }

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

@@ -0,0 +1,170 @@
+---
+paths:
+  - '**/*plugin*'
+  - '**/*plugin*/**'
+---
+
+# Plugin modelling — model vs. system, authored vs. derived
+
+Each plugin has two orthogonal axes:
+
+1. **Authored** state — the user inserts / sets it. Designed by the human
+   architect.
+2. **Derived** state — a system produces it from other state. Implementation;
+   owned by the AI.
+
+The human's mental model of a project is the union of every plugin's
+**authored surface**. Systems and derived state are how the world updates
+and renders — read their interface contract, not their innards.
+
+## Two tiers of model plugins
+
+- **Core** — the primary record types every consumer reads. Small, fixed,
+  shared.
+- **Authoring abstractions** — higher-level intents (orbit, animation,
+  procedural shape, particle emitter, constraint, …) that systems expand
+  into core state. Open-ended; each project picks what it needs.
+
+A plugin almost never holds both authored and derived data the user cares
+about. If it appears to, the derived data is the *implementation* of the
+authoring abstraction.
+
+## File naming
+
+Each file whose primary export is a `Database.Plugin` (created or
+combined) ends in `-plugin.ts` — e.g. `node-plugin.ts`, `model-plugin.ts`,
+`pbr-core-plugin.ts`. The suffix is for discovery: cursor rules,
+codebase grep, and "find all plugins" tooling match `**/*-plugin.ts`
+without inspecting contents.
+
+The exported constant's name depends on whether the folder also hosts a
+type namespace:
+
+- **Pure-plugin folder** (no owned type) → export the concept name
+  itself, lowercase. `node-plugin.ts` exports `node`. Import sites read
+  `import { node } from "..."; Database.Plugin.combine(node, ...)`.
+- **Type + plugin folder** (folder hosts both an owned type and its
+  plugin) → the plugin file exports `plugin`, re-exported through the
+  type's namespace. `camera-plugin.ts` exports `plugin`; `camera/public.ts`
+  re-exports it; consumers reach it as `Camera.plugin`. One import gives
+  both the type and the plugin.
+
+Files with helper exports, value types, schemas, or shaders do **not**
+take the suffix — only plugin files.
+
+## Resources and archetypes as types
+
+Prefer **one resource per plugin**, of an owned type that the folder also
+hosts. `light/` has one `light` resource of type `Light`; `orbit/` has
+one `orbit` resource of type `Orbit`. Splitting a single coherent
+concept into siblings (`lightDirection`, `lightColor`, `ambientStrength`)
+duplicates the concept's identity at every read site.
+
+For each **archetype** the plugin declares, add a TypeScript type with
+the same name describing one row's authored shape. `Node` is the type
+for the `Node` archetype's row. The components stay separate per
+typed-buffer-column convention; the type names the bundle so consumers
+can declare `const node: Node` after a read.
+
+Both cases follow the same folder shape:
+
+```
+<concept>/
+  <concept>.ts          # type + namespace
+  public.ts             # re-exports plugin (and any helpers)
+  <concept>-plugin.ts   # exports `plugin`
+```
+
+Consumers reach the plugin as `Concept.plugin` and the type as
+`Concept`. Pure-plugin folders (no owned type) still export their
+plugin under a lowercase concept name — see "File naming" below.
+
+**Exceptions:**
+- Plugins whose resources have genuinely independent lifecycles
+  (`graphics` — `device`, `canvas`, `commandEncoder`, each set at
+  different times) keep them as separate resources. Consolidating
+  would force any one write to replace the whole struct.
+- Ephemeral implementation archetypes (e.g. `_PbrPrimitive`,
+  `_VisibleMaterial`) don't need a value type — consumers iterate
+  them by archetype, never construct one.
+
+## Shared conventions
+
+- **Uppercase identifier** = archetype. **Lowercase** = component or
+  resource. Disambiguated by where declared (archetype vs. component vs.
+  resource section of the data plugin).
+- **Entity references** are typed `EntityId`; field names drop the `Ref`
+  suffix — the type carries the signal.
+- **Implementation prefixes** (`pbr`, `ibl`, …) belong in code where they
+  disambiguate cross-plugin reuse. Drop them in the conceptual view.
+- **`_` prefix** = ephemeral / derived / not part of the data model.
+  Applies to **components, archetypes, and resources** in code — the
+  prefix makes "this is system-owned, not user-authored" visible at every
+  read site. The human ignores it when modelling; system-graph views
+  still display it. Does **not** apply to plugin names, system names, or
+  transactions — those are grouped by feature folder, and the folder
+  already communicates whether a plugin is authored surface or
+  implementation.
+- **Inline `: Type`** only on `_`-prefixed names. Persistent items get
+  their type from the data plugin where they're declared.
+- **Components use JSON schemas**, resources use `{ default: X as T }`.
+  Schemas (e.g. `Entity.schema`, `Mat4x4.schema`, `Boolean.schema`,
+  `{ type: "string" }`) enable typed-buffer column storage — the right
+  choice when a value is stored once per entity. Resources are a single
+  slot per database, so the runtime cost of typed storage isn't worth
+  it; the default-pattern is the convention there. Use the default
+  pattern on components *only* for runtime-only objects (GPU buffers,
+  bind groups, closures, complex JS objects with no schema).
+
+## Model plugin format
+
+Authored surface only — no derived state, no systems.
+
+```
+pluginName
+  components
+    fieldName:  Type
+    ...
+  resources
+    fieldName:  Type
+    ...
+  archetypes
+    ArchetypeName: [field, field, ...OtherArchetype]
+```
+
+- `...Other` composes another archetype's component list.
+- Shape comments (`// { … }`) stay on the same line; do not wrap.
+
+## System plugin format
+
+```
+systemName              // high-level summary
+  query: ArchetypeExpr [, ArchetypeExpr ...]   // omit if resource-only
+  read:
+    name                                       // persistent — type from data plugin
+    _name: Type                                // ephemeral — type inline
+  write:
+    name                                       // writes a component / resource
+    _Archetype                                 // creates new entities of this archetype
+    // free-text side effect                   // draw calls, network sends, …
+```
+
+- `read:` and `write:` are outlined one-per-line.
+- A system can have multiple independent queries; comma-separate them on
+  the `query:` line.
+
+## Query DSL
+
+- `Archetype` — entities matching the archetype.
+- `+component` — require this additional component.
+- `-component` — exclude entities that have it.
+- `Archetype+a-b+c` — left-to-right chain of `+` / `-`.
+- `Q1, Q2, ...` — multiple independent queries the system reads from.
+
+## Designing or discussing a plugin
+
+1. Write the authored surface (model format) **first**.
+2. Then each system as its own interface card with `query` / `read` /
+   `write`.
+3. The graph of `write:` → `read:` edges is the implementation; the union
+   of authored surfaces is the human's mental model.

package/.claude/rules/presentation.md

@@ -0,0 +1,83 @@
+---
+paths:
+  - 'packages/**/*presentation.ts'
+---
+
+# Presentation authoring
+
+A presentation is a pure function: data + action callbacks → renderable
+output. It has no `this`, no hooks, no subscriptions, no side effects,
+no component state, no business logic. The container element supplies
+everything it needs.
+
+This rule is framework-agnostic. The framework-specific bindings are in
+the table at the bottom.
+
+## Exports
+
+A presentation file exports exactly one symbol: `render` — the pure
+function. No types, styles, helpers, constants, or re-exports. If you
+need shared logic, keep it inside `render` as a local helper. If you
+need shared UI, that's another presentation.
+
+Consumers derive the props type via `Parameters<typeof render>[0]` —
+never declare or export a separate props type.
+
+## Action callbacks are actions, not events
+
+Use **verbNoun** form. The presentation invokes the callback when the
+user acts; it *is* the action, with no intermediary event to handle.
+
+```ts
+// ✅
+export function render({ dismiss, setLayout, createFolder }: {
+    dismiss: () => void;
+    setLayout: (layout: "grid" | "row") => void;
+    createFolder: (name: string) => void;
+}) { /* ... */ }
+
+// ❌
+export function render({ onDismiss, onLayoutChange, onCreate }: { ... }) {}
+```
+
+## Testing
+
+A pure `render(props)` is trivial to test — no DOM, no rendering, no
+component lifecycle. Pass stub props (no-op callbacks) and assert on the
+**declaration** it returns. Co-locate tests as `<name>-presentation.test.ts`.
+
+For Lit, wrap the result with `Template.from` (from `@adobe/data-lit`) and
+assert on the query, not on positional `.values` indices:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { Template } from "@adobe/data-lit";
+import { render } from "./todo-toolbar-presentation.js";
+
+it("wires the Add button and shows the stats", () => {
+    const addTodo = () => {};
+    const t = Template.from(render(props({ addTodo, totalCount: 3, completedCount: 1 })));
+    expect(t.has("<sp-textfield")).toBe(true);     // presence
+    expect(t.text).toContain("1 / 3 completed");   // static + primitive text
+    expect(t.values).toContain(addTodo);           // callback wired (identity, not values[3])
+});
+```
+
+`Template.Query` exposes `text`, `values`, `children`, `has(fragment)`, and
+`find(fragment)`. Prefer **identity** checks (`values` `toContain` a
+callback / `nothing` / a bound value) over positions. To exercise a
+callback, pull it from `values` and call it with a plain synthetic event —
+no mocks, no DOM.
+
+A presentation that only composes lazy child-element wrappers (or imports
+Spectrum components) needs a `// @vitest-environment jsdom` docblock so the
+module's custom-element side effects can load — the assertions still never
+render or touch the DOM. Presentations of native elements run under Node.
+
+## Framework bindings
+
+| Framework | Return type      | Common template imports             | Test assertion target                        |
+| --------- | ---------------- | ----------------------------------- | -------------------------------------------- |
+| Lit       | `TemplateResult` | `html`, `nothing`, `svg`, `repeat`  | `Template.from(...)` query (`@adobe/data-lit`) |
+| React     | `ReactNode`      | JSX runtime                         | render-to-string or virtual-DOM utility      |
+| Solid     | `JSX.Element`    | JSX runtime                         | render-to-string or virtual-DOM utility      |