@adobe/data-ai 0.10.23 → 0.10.25

package/.claude/rules/features/services/main-service/transactions.md

@@ -0,0 +1,61 @@
+---
+paths:
+  - '**/features/*/services/main-service/transaction-database/transactions/**/*.ts'
+---
+
+# database/transactions/ — atomic mutations
+
+> **Legacy state-based layout**, kept for existing features (`data/state/` + `services/main-service/`). New features use the layered layout in `../../index.md`.
+
+One mutation per file: a function taking the transaction store as its
+first argument and pure `data/` args, returning `void`. It reads and
+writes `t.resources` / entities; all its writes commit or roll back
+together.
+
+```ts
+import { PlayMoveArgs } from "../../../data/play-move-args/play-move-args.js";
+import type { CoreDatabase } from "../../core-database/core-database.js";
+
+export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
+    // guard, then mutate t.resources / entities / archetypes
+};
+```
+
+- Type the store parameter as `<Layer>.Store`: **`CoreDatabase.Store`** for a
+  transaction that reads/writes entities, resources, or archetypes (the common
+  case — all schema lives in `core-database`); **`IndexDatabase.Store`** the
+  moment it reads an index. A store *is* the transaction context: it carries the
+  index handles and the initiating `t.userId`. There is no separate
+  transaction-context type.
+- Keep transactions idempotent under replay where sync/P2P applies —
+  validate and silently return on illegal or out-of-turn input rather
+  than throwing.
+- Decisions come from pure `data/` helpers; the transaction only applies the
+  result — read the touched slice, call the `data/` transform, write the diff.
+- Keep transaction files **single-export** (the `transactions/` barrel is
+  `export *`-ed into the plugin facet, so a second export would pollute it).
+- **ECS-based feature (no `data/state/`):** there are no conformance cases, so
+  **every transaction carries its own unit test** — `Store.create(plugin)`, run the
+  transaction, assert the resulting resources/entities/archetypes. That test is the
+  direct substitute for the conformance oracle (see `../../index.md`, Two modes). The
+  bullet below applies only to **state-based** features.
+- **Conformance is wired once, centrally, and auto-paired** — not per-file. The
+  feature's single `conformance/conformance.test.ts` `Conformance.checkFeature(spec)`
+  call conforms transactions: it pulls them off **`plugin.transactions`** (the
+  registered facet), pairs each to the **same-named** `data/state` transition, and
+  conforms it — seed `fromState(before)`, apply, `Match.assert` `toState ≡ after`
+  (state only; service effects are asserted through the action). There is **no**
+  `define`/`conforms` adapter and **no** `covers` guard. A transaction taking
+  **entity ids** takes them under the transition's own arg key (`{ id }`); the runner
+  resolves each id the case's `args` schema marks via the id→entity map `fromState` returns. A
+  transaction with **no same-named transition** is infrastructure (`setInput`,
+  `setBounds`) or the drag UI op (`dragTodo`) or system-dispatched — it is simply
+  **skipped**, no guard needed. Don't add a per-item adapter for a renamed op; add a
+  thin same-named transaction instead (see `conformance.md`).
+- An `index.ts` barrel feeds the `transactions` plugin facet — so it must
+  re-export **only** the mutations. A read/query helper shared by several
+  transactions (`readShip`, `readBoard` — a `(t) => value` function) may live
+  beside them in `transactions/`, but keep it **out of the barrel**, or it gets
+  registered as a dispatchable transaction. (These are related helpers, so they
+  belong here, not in a separate folder — `global/cohesion.md`'s peer-level caution
+  doesn't apply.)

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

@@ -6,6 +6,8 @@ paths:
 
 # ui/ — user interface
 
+> **Legacy feature** (has `data/state/` or `services/main-service/`)? Its data and services follow the legacy rules; the ui rules here still apply.
+
 The top layer: UI that binds the feature's `MainService` database (`ecs/main-service.ts`)
 to what the user sees. It owns no business logic — it subscribes to state, hands it to
 a pure presentation, and wires user input to `service.actions.*`.

package/.claude/rules/service.md

@@ -6,7 +6,7 @@ paths:
 
 # Service authoring
 
-> Inside a feature, `features/services/index.md` governs the folder layout: a small service keeps `create.ts` and `create-fake.ts` flat beside the interface (the single-file exception below); one with helpers moves its implementation into a sub-folder. Database-bound factories in `ecs/services/` follow `features/ecs/services.md`.
+> Inside a feature, `features/services/index.md` covers the service layer; database-bound factories in `ecs/services/` follow `features/ecs/services.md`.
 
 Asynchronous data services. Live in the `services/` layer. Adhere to the namespace rule for type and function organization.
 
@@ -44,74 +44,26 @@ Compile-time check: `Assert<AsyncDataService.IsValid<ServiceInterface>>`.
 
 ---
 
-## Folder structure and cohesion
-
-**MUST NOT** place implementation files alongside the interface file. The `<name>-service/` folder MUST contain only the interface file and
-`public.ts`.
+## Folder structure
 
 ```
 services/<name>-service/
-  <name>-service.ts          ← interface + contract types; `export * as ServiceName from './public.js'` at bottom
-  public.ts                  ← re-exports factory (and other public exports) from the implementation sub-folder
-  <impl-name>/               ← REQUIRED sub-folder for all implementation files
-    create-<name>-service.ts ← factory function
-    *.ts                     ← helpers, utils, constants (implementation-private)
-    *.test.ts                ← tests live here alongside implementation
-```
-
-**Single-file exception**: a bare factory with no helpers, no utilities, and no constants MAY live as a flat file alongside the interface.
-The moment any additional implementation file is needed, the factory MUST move into a sub-folder.
-
-**Interface file** (`<name>-service.ts`) — interface declaration and types that define the public service contract. MUST NOT import from any
-implementation file or sub-folder. At the bottom of the file, exports the namespace: `export * as ServiceName from './public.js'`. This
-merges the interface type and the factory namespace under one identifier — callers type against the interface and invoke factory functions
-through the same name.
-
-**Separate types file at the interface level** — only permitted if it contains exclusively public-contract types (types that appear in the
-interface's method signatures or `Observe<>` generic arguments). Implementation-detail types — third-party API shapes, `window.*` global
-augmentations, internal utilities — MUST live inside the implementation sub-folder.
-
-**`*.test.ts` files MUST NOT appear at the interface folder level.** Every test file belongs inside the implementation sub-folder next to
-the code it tests; there is nothing at the interface level to test.
-
-**Implementation sub-folder** — all implementation logic including the factory, utilities, constants, helpers, and their tests. MUST NOT
-depend on the interface file's types via the `public.js` re-export; import directly from `<name>-service.js`.
-
-**public.ts** — MUST re-export the factory function and any other public exports from the implementation sub-folder. Does NOT re-export the
-interface — the interface is exported directly from `<name>-service.ts`.
-
-**No classes** — factory function or static plain object only. `this` bindings are brittle and block higher-order composition.
-
----
-
-## Factory export shape — `singletonFactory` + dual export
-
-Every service factory MUST be wrapped with `singletonFactory` from `factory-functions.js`. This guarantees one instance per argument tuple
-when the same factory is called multiple times, preventing duplicate subscriptions and torn state.
-
-Export **both** the raw `factory` and the singleton-wrapped `create`:
-
-```ts
-// <name>-service/<impl-name>/create-<name>-service.ts
-import { singletonFactory } from 'factory-functions.js';
-
-export const factory = (deps: Deps): NameService => {
-  // implementation
-};
-
-// `factory` — for test injection (bypasses the singleton cache; each test gets a fresh instance)
-// `create`  — for production use (singleton per deps-tuple)
-export const create = singletonFactory(factory);
-```
-
-`public.ts` re-exports both:
-
-```ts
-export { create, factory } from './<impl-name>/create-<name>-service.js';
+  <name>-service.ts   ← interface + contract types; `export * as ServiceName from './public.js'` at bottom
+  create.ts           ← the implementation factory (or a factory that throws when the app must inject it)
+  create-fake.ts      ← an inert fake with every method present
+  public.ts           ← re-exports `create` and `createFake`
 ```
 
-**Why:** Tests must create fresh instances without sharing a singleton cache. Production callers use `create`; tests that need isolation
-import `factory` directly.
+- **Interface file** (`<name>-service.ts`) — the interface and the types in its method
+  signatures. It never imports an implementation file. The namespace export at the
+  bottom merges the interface type and the factories under one name: callers type
+  against the interface and call `ServiceName.create`.
+- **An implementation that grows helpers** moves into a named sub-folder
+  (`create-<name>-service/` with its helpers and their tests); `public.ts` re-exports
+  its factory. Implementation-only types (third-party API shapes, `window.*`
+  augmentations) live there too, never in the interface file.
+- **No classes** — factory functions or plain objects only. `this` bindings are brittle
+  and block higher-order composition.
 
 ---
 
@@ -124,7 +76,7 @@ identifiers in any method signature, property name, or type parameter.
 
 ```ts
 interface SessionService extends Service {
-  readonly dunamis: DunamisSdk; // UI now knows Dunamis exists
+  readonly analyticsSdk: AnalyticsSdk; // UI now knows which SDK is used
 }
 ```
 
@@ -136,7 +88,7 @@ interface SessionService extends Service {
 }
 ```
 
-The interface is the contract between UI and data layers. If the underlying tool is swapped (Dunamis → another SDK, cookies → localStorage),
+The interface is the contract between UI and data layers. If the underlying tool is swapped (one SDK → another, cookies → localStorage),
 the interface must not change. Any leak of an internal tool name into the interface couples the UI to an implementation detail it must not
 know about.
 
@@ -146,21 +98,19 @@ know about.
 
 When creating or modifying a service:
 
-1. Place in `services/<name>-service/`.
+1. Place it in `services/<name>-service/`.
 2. Interface in `<name>-service.ts` — types only, extend `Service`, add `Assert<AsyncDataService.IsValid<>>`.
-3. All implementation files go inside a named sub-folder (e.g. `create-<name>-service/`).
+3. Add `create.ts`, `create-fake.ts` and `public.ts`; move the implementation into a sub-folder once it needs helpers.
 4. At the bottom of `<name>-service.ts`, add `export * as ServiceName from './public.js'`.
-5. In `public.ts`, re-export the factory (and any other public exports) from the implementation sub-folder.
-6. For front-end services: actions return void only; observables observe Data or Service only. For back-end services: functions return
+5. For front-end services: actions return void only; observables observe Data or Service only. For back-end services: functions return
    `Promise<Data>` or `AsyncGenerator<Data>`.
 
 ---
 
 ## Verify
 
-When any `src/**/services/**/*.ts` file is in the diff, confirm all three invariants:
+When any `services/**` file is in the diff, confirm:
 
-1. **Interface/implementation separation** — every `.ts` file added or modified in `<name>-service/` is either `<name>-service.ts`,
-   `public.ts`, or inside a named sub-folder. Any file at the root of the folder that is neither is a violation.
-2. **`public.ts` completeness** — `public.ts` re-exports the factory function (and any other public exports from the sub-folder).
-3. **Interface file purity** — `<name>-service.ts` contains no imports from implementation sub-folders.
+1. **Interface file purity** — `<name>-service.ts` imports no implementation file.
+2. **`public.ts` completeness** — it re-exports `create` and `createFake` (and any other public factory).
+3. **No implementation-only types in the interface** — they live with the implementation.

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adobe-data-ai",
-  "version": "0.10.23",
+  "version": "0.10.25",
   "description": "Architecture skills for @adobe/data — data-oriented modelling, archetype iteration, hot-path performance, and related conventions.",
   "author": {
     "name": "Adobe"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.10.23",
+  "version": "0.10.25",
   "description": "Cross-agent architecture skills for @adobe/data — installable as a Claude Code plugin or copied into any Agent-Skills-compatible agent (Cursor, Codex).",
   "type": "module",
   "private": false,
@@ -29,12 +29,12 @@
     "skills"
   ],
   "peerDependencies": {
-    "@adobe/data": "0.10.23"
+    "@adobe/data": "0.10.25"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.10.23"
+    "@adobe/data": "0.10.25"
   },
   "license": "MIT",
   "scripts": {

package/skills/build-actions/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create `ecs/actions/`: `action-database.ts` (extends the previous layer, adds `actions`
 from `./index.js`), one action per file, and a barrel. Every spec action has a
 same-named action. It awaits services and commits through at most one transaction

package/skills/build-app-entry/SKILL.md

@@ -5,6 +5,8 @@ input: app
 output: app
 ---
 
+A legacy feature (has `data/state/` or `services/main-service/`) exposes its `MainService` from `services/main-service/`; compose it from there.
+
 Create `src/app/`:
 
 - `schema.ts` — the composed plugin: the base feature's `MainService.plugin`, `imports`

package/skills/build-computed/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip if the spec has no derivations and the UI needs no derived values.
 
 Create `ecs/computed/`: `computed-database.ts` (extends the previous layer, adds

package/skills/build-core-database/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create:
 
 - `ecs/core/archetypes.ts` — `Database.archetypes(components, { … })`, spreading each

package/skills/build-data/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create the feature's `data/` layer: pure Data declarations, depending only on
 `@adobe/data` and the `data/` of features this one builds on.
 

package/skills/build-feature/SKILL.md

@@ -5,6 +5,9 @@ input: feature
 output: feature
 ---
 
+If the feature already has `data/state/` or `services/main-service/`, it uses the legacy
+state-based layout: extend it in place per those legacy rules; don't migrate it unless asked.
+
 /graph-execute
     /build-data
     /build-services

package/skills/build-indexes/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip if the feature needs no indexed lookups.
 
 Create `ecs/indexes/`: `index-database.ts` (extends `CoreDatabase`, adds `indexes` from

package/skills/build-service-database/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip if the feature has no services.
 
 Create `ecs/services/service-database.ts` (extends the previous layer), registering

package/skills/build-services/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip if the feature talks to nothing outside itself.
 
 Create one `services/<name>-service/` namespace per service: the interface (an async

package/skills/build-spec/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create the feature's `spec/` folder, the specification the ECS will be conformed to:
 
 - `state.ts` — `State` built from `data/` types (singletons named for resources,

package/skills/build-systems/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Skip unless the feature is real-time (games, simulations).
 
 Create `ecs/systems/system-database.ts`: `Database.Plugin.create({ extends:

package/skills/build-transactions/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create `ecs/transactions/`: `transaction-database.ts` (extends the previous layer, adds
 `transactions` from `./index.js`), one mutation per file, and a barrel. Type the store
 `CoreDatabase.Store`, or `IndexDatabase.Store` once it reads an index. Guard by entity

package/skills/build-ui/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? Extend it in place per the legacy rules; don't migrate unless asked.
+
 Create `ui/`: one folder per UI unit —
 `<name>/{<name>.ts (lazy wrapper), <name>-element.ts (container), <name>-presentation.ts (pure render), <name>.css.ts}`.
 The element subscribes to `MainService` state and calls `service.actions.*`; the

package/skills/review/SKILL.md

@@ -6,6 +6,8 @@ input: a path to built output (a layer, a feature, or a whole app)
 output: a review — OPTIMAL, or a list of issues each tagged code | skill | rule
 ---
 
+Check a legacy feature (has `data/state/` or `services/main-service/`) against the legacy rules; don't flag the layout itself.
+
 Read the files under the given path and assess them against the relevant `features/`
 rules (each layer's rule and the cross-cutting rules — `namespace`, `data-modelling`,
 `type-casts`, `cohesion`, …):

package/skills/structure/SKILL.md

@@ -3,5 +3,7 @@ name: structure
 description: Use when laying out or reasoning about a feature's file/folder structure and layer dependencies.
 ---
 
+Legacy feature (has `data/state/` or `services/main-service/`)? It keeps its state-based layout (the legacy rules); don't migrate unless asked.
+
 See `features/index.md` (and the per-folder `features/` rules) for how features are
 structured and layered.

package/.claude/rules/features/ui/binding-element.md

@@ -1,226 +0,0 @@
----
-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 (allowed 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 `hooks.md` for hook-first lifecycle).
-
-## `@property` allowlist
-
-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.actions.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:** `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 `hooks.md` and `features/ui/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 `features/ui/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.actions.updateThing({ value: normalized });
-    };
-    return presentation.render({ total: clamped, onSave });
-  }
-}
-```