@adobe/data-ai 0.9.86 → 0.9.87

package/.claude/rules/observe.md

@@ -0,0 +1,183 @@
+---
+paths:
+  - '**/services/**/*.ts'
+  - '**/*-plugin.ts'
+  - '**/*-plugin/**/*.ts'
+  - '**/*dependent-state*.ts'
+  - '**/*dependent-state*/**/*.ts'
+---
+
+# Observe pattern
+
+`Observe<T>` from `@adobe/data/observe` — a subscription function: `(notify: (value: T) => void) => Unobserve`. Callback may be invoked
+synchronously or asynchronously, zero or more times. Returns `Unobserve` to stop observing.
+
+**Always use `Observe.*` helpers to create and manipulate observables. Never write raw subscriptions or manual notify wrappers** — the
+standard helpers cover every composition need and keep the code consistent.
+
+---
+
+## Creation helpers
+
+| Helper                               | Usage                                              |
+| ------------------------------------ | -------------------------------------------------- |
+| `Observe.fromConstant(value)`        | `Observe<T>` from a constant value                 |
+| `Observe.fromProperties({ a, b })`   | Combine named observables into `Observe<{ a, b }>` |
+| `Observe.fromArray([obs1, obs2])`    | Combine array of observables into `Observe<T[]>`   |
+| `Observe.fromPromise(() => Promise)` | Lazy; notifies once when promise resolves          |
+| `Observe.createState(initial?)`      | `[Observe<T>, (value: T) => void]` — mutable state |
+
+```ts
+const constant = Observe.fromConstant(42);
+const combined = Observe.fromProperties({ a: db.observe.resources.a, b: db.observe.resources.b });
+const [count, setCount] = Observe.createState(0);
+```
+
+---
+
+## Transformation helpers
+
+| Helper                              | Usage                                                        |
+| ----------------------------------- | ------------------------------------------------------------ |
+| `Observe.withMap(obs, fn)`          | Transform value; map from one type to another                |
+| `Observe.withFilter(obs, fn)`       | Transform or filter; return `undefined` to skip              |
+| `Observe.withDefault(default, obs)` | Use default when value is undefined                          |
+| `Observe.withLazy(() => obs)`       | Defer expensive observable creation until first subscription |
+| `Observe.withUnwrap(obs)`           | Flatten `Observe<Observe<T>>` to `Observe<T>`                |
+
+```ts
+const doubled = Observe.withMap(count, n => n * 2);
+const max = Observe.withFilter(Observe.fromProperties({ a, b }), ({ a, b }) => Math.max(a, b));
+const withFallback = Observe.withDefault('unknown', maybeName);
+```
+
+---
+
+## Conversion helpers
+
+| Helper                   | Usage                               |
+| ------------------------ | ----------------------------------- |
+| `Observe.toPromise(obs)` | Resolve with first value (one-shot) |
+
+`Observe.toPromise` is for services reading a current value — **never use it in UI elements**.
+
+---
+
+## ⛔ Antipattern: synchronous "peek"
+
+**Never read an observable's current value by subscribing and immediately unsubscribing.** The `notify` callback may fire asynchronously
+(auth state, network, derived chains), so the snapshot is stale or `undefined`.
+
+```ts
+// WRONG — only works if the observable happens to emit synchronously on subscribe
+let value: T | undefined;
+const unobserve = someObservable(v => {
+  value = v;
+});
+unobserve();
+// use `value`  ← undefined for any async-resolving observable
+```
+
+```ts
+// CORRECT — resolve the current value explicitly
+const value = await Observe.toPromise(someObservable);
+```
+
+A stored `unobserve` is **only** ever for deferred teardown (returned from an Effect, called on unmount/cleanup) — never to bookend a
+synchronous read. If a sync call site (e.g. a DOM event handler that must call `preventDefault()` before any `await`) needs the value, do
+the synchronous work first, then `void asyncHelper(...)` that awaits `Observe.toPromise`. In a Lit render path, read reactive values through
+`useObservableValues`, not `toPromise`.
+
+---
+
+## ⛔ Antipattern: `undefined` as an Observe data value
+
+`@adobe/data/observe` reserves `undefined` to mean **"no value has been emitted yet"** — it gates the synchronous initial emit in
+`Observe.createState`, `fromProperties`, and friends. A data value flowing through an Observe pipeline must use `null` for the absent case,
+**never** `undefined`.
+
+```ts
+// WRONG — Observe<X | undefined>
+const [projectId, setProjectId] = Observe.createState<ProjectId | undefined>(undefined);
+return Observe.withDefault(undefined, cloudSync.projectName);
+
+// CORRECT — Observe<X | null>
+const [projectId, setProjectId] = Observe.createState<ProjectId | null>(null);
+return Observe.withDefault<string | null>(null, cloudSync.projectName);
+```
+
+Why it bites:
+
+- `createState<T | undefined>(undefined)` does **not** fire on subscribe (the implementation treats `undefined` as "not yet set"), so
+  downstream `useObservableValues` callers wait forever for a value that never arrives.
+- `fromProperties` re-emits when an input flips `undefined → defined`, not when a value changes — using `undefined` as data corrupts the
+  dirty-tracking.
+- `null` JSON-stringifies across the wire; `undefined` silently disappears.
+
+When auditing new code, flag `Observe<… | undefined>`, `createState<… | undefined>`, `withDefault(undefined`, and `fromConstant(undefined)`
+— each should use `null`. (A plain function returning `undefined`, e.g. an early `return` from an async helper, is unrelated and fine.)
+
+---
+
+## ⛔ Antipattern: membership-only subscription for value reads (ECS)
+
+`db.observe.select(archetype.components)` fires **only when entities enter or leave the archetype** — i.e. on set-membership changes. It
+does **not** fire when a component value changes on an entity already in the set. If the callback reads component **values**, this
+subscription is almost always wrong: it emits once on load, then silently stops reacting when the user edits values (opacity slider,
+selection toggle, drag end). The derived state goes stale with no error — the hardest bug to catch.
+
+Pick the subscription by what the callback reads:
+
+| Callback needs                                                          | Use                                                       |
+| ----------------------------------------------------------------------- | --------------------------------------------------------- |
+| Entity **IDs** only ("how many items," "does this track have children") | `db.observe.select(archetype.components)`                 |
+| Component **values** (any `db.get(id, 'field')` in a map/filter)        | `Database.observeSelectDeep(db, [...fields] as const)`    |
+| A single UI element bound to one entity                                 | `db.observe.entity(id)` / `observe.entity(id, archetype)` |
+
+```ts
+// WRONG — reads values but only reacts to add/remove; value edits never re-run this
+Observe.withMap(db.observe.select(archetype.components), ids => ids.filter(id => (db.get(id, 'selectedByUsers') ?? []).includes(userId)));
+
+// CORRECT — value-tracking subscription; list exactly the fields read downstream
+const SELECTED_FIELDS = ['selectedByUsers'] as const; // hoist the tuple above the factory
+const rows$ = Database.observeSelectDeep(db, SELECTED_FIELDS);
+Observe.withMap(rows$, rows => rows.filter(r => r.selectedByUsers?.includes(userId)).map(r => r.id));
+```
+
+`observeSelectDeep` re-emits on **any** change to **any** listed component on **any** matched entity — so list only the fields actually
+read, and when the matched set is large pair it with a structural deduplicate downstream so identical-looking emissions don't propagate
+(`@adobe/data/observe`'s `withDeduplicate` is reference-equality only). `observeSelectDeep` from a UI element is banned — let each element
+observe its own entity (see `.claude/rules/ecs.md` and `.claude/rules/squirrel/ui-data-access.md`).
+
+---
+
+## Common patterns
+
+**Derived observable from service:**
+
+```ts
+export const isDevelopment = memoize((service: Pick<EnvironmentService, 'type'>) =>
+  Observe.withMap(service.type, type => type === 'development')
+);
+```
+
+**Computed from multiple resources:**
+
+```ts
+Observe.withFilter(Observe.fromProperties({ a: db.observe.resources.a, b: db.observe.resources.b }), ({ a, b }) => Math.max(a, b));
+```
+
+**Lazy creation:** `Observe.withLazy(() => expensiveObs)` — defers until first subscription.
+
+---
+
+## Execute
+
+When adding or using Observe:
+
+1. Use `Observe.fromConstant` for static values.
+2. Use `Observe.fromProperties` to combine multiple observables.
+3. Use `Observe.withFilter` when mapping and/or filtering.
+4. Use `Observe.createState` for mutable state with a setter.
+5. Use `Observe.withUnwrap` to flatten `Observe<Observe<T>>`.
+6. Call `unobserve()` when cleaning up (e.g. component unmount).

package/.claude/rules/react.md

@@ -0,0 +1,102 @@
+---
+paths:
+  - '**/*.tsx'
+---
+
+# React component authoring
+
+React components live in the `components/` layer. Consume Observe and void actions from plugins. Use `@adobe/data-react` for `useDatabase`,
+`useObservableValues`, and `DatabaseProvider`.
+
+---
+
+## useDatabase — single context
+
+Binding components **must** call `useDatabase` to obtain the main service context. Do **not** access any other React context. Additional
+contexts create a context waterfall and hurt performance. All other services and state are reachable from the database.
+
+---
+
+## Binding component vs presentation
+
+**Binding component** — the React component that:
+
+- Injects observed values via `useObservableValues`
+- Triggers re-render when those values change
+- Binds action callbacks to the presentation
+
+**Presentation** — a pure function (no hooks) that receives data and action callbacks as props and returns JSX. Keep reactive logic in the
+binding component; presentation stays pure.
+
+---
+
+## Props from parent
+
+**Do not** pass values from parent except when needed to identify which entity in the database to bind to.
+
+```tsx
+// Parent: passes entity so child knows which record to bind to
+{
+  values.sprites.map(entity => <Sprite key={entity} entity={entity} />);
+}
+
+// Child: uses entity prop to observe the right record
+function Sprite({ entity }: { entity: Entity }) {
+  const db = useDatabase();
+  const values = useObservableValues(() => ({ sprite: db.observe.entity(entity, db.archetypes.Sprite) }), [entity]);
+}
+```
+
+---
+
+## useObservableValues
+
+_Most_ binding components use a **single** `useObservableValues` call. Collect all observed values in one object. Use `Observe.withDefault`
+for values that may resolve slowly.
+
+```tsx
+function Counter() {
+  const db = useDatabase(counterPlugin);
+  const values = useObservableValues(() => ({
+    count: db.observe.resources.count,
+  }));
+  if (!values) return null;
+  return presentation.render({ ...values, increment: db.transactions.increment });
+}
+```
+
+---
+
+## Presentation exports
+
+Presentation files ONLY export `render` (and localization bundles where appropriate). Nothing else. If you need render args type externally,
+use `Parameters<typeof render>[0]`.
+
+---
+
+## Action callbacks (not events)
+
+Use **verb** or **verbNoun** names — never `on*` prefix. See `.claude/rules/presentation.md` for full examples.
+
+**Pass function references directly** when the signature matches; wrap in an arrow function only to supply arguments:
+
+```tsx
+increment: db.transactions.increment; // reference — no wrapper needed
+toggleSprite: () => db.transactions.toggleSpriteActive({ entity }); // args required — wrap
+```
+
+---
+
+## Execute
+
+When creating or modifying a React component:
+
+1. Call `useDatabase` for the main service context. Do not use any other React context.
+2. Split into binding component (reactive) and presentation (pure).
+3. Use a single `useObservableValues` in the binding component.
+4. Pass observed values and action callbacks to presentation. Pass function references directly when the signature matches; wrap only when
+   supplying arguments.
+5. Keep presentation pure — no hooks.
+6. Presentation exports only `render` (and localization bundles where appropriate).
+7. Add `*-presentation.test.tsx` for presentation when appropriate; do not unit test binding components.
+8. Never include business logic within binding components. Move into computed values or action handlers.

package/.claude/rules/service.md

@@ -0,0 +1,164 @@
+---
+paths:
+  - '**/services/**/*.ts'
+  - '**/*-service.ts'
+---
+
+# Service authoring
+
+Asynchronous data services. Live in the `services/` layer. Adhere to the namespace rule for type and function organization.
+
+**Data** = readonly JSON values or Blobs.
+
+---
+
+## Front-end vs back-end services
+
+**Front-end services** — called directly from UI components. Support unidirectional control flow.
+
+| Allowed                         | Not allowed                      |
+| ------------------------------- | -------------------------------- |
+| `Observe<Data>`                 | Promise or AsyncGenerator return |
+| Other services (sub-Services)   |                                  |
+| Void-returning action functions |                                  |
+
+**Back-end services** — usually stateless. Functions typically return `Promise<Data>` or `AsyncGenerator<Data>`. Not called directly from
+UI; front-end services call them.
+
+This separation keeps UI components on a strict unidirectional path: data down via void actions, data up via Observe.
+
+---
+
+## Front-end service constraints
+
+`Service` interfaces for UI consumption may only contain:
+
+- **`Observe<Data>`** — observable properties or factories
+- **Sub-Service**s — nested service interfaces
+- **Action functions** — zero or more `Data` arguments, return `void` only
+- **Factory functions** — create observables or sub-Services
+
+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`.
+
+```
+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';
+```
+
+**Why:** Tests must create fresh instances without sharing a singleton cache. Production callers use `create`; tests that need isolation
+import `factory` directly.
+
+---
+
+## Service interface cleanliness
+
+The `<name>-service.ts` interface MUST NOT reference internal implementation tools, third-party SDK names, or infrastructure system
+identifiers in any method signature, property name, or type parameter.
+
+**Wrong** — leaks an internal infrastructure name into the UI contract:
+
+```ts
+interface SessionService extends Service {
+  readonly dunamis: DunamisSdk; // UI now knows Dunamis exists
+}
+```
+
+**Correct** — surfaces only what UI needs, implementation-tool-agnostic:
+
+```ts
+interface SessionService extends Service {
+  readonly sessionId: Observe<string>;
+}
+```
+
+The interface is the contract between UI and data layers. If the underlying tool is swapped (Dunamis → another SDK, 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.
+
+---
+
+## Execute
+
+When creating or modifying a service:
+
+1. Place 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/`).
+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
+   `Promise<Data>` or `AsyncGenerator<Data>`.
+
+---
+
+## Verify
+
+When any `src/**/services/**/*.ts` file is in the diff, confirm all three invariants:
+
+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.

package/.claude/rules/type-casts.md

@@ -1,7 +1,7 @@
 ---
 paths:
-  - 'packages/**/*.ts'
-  - 'packages/**/*.tsx'
+  - '**/*.ts'
+  - '**/*.tsx'
 ---
 
 # Type casts — only two valid uses

package/.claude-plugin/plugin.json

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

package/README.md

@@ -76,5 +76,5 @@ This presumes you are already running the agent within the directory you want to
 
 ```
 Find the @adobe/data-ai package on npmjs and then install it in the current directory.
-Next use it's /build-application skill to build <promt here>
-```
+Next use it's /build-application skill to build <prompt here>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.86",
+  "version": "0.9.87",
   "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.9.86"
+    "@adobe/data": "0.9.87"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.9.86"
+    "@adobe/data": "0.9.87"
   },
   "license": "MIT",
   "scripts": {

package/.claude/rules/archetypes.md

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