@adobe/data-ai 0.9.84 → 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/data/state.md

@@ -10,6 +10,8 @@ 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.
 
+Every feature that has ECS resources or transactions owns a `State` — including
+a host whose aggregate is a single scalar (`{ playing: boolean }`) or even when there is no state in which case use `{}`. 
 ```ts
 // state.ts — the aggregate, plus the namespace of transforms/derivations.
 export type State = {

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

@@ -8,9 +8,11 @@ paths:
 The bridge that keeps the ecs implementation honest against the `data/` spec.
 **Test-only**: imported solely by `*.test.ts` and in no facet barrel, so it never
 enters the runtime bundle (test-support may import the test framework — it is not
-a runtime declaration). **Feature-level**: one projection per feature, reused by
-every transaction test and the system tick-loop test — don't nest it under
-`transaction-database/`.
+a runtime declaration). **Never call `fromState` / `toState` (or a shared
+clear-all + reinsert helper used only for that projection) from systems,
+transactions, or UI** — that is a full-store rewrite, not an O(1) ECS update.
+**Feature-level**: one projection per feature, reused by every transaction test
+and the system tick-loop test — don't nest it under `transaction-database/`.
 
 The property, per `{ before, args, after }` case:
 `toState(apply(fromState(before), args)) ≡ spec(before, args)`.

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
@@ -63,9 +64,8 @@ const plugin = Database.Plugin.create({
   HUD) are notified. Reserve direct `db.store` writes for the hot per-row paths
   (movement, aging) that run on every entity every frame and shouldn't pay
   per-entity transaction overhead.
-- **The step math lives in `data/`.** A system is the ecs wiring: it reads store
-  rows, calls a pure `data/` step/derive function, writes the result back — same
-  spec↔implementation discipline as transactions. No physics/game math inline.
+- **Optimize for execution speed in systems** if there are multiple items, then make sure we are using efficient store queries and reading/writing minimal data columns. If this is not hot path, then the simplified data functions can be used, but in hot paths we only consider data functions to be specification. (ie: only use them if it's clearly not a hot path or you cannot write anything more performant by directly using ecs store) 
+- **The step math may live in `data/`.** but only for non-hot path
 - **Iterate archetypes per `archetypes.md`.** Express selection with
   `queryArchetypes(include, { exclude })`; when a system destroys/migrates rows
   (bullets expiring, entities dying) iterate **tail → head** so hole-fills don't
@@ -96,8 +96,8 @@ const plugin = Database.Plugin.create({
 - Games or simulations with immediate mode rendering may want to store a session
   resource of the canvas and render to it within a system. @adobe/data-gpu provides
   example patterns for doing this.
-- All or simulation systems should be optimized for performance.
-  Avoid allocatin intermediate objects if possible, read directly from store.
+- All simulation systems should be optimized for performance.
+  Avoid allocating intermediate objects if possible; read/write columns directly if hot-path. You can use transactions if needed, for instance if we are writing non hot path things which we have other things observing. (Only transactions are observable, not direct writes)
 
 ## Driving the loop — the scheduler
 
@@ -131,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>`;
+};