@adobe/data-ai 0.9.86 → 0.9.87

package/.claude/rules/cohesion.md

@@ -1,7 +1,7 @@
 ---
 paths:
-  - 'packages/**/*.ts'
-  - 'packages/**/*.tsx'
+  - '**/*.ts'
+  - '**/*.tsx'
 ---
 
 # Cohesion — make related code share a name

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

@@ -1,4 +1,6 @@
 ---
+paths:
+  - '**/data/*.ts'
 ---
 
 # Data modelling — locality of knowledge

package/.claude/rules/ecs.md

@@ -0,0 +1,275 @@
+---
+paths:
+  - '**/*-plugin.ts'
+  - '**/*-plugin/**/*.ts'
+  - '**/*-database.ts'
+---
+
+# Database.Plugin authoring
+
+Plugins are created with `Database.Plugin.create()` from `@adobe/data/ecs`.
+
+## Property order (enforced at runtime)
+
+Properties **must** appear in this exact order. All are optional.
+
+| #   | Property       | Signature                              | Purpose                                   |
+| --- | -------------- | -------------------------------------- | ----------------------------------------- |
+| 1   | `imports`      | `Plugin`                               | Dep plugin: types usable, NOT re-exported |
+| 2   | `extends`      | `Plugin`                               | Base plugin to extend (types re-exported) |
+| 3   | `services`     | `(db) => ServiceInstance`              | Singleton service factories               |
+| 4   | `components`   | schema object                          | ECS component schemas                     |
+| 5   | `resources`    | `{ default: value as Type }`           | Global resource schemas                   |
+| 6   | `archetypes`   | `['comp1', 'comp2']`                   | Standard ECS archetypes                   |
+| 7   | `indexes`      | `{ key, order?, unique?, archetype? }` | Sorted/filtered entity indexes            |
+| 8   | `computed`     | `(db) => Observe<T>`                   | Computed observables                      |
+| 9   | `transactions` | `(store, payload) => void`             | Synchronous atomic mutations              |
+| 10  | `actions`      | `(db, payload) => T`                   | General functions                         |
+| 11  | `systems`      | `{ create: (db) => fn \| void }`       | Per-frame (60fps) or init-only            |
+
+**Wrong order throws at runtime.**
+
+---
+
+## Composition
+
+**Single extension:**
+
+```ts
+export const authPlugin = Database.Plugin.create({
+  extends: environmentPlugin,
+  services: {
+    auth: db => AuthService.createLazy({ services: db.services }),
+  },
+});
+```
+
+**Combine** — `extends` accepts only one plugin. For multiple, use `Database.Plugin.combine`:
+
+```ts
+export const generationPlugin = Database.Plugin.create({
+  extends: Database.Plugin.combine(aPlugin, bPlugin),
+  computed: { ... },
+});
+```
+
+**`imports` vs `extends`** — both make the dep's declarations usable in this plugin's factory bodies and merge it at runtime. The difference
+is the result type: `extends` re-exports the dep's types into this plugin's type; `imports` does NOT. Use `imports` for a dep whose types
+you don't want propagating downstream — it keeps the result type O(local), so the dep's type params (e.g. an index `IX`) never accumulate
+through a deep `combine` chain (the TS2589 fix). The runtime merge means no separate top-level `combine` is needed for the imported plugin.
+
+```ts
+export const consumerPlugin = Database.Plugin.create({
+  imports: indexesPlugin, // db.indexes usable here + registered at runtime; IX not re-exported
+  extends: corePlugin,
+  computed: { ... },
+});
+```
+
+**Final composition:**
+
+```ts
+export const appPlugin = Database.Plugin.combine(corePlugin, themePlugin, dataPlugin, authPlugin, uiPlugin, featurePlugin);
+export type AppPlugin = typeof appPlugin;
+export type AppDatabase = Database.Plugin.ToDatabase<AppPlugin>;
+```
+
+---
+
+## Data modeling example
+
+```ts
+import { Database } from '@adobe/data/ecs';
+import { Vec3, Vec4, F32 } from '@adobe/data/math';
+
+const particleDataPlugin = Database.Plugin.create({
+  components: {
+    position: Vec3.schema,
+    velocity: Vec3.schema,
+    color: Vec4.schema,
+    mass: F32.schema,
+  },
+  resources: {
+    gravity: { default: 9.8 as number },
+  },
+  archetypes: {
+    Particle: ['position', 'velocity', 'color', 'mass'],
+  },
+});
+```
+
+- **Components**: per-entity data. Use schema imports (`Vec3`, `Vec4`, `F32` from `@adobe/data/math`) or type namespaces for custom shapes.
+- **Resources**: global state. Use **only** `{ default: value as Type }`.
+- **Archetypes**: one per entity kind. List all components that kind requires.
+
+---
+
+## Property details
+
+### components
+
+Non-persistable values (e.g. HTML elements, DOM refs) must use `ephemeral: true` on the schema.
+
+```ts
+components: {
+  layout: Layout.schema,
+  layoutElement: { default: null as unknown as HTMLElement, ephemeral: true },
+},
+```
+
+### resources
+
+Use `as Type` to provide the compile-time type. Use `null as unknown as Type` for resources initialized later in a system initializer.
+
+```ts
+resources: {
+  themeColor: { default: 'dark' as ThemeColor },
+  connection: { default: null as unknown as WebSocket },
+},
+```
+
+### computed
+
+Factory returning `Observe<T>` or `(...args) => Observe<T>`. Receives full db.
+
+### transactions
+
+Synchronous, deterministic atomic mutations. Receive `store` and a payload.
+
+- `store.update(entity, data)` — update entity components
+- `store.resources.x = value` — mutate resources
+- `store.get(entity, 'component')` — read component value
+- `store.select(archetype.components, { where })` — query entities
+
+### actions
+
+UI components that call actions must never consume returned values — see `.claude/rules/binding-element.md` (Actions are fire-and-forget).
+
+**At most one transaction per action.** Multiple transactions in a single action corrupt the undo/redo stack.
+
+### systems
+
+`create` receives db and may optionally return a per-frame function (60fps) or just initialize values.
+
+---
+
+## Naming conventions
+
+| Item        | Convention                                            | Example                      |
+| ----------- | ----------------------------------------------------- | ---------------------------- |
+| File        | `*-plugin.ts` (kebab-case)                            | `layout-plugin.ts`           |
+| Export      | `*Plugin` (camelCase)                                 | `layoutPlugin`               |
+| System      | `plugin_name__system` (snake_case, double underscore) | `layout_plugin__system`      |
+| Init system | `plugin_name_initialize`                              | `ui_state_plugin_initialize` |
+
+---
+
+## Type utilities
+
+```ts
+export type MyDatabase = Database.Plugin.ToDatabase<typeof myPlugin>;
+export type MyStore = Database.Plugin.ToStore<typeof myPlugin>;
+```
+
+---
+
+## State minimalism
+
+Before adding any `resource`, `component`, or `computed` to a plugin, identify at least one concrete subscriber that reads it. State that
+nothing subscribes to is dead state — it occupies schema space, complicates serialization, and creates false surface area for future
+maintainers.
+
+**Before adding state, ask:**
+
+1. Which UI component, computed, or action reads this?
+2. Can a direct function call replace this entirely (avoiding a transaction that writes state only to read it back immediately)?
+3. Is this "tracking in case it's needed" — if yes, do not add it.
+
+**Computed vs. type utility:**
+
+When a derivation is a pure function of a single typed value with no observable subscription needed, prefer a **type utility function** over
+a computed state:
+
+```ts
+// WRONG — computed state when a type utility suffices
+computed: {
+  hasMinimumDuration: db => Observe.withMapData([db.resources.clip], clip => clip.duration >= 8);
+}
+
+// CORRECT — type utility; zero subscription overhead, testable in pure unit tests
+// types/clip/clip.ts
+export namespace Clip {
+  export const hasMinimumDuration = (clip: Clip): boolean => clip.duration >= 8;
+}
+// Usage: Clip.hasMinimumDuration(clip) — no observable, no subscription
+```
+
+Use a computed only when the result must be observable (i.e. UI needs to react when the underlying data changes). Use a type utility when
+the derivation is needed inline and does not require reactivity.
+
+---
+
+## Type safety
+
+Plugin code must be **fully and honestly typed**. No `as` / `as unknown as` casts (including on `db.get()` results), no `db: any` /
+`db: unknown` parameters, and no hand-written "surface" / "launder" types that approximate the real database or store and get cast into. We
+hold database-plugin typing to a strict standard: if the types fight you, the fix is to model the plugin correctly (or fix the framework) —
+never to cast around it.
+
+### Type every `db` / `t` / `store` with its real surface
+
+A factory, transaction, action, or system parameter must be the plugin's actual database or store type — or a type **derived** from it
+(`Database.Plugin.ToDatabase`, `ToStore`, `Database.Archetype.RowOf`). It must reflect what the framework actually passes. Do **not**
+declare a narrow structural subset and cast the real value into it. If the body needs services, resources, archetypes, or computeds, make
+them genuinely present on the plugin so the parameter type already carries them:
+
+- **`extends`** the right base so the store/db includes what you read and write — e.g. a transaction that mutates a resource archetype must
+  live on a plugin whose `extends` chain declares that archetype, or the store type won't have it.
+- **`imports`** a dependency plugin to use its surface inside your factory bodies _without_ re-exporting its types into your result type —
+  it stays out of downstream `combine` chains and is runtime-merged + identity-deduped.
+
+### Cross-plugin reads follow rules, not casts
+
+- A computed factory can read its **base** plugin's resolved computeds, but not a **sibling** computed declared in the same `computed: {}`
+  block (circular). To reuse a sibling's logic, either: (a) put the shared computed on a base plugin and `extends` it; or (b) author each
+  computed as a standalone exported factory `(db) => Observe<T>` and have the consumer import that factory and call it directly
+  (`otherComputed(db)`) instead of reaching for `db.computed.other`. A direct call builds a fresh `Observe` per call — wrap the factory in
+  `memoize` from `@adobe/data/cache` (keyed on `db`) if callers must share one instance.
+- An **inline** system/action body gets a contextually-typed `db`; a **standalone** exported system/action object does not, and cannot
+  import its own plugin's db type (circular). Prefer inline definitions where a typed `db` matters.
+
+### Brand domain types at the schema
+
+Model a branded value as a branded **scalar** (`number & Brand`) and brand it at the component/resource schema:
+`{ ...numberSchema, default: x as Branded }`. The stored shape equals the runtime shape, so the column types as the brand with **zero
+runtime cost** — reads and writes need no conversion.
+
+### We own `@adobe/data` — fix the root, don't cast
+
+If clean, strong typing is genuinely blocked by a framework limitation (the library's types cannot express something correctly), that is
+**not** license to cast. Surface it as a change request to `@adobe/data` and fix it at the source, then type the plugin honestly. The repo
+is maintained by **knye** — raise it with him.
+
+### Casts are a last resort, never a convenience
+
+Before any cast, you must have exhausted: the real db/store type, `extends` / `imports`, schema-level branding, and an `@adobe/data` change.
+If a cast is still unavoidable for a runtime invariant the compiler cannot see, funnel it through **one** named, documented boundary helper
+and back it with a compile-time drift guard (`Assert<Extends<…>>`) so it can never silently lie.
+
+## Service registration
+
+Services must be registered through `Database.Plugin.create({ services: { name: db => createService(db) } })`, not bolted on via
+`Object.assign`.
+
+---
+
+## Execute
+
+When creating or modifying a plugin:
+
+1. Verify property order matches the table (imports, extends, services, components, resources, archetypes, indexes, computed, transactions,
+   actions, systems).
+2. Use `extends` for single-parent, `Database.Plugin.combine()` for multiple peers.
+3. Ensure services only access `db.services` from extended plugins (not forward references).
+4. Export `type *Database = Database.Plugin.ToDatabase<typeof *Plugin>` when consumers need typed db access.
+5. Follow naming conventions for files, exports, and systems.

package/.claude/rules/element.md

@@ -1,6 +1,8 @@
 ---
 paths:
-  - 'packages/**/*-element.ts'
+  - '**/*-element.ts'
+  - '**/elements/**/*.ts'
+  - '**/ui/**/*.ts'
 ---
 
 # Container element authoring

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

@@ -1,6 +1,7 @@
 ---
 paths:
   - '**/features/*/ecs/**/systems/**/*.ts'
+  - '**/systems/*.ts'
 ---
 
 # database/systems/ — the real-time tick loop
@@ -130,3 +131,59 @@ an inline body grows too large — the schedule and registration still live inli
 `system-database/tick-loop.test.ts`. Test **selection/detection** logic (which
 entities collide, which pair resolves) separately, with seeded edge-case geometries
 — it's a system concern, not a transaction, and where subtle bugs hide.
+
+# 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/features/ui/binding-element.md

@@ -0,0 +1,226 @@
+---
+paths:
+  - 'src/**/*element*.ts'
+  - 'src/**/elements/**/*.ts'
+  - 'src/**/ui/**/*-element.ts'
+---
+
+# Binding elements
+
+Binding elements are thin wires between application state and the UI — not designed for unit-testability. Non-trivial logic doesn't belong
+here, it must be pushed into either the action/transaction layer or into presentations.
+
+## Scope
+
+This rule applies to **binding elements** — Lit elements that read state from a service via `useObservableValues`. If you are not using Lit then still try to adhere to a similar pattern to this with the same focus on separation of concerns and functional presentation if possible.
+The discriminator is the base class:
+
+- `ApplicationElement<T>` — from either `@adobe/data-lit` or `src/applications/application-element.ts`. Every app-level binding element
+  extends this (directly or transitively). Concrete app bases like `FooElement`, `VideoGenerationElement`, `ImageEditorElement`,
+  `StoryGenerationElement`, `ImageGenerationElement` are thin subclasses that bind a specific `MainService` type and inherit this contract.
+- `DatabaseElement<T>` — the lower-level `@adobe/data-lit` base used by apps with no intermediate `*Element` layer (e.g.
+  `HelloWorldElement`).
+
+Plain `LitElement` subclasses that expose their API through `@property` alone (shared UI primitives like `media-timeline`, `model-picker`,
+`toast-with-image`) are **not** binding elements. They don't subscribe to a service; their props are the entire contract. Out of scope for
+this rule.
+
+Presentation files (`*-presentation.ts`), CSS files (`*.css.ts`), tests (`*.test.ts`, `*.spec.ts`), and stories are also out of scope.
+
+## The shape
+
+A binding element is a thin wire between a service and a presentation. The class body contains:
+
+1. Optional static `styles` property definition
+2. Zero or more `@property` declarations (whitelisted below).
+3. One `render()` method whose body is: one `useObservableValues(...)` call, another lifecycle hook call (in rare cases), a null-guard, and
+   `return presentation.render({ ...values, ...callbacks })`.
+
+No other members. No `@state`. No private handler fields. No lifecycle methods (`connectedCallback`, `updated`, `firstUpdated`,
+`disconnectedCallback`) except on app-entrypoint classes where the lifecycle concern is app-boot shaped but cannot be expressed as a hook
+(see `.claude/rules/hooks.md` for hook-first lifecycle).
+
+## `@property` whitelist
+
+The allowed set depends on **class role**:
+
+- **App entrypoint classes** — the (typically empty-body) subclass of `ApplicationElement<T>` that binds a specific `MainService` type.
+  Examples: `VideoGenerationElement`, `HelloWorldElement`, `TodoElement`. These accept injected services and top-level inputs from the host
+  shell.
+- **Concrete binding elements** — classes that extend an app entrypoint (or another concrete binding) and render UI. Examples: `Hud`,
+  `FooRotationControlElement`, `CommunitySubmissionConnector`. These accept only:
+  - Entity-id-shaped locator props (`entityId`, `entityIds`, `trackId`) that identify _where_ to load this element's data from.
+  - Rare parent-forwarded flags passed straight to the presentation without branching on them (e.g. `highVolumeFlag` in `audio-view.ts`).
+    Prefer promoting the flag into a service computed.
+
+All other values come from the service.
+
+## Observed values must be raw reads
+
+Every expression inside `useObservableValues` is either a direct read of a service observable (`this.service.observe.*`) or a direct read of
+a computed (`this.service.computed.*`). No `.map`, `.filter`, `.reduce`, arithmetic, conditionals, or `Observe.withMap`-inline composition.
+
+If derivation is needed: ECS Database apps place it in a database computed (`plugins/computed`, read back as `this.service.computed.*`);
+non-ECS apps place it in a dependent-state service function (`dependent-state-service`). If it is used only by this element, define it
+locally in a sibling file and import it. Computed and dependent-state must use utilities from `Obsereve.*` rather than trying to call
+observable functions.
+
+**Bad - doesn't use utilities from `Obsereve.*`**
+
+```ts
+return notify => {
+  const unobserve = oValue(value => {
+    notify(value ** 2);
+  });
+  return unobserve;
+};
+```
+
+**Good - uses utilities from `Obsereve.*`**
+
+```ts
+return Observe.withMap(oValue => value ** 2);
+```
+
+## Callbacks are one-liners
+
+- Each callback passed to the presentation invokes a UI action with optional arguments or a transaction with optional arguments.
+- Callbacks must not encode domain knowledge, branch on state, or build complex shapes. Logic belongs in the UI action layer or transactions
+  layer.
+- UI action functions and transactions must be called only via `this.service`, they must never be imported directly.
+- Never consume the return value of a UI action or transaction call.
+- Simple argument transformations are allowed — arithmetic, negation, fixed arguments, simple ternaries that select an argument value.
+
+```ts
+render() {
+  return presentation.render({
+    // UI action call without parameters — good
+    saveProgress: this.service.actions.saveProgress,
+    // UI action call with fixed argument — good
+    setLandscape: () => this.service.actions.setOrientation('landscape'),
+    // UI action call with simple ternary — good
+    jump: (heroMode: boolean) => this.service.actions.move(heroMode ? 100 : 10),
+    // transaction call - good
+    play: this.service.transactions.playTrack
+  });
+}
+```
+
+## No derivation math in `render()`
+
+**Derivation math** is forbidden in `render()`. Simple argument assembly in callbacks is the only exception — see **Action callbacks are
+one-liners** above.
+
+## Lifecycle goes through hooks
+
+Any need for mount/unmount/update behavior routes through a hook. **Reuse order, one hook per file, presentation vs binding placement, and
+testing notes:** `.claude/rules/hooks.md`.
+
+Never inline lifecycle logic in the binding. App-entrypoint classes may override lifecycle methods when the concern is app-boot shaped
+(service wiring, ancestor lookup); even then, prefer a hook.
+
+Rare cases when an additional hook can be used in `render()`:
+
+- focus on element
+- scroll to element
+- clean up on un-mount
+- and other lifecycle-bound behaviour
+
+Use `useEffect` for cleanup on unmount rather than `disconnectedCallback`:
+
+```ts
+render() {
+  useEffect(() => {
+    return () => this.service.actions.someCleanup();
+  }, []); // empty array → runs cleanup on unmount only
+
+  const values = useObservableValues(() => ({ ... }));
+  if (!values) return nothing;
+  return presentation.render(values);
+}
+```
+
+In binding-elements `render()` doesn't need to be explicitly decorated with `withHooks()` because it's done implicitly in the
+`ApplicationElement` base class.
+
+## No timers, emitters, or broadcast channels
+
+- Never `setInterval`, `setTimeout`, or `requestAnimationFrame`.
+- Never `new EventEmitter`. Cross-element state flows through service observables.
+- Never `new BroadcastChannel`. Cross-tab concerns go through a dedicated service.
+
+## No direct database reads
+
+Never call `this.service.get()`, `this.service.read()`, `this.service.select()`, or any synchronous accessor. The service interface does not
+expose them by design; reaching for them means a missing computed.
+
+## Presentation contract
+
+A binding element imports a sibling `*-presentation.ts` file that exports exactly `render` (required) and optionally `unlocalized`. Nothing
+else — no types, no styles, no helpers. Consumers derive the props type via `Parameters<typeof render>[0]`. Presentation stays hook-free by
+default; element hooks live here or in shared modules per `.claude/rules/hooks.md` and `.claude/rules/presentation.md`.
+
+**For refactors whose stated scope does not include presentations**, the matching `*-presentation.ts` file must not change. Verify with
+`git diff --name-only | grep presentation`. If a scope-limited refactor requires a presentation signature change, stop and reconsider the
+binding-side helper — the scope fence exists because presentations are the public contract between binding and render output.
+
+Callback prop names use **verb** or **verbNoun** form. Never `on*` prefix. The binding-side variable matches the presentation prop name 1:1.
+See `.claude/rules/presentation.md` for full examples.
+
+## Size budget
+
+A compliant binding element file is small enough that the `render()` body fits on screen without scrolling. If it doesn't, a concern has not
+been extracted yet — find it.
+
+## Deletion test
+
+Delete everything except the class body. What remains should be: static styles assignment, property declarations, one
+`useObservableValues(...)` call, another lifecycle hook call (in rare cases), a null-guard, and one render call. Anything else is a
+violation.
+
+## Good examples (in-tree)
+
+- `src/applications/image-generation/elements/sub-navigation-panel/sub-navigation-panel.ts` — concrete binding element; one-liner action
+  callback
+- `src/applications/foo/elements/properties-panel/views/audio-view.ts` — entity-id-only + parent-forwarded flag
+- `src/applications/image-editor/elements/hud/hud.ts` — concrete binding element (extends `ImageEditorElement`); `useObservableValues` reads
+  a dependentState observable; forwards to presentation with spread.
+- `src/applications/video-generation/elements/commerce-coachmark/commerce-coachmark.ts` — localization-only binding; trivially small and
+  compliant.
+
+## Counter-example (do not land)
+
+```ts
+@customElement(tagName)
+export class BadControlElement extends FooElement {
+  @property({ attribute: false }) entityIds: readonly Entity[] = [];
+  @state() private _cachedSum = 0; // violation: @state
+  private _handleChange?: (e: Event) => void; // violation: private handler
+
+  connectedCallback() {
+    // violation: lifecycle override
+    super.connectedCallback();
+    this._handleChange = e => (this._cachedSum += Number((e.target as HTMLInputElement).value));
+  }
+
+  @withHooks // Redundant
+  render() {
+    const values = useObservableValues(() => ({
+      items: this.service.observe.select(/* ... */),
+      total: Observe.withMap(
+        // violation: logic in observed values
+        this.service.observe.select(/* ... */),
+        rows => rows.reduce((a, r) => a + r.duration, 0)
+      ),
+    }));
+    const clamped = Math.max(0, Math.min(100, values.total)); // violation: derivation in render
+    const onSave = (v: number) => {
+      // violation: logic in callback + onX name
+      const normalized = Math.round(v * 100) / 100;
+      if (!Number.isFinite(normalized)) return;
+      this.service.transactions.updateThing({ value: normalized });
+    };
+    return presentation.render({ total: clamped, onSave });
+  }
+}
+```

package/.claude/rules/features/ui/lazy-wrapper.md

@@ -0,0 +1,27 @@
+---
+paths:
+  - 'src/**/elements/**/*.ts'
+  - 'src/**/ui/**/*.ts'
+---
+
+# Lazy Wrapper
+
+A lazy element wrapper is a strongly typed function that emits a lit template and dynamically loads the actual element code to ensure no loading till first real usage.
+Consumers of this element DO NOT use the <todo-row...> markup, instead they import this lazy function and call it with `{TodoRow({...})}`.
+
+# Example from data-lit-todo
+
+# todo-row.ts
+import { html, type TemplateResult } from "lit";
+import type { Entity } from "@adobe/data/ecs";
+
+export const TodoRow = (args: {
+  entity: Entity;
+  index: number;
+}): TemplateResult => {
+  void import("./todo-row-element.js");
+  return html`<todo-row
+    .entity=${args.entity}
+    .index=${args.index}
+  ></todo-row>`;
+};

package/.claude/rules/features/ui/presentation-test.md

@@ -0,0 +1,38 @@
+---
+paths:
+  - '**/*presentation.test.ts'
+---
+
+## 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.