@adobe/data-ai 0.9.86 → 0.9.88

package/.claude/rules/{presentation.md → features/ui/presentation.md}

@@ -1,6 +1,6 @@
 ---
 paths:
-  - 'packages/**/*presentation.ts'
+  - '**/*presentation.ts'
 ---
 
 # Presentation authoring
@@ -42,37 +42,7 @@ export function render({ onDismiss, onLayoutChange, onCreate }: { ... }) {}
 
 ## Testing
 
-A pure `render(props)` is trivial to test — no DOM, no rendering, no
-component lifecycle. Pass stub props (no-op callbacks) and assert on the
-**declaration** it returns. Co-locate tests as `<name>-presentation.test.ts`.
-
-For Lit, wrap the result with `Template.from` (from `@adobe/data-lit`) and
-assert on the query, not on positional `.values` indices:
-
-```ts
-import { describe, it, expect } from "vitest";
-import { Template } from "@adobe/data-lit";
-import { render } from "./todo-toolbar-presentation.js";
-
-it("wires the Add button and shows the stats", () => {
-    const addTodo = () => {};
-    const t = Template.from(render(props({ addTodo, totalCount: 3, completedCount: 1 })));
-    expect(t.has("<sp-textfield")).toBe(true);     // presence
-    expect(t.text).toContain("1 / 3 completed");   // static + primitive text
-    expect(t.values).toContain(addTodo);           // callback wired (identity, not values[3])
-});
-```
-
-`Template.Query` exposes `text`, `values`, `children`, `has(fragment)`, and
-`find(fragment)`. Prefer **identity** checks (`values` `toContain` a
-callback / `nothing` / a bound value) over positions. To exercise a
-callback, pull it from `values` and call it with a plain synthetic event —
-no mocks, no DOM.
-
-A presentation that only composes lazy child-element wrappers (or imports
-Spectrum components) needs a `// @vitest-environment jsdom` docblock so the
-module's custom-element side effects can load — the assertions still never
-render or touch the DOM. Presentations of native elements run under Node.
+@see ./presentation-test.md
 
 ## Framework bindings
 

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

@@ -1,7 +1,7 @@
 ---
 paths:
-  - 'packages/**/*.ts'
-  - 'packages/**/*.tsx'
+  - '**/*.ts'
+  - '**/*.tsx'
 ---
 
 # Pass functions by reference — don't wrap them

package/.claude/rules/hooks.md

@@ -0,0 +1,57 @@
+---
+paths:
+  - '**/use-*.ts'
+  - '**/hooks/**/*.ts'
+---
+
+# Element hooks (Lit / `@adobe/data-lit`)
+
+Hooks tie **element lifecycle** and **DOM** concerns to reactive updates. This rule covers **where** hooks live, **how** to name and split
+them, and **what** to reuse before writing something new.
+
+---
+
+## Where hooks belong
+
+| Location                                                                        | Role                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Binding element** (`ApplicationElement` / app `*Element` / `DatabaseElement`) | **Default home** for hooks: `useObservableValues`, refs, resize, visibility, keyboard, etc. Compute values here and pass **plain data + action callbacks** into `presentation.render(...)`.                    |
+| **Presentation** (`*-presentation.ts`)                                          | **Hook-free** so `render` stays a pure `props → TemplateResult` function. **Exception:** only when unavoidable for performance or platform constraints — document **why** a binding-level hook could not work. |
+| **Shared UI primitives** (plain `LitElement`, not a binding element)            | Hooks allowed when the primitive owns DOM behavior; still follow **one hook per file** and the reuse order below.                                                                                              |
+
+---
+
+## Reuse before inventing
+
+Search in this order before adding a new hook module:
+
+1. **`src/elements/hooks/`** — shared hooks for Studio / platform elements.
+2. **`@adobe/data-lit`** — framework-provided hooks and primitives.
+3. **Application-specific** — under `src/applications/<app>/…` when behavior is owned by that app.
+4. **Element-local** — `use-<concern>.ts` next to the element when behavior is specific to one component.
+
+---
+
+## One hook, one file
+
+- Each custom hook lives in **its own module** with a clear name (`use-element-size.ts`, `use-my-panel-keyboard.ts`).
+- Do **not** bundle unrelated hooks in one file.
+- Export the hook (and any minimal types its signature needs). Avoid dumping unrelated utilities into the same file.
+
+---
+
+## Encapsulation
+
+- A hook should own a **single concern**: e.g. "sync width to state", "subscribe to window resize", "focus prompt on open".
+- Prefer **narrow return values** (values + small set of callbacks) over mutating arbitrary element fields.
+
+---
+
+## Execute
+
+When adding or changing hook code:
+
+1. Confirm the hook cannot live on a **binding element** (or shared hook package) before putting it in a **presentation** file.
+2. Run the **reuse** search order above; extend an existing hook if the behavior is the same concern.
+3. Add or edit **one file per hook**; name with the `use-` prefix consistent with the rest of the repo.
+4. Keep **binding** `render()` thin — call hooks, then pass results into `presentation.render`.

package/.claude/rules/layout.md

@@ -0,0 +1,132 @@
+---
+paths:
+  - '**/*.css.ts'
+  - '**/*.css'
+  - '**/elements/**/*.ts'
+---
+
+# Layout and component types
+
+UI components are one of two types with no overlap. Every component is either terminal or layout.
+
+---
+
+## Terminal components
+
+- Render their own UI (buttons, inputs, cards, text, etc.)
+- Contain CSS for their appearance
+- **Never** contain any external margin
+
+Terminal components are the leaves of the component tree. They own their visual styling and content.
+
+---
+
+## Layout components
+
+- Do **not** render any UI themselves
+- Composed only of other layout or terminal components
+- Responsible for interior gaps between their children
+- **Never** contain any external margin
+- Should not need CSS 90% of the time or more — use the standard layout utility classes below.
+- Generally have no business logic and should never re-render — keeps re-renders confined to lower terminal levels
+
+**Exception:** Some layout components explicitly manage state (animating, showing/hiding tabs, accordions). Those will have logic and may
+re-render.
+
+---
+
+## Layout utility classes
+
+Define `--layout-gap`, `--layout-gutter`, and `--layout-padding` on `:root` (or the root element) with your spacing scale. In Lit, import
+the styles and include them in `export const styles` of the root element or shared base class.
+
+```css
+/* -- Direction --------------------------------------------------------- */
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--layout-gap);
+}
+.row {
+  display: flex;
+  flex-direction: row;
+  gap: var(--layout-gap);
+}
+.cluster {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: var(--layout-gap);
+}
+
+/* -- Gap overrides ----------------------------------------------------- */
+.gap-gutter {
+  gap: var(--layout-gutter);
+}
+.gap-padding {
+  gap: var(--layout-padding);
+}
+.gap-none {
+  gap: 0;
+}
+
+/* -- Inset (padding) --------------------------------------------------- */
+.inset {
+  padding: var(--layout-padding);
+}
+.inset-gutter {
+  padding: var(--layout-gutter);
+}
+.inset-gap {
+  padding: var(--layout-gap);
+}
+
+/* -- Alignment --------------------------------------------------------- */
+.center {
+  justify-content: center;
+  align-items: center;
+}
+.spread {
+  justify-content: space-between;
+}
+.align-center {
+  align-items: center;
+}
+.align-start {
+  align-items: flex-start;
+}
+.align-end {
+  align-items: flex-end;
+}
+
+/* -- Sizing (applied to children) -------------------------------------- */
+.fill {
+  flex: 1;
+}
+.fit {
+  flex: 0 0 auto;
+}
+```
+
+For custom spacing in terminal components, use `var(--layout-gap)`, `var(--layout-gutter)`, or `var(--layout-padding)` rather than hardcoded
+lengths.
+
+---
+
+## Why this split matters
+
+Layout components that rarely re-render are efficient. State changes and user interactions trigger updates at terminal levels; layout
+structure above stays stable. Avoid putting reactive logic in layout components unless the layout itself is dynamic (tabs, accordions,
+animations).
+
+---
+
+## Execute
+
+When creating or modifying UI components:
+
+1. Classify as terminal or layout. No overlap.
+2. Terminal: owns UI and CSS; never external margin.
+3. Layout: no own UI; only layout/terminal children; owns interior gaps; never external margin.
+4. Prefer standard layout tokens for layout components; avoid custom CSS when possible.
+5. Keep layout components free of business logic unless they explicitly manage layout state.

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

@@ -1,6 +1,6 @@
 ---
 paths:
-  - 'packages/**/ui/**/*.ts'
+  - '**/ui/**/*.ts'
 ---
 
 # Lazy Lit element pattern

package/.claude/rules/lit.md

@@ -0,0 +1,115 @@
+---
+paths:
+  - '**/ui/**/*.ts'
+  - '**/elements/**/*.ts'
+  - '**/*-element.ts'
+---
+
+# Lit element authoring
+
+Lit elements live in the `components/` layer per the structure rule. Consume Observe and void actions from plugins per the service rule.
+
+---
+
+## Extending DatabaseElement
+
+Binding elements extend `DatabaseElement<typeof myPlugin>` — either directly or via an intermediate base class. The required plugin must be
+specified in the generic.
+
+```ts
+// Direct
+export class HelloWorldElement extends DatabaseElement<typeof helloWorldPlugin> {
+  get plugin() {
+    return helloWorldPlugin;
+  }
+}
+
+// Indirect — base extends DatabaseElement, leaf specifies plugin
+export class LayoutElement<T extends MyApplicationPlugin = MyApplicationPlugin> extends CoreApplicationElement<T> {}
+export class ToolbarElement extends LayoutElement<typeof toolbarPlugin> {}
+```
+
+---
+
+## Binding element vs presentation
+
+**Binding element** — the Lit custom element 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 by default) that receives data and action callbacks as props and returns a `TemplateResult`.
+Keep reactive logic in the binding element; presentation stays pure.
+
+---
+
+## useObservableValues
+
+_Most_ binding elements use a **single** `useObservableValues` call. Collect all observed values in one object.
+
+**Observe only what you need** — the minimal values required for rendering. For values that may resolve slowly, wrap with
+`Observe.withDefault`.
+
+```ts
+render() {
+  const values = useObservableValues(() => ({
+    visible: this.service.computed.isViewVisible(name),
+    userProfile: this.service.services.authentication.userProfile,
+  }));
+  if (!values) return;
+  return presentation.render({ ...values, toggleView: () => this.service.transactions.setViewVisible({ name, visible: true }) });
+}
+```
+
+---
+
+## Presentation exports
+
+Presentation files ONLY export `render` (and `unlocalized` bundles where appropriate). Nothing else. If you need render args type
+externally, use `Parameters<typeof render>[0]`.
+
+**Styles:** Do not import or re-export Lit `CSSResult` from presentations. The binding element imports `*.css.ts` and sets `static styles`
+there.
+
+---
+
+## Action callbacks (not events)
+
+Use **verb** or **verbNoun** names — never `on*` prefix. See `.claude/rules/presentation.md` for full examples and rationale.
+
+---
+
+## Lit properties
+
+**Almost never** use `@property` on binding elements.
+
+**Exception:** Use properties ONLY when needed to bind to the correct entity in the database — e.g. `entity` for table rows, `layer` for
+view hosts. Multiple instances of the same element need a property to identify which entity they represent.
+
+---
+
+## Hooks
+
+Canonical rules (reuse order, one hook per file, binding vs presentation): `.claude/rules/hooks.md`.
+
+Use hooks from `src/elements/hooks/` and `@adobe/data-lit` instead of `connectedCallback`/`disconnectedCallback`. Use `useEffect` for
+setup/teardown, `useKeyboardEvent` for single key events.
+
+---
+
+## Execute
+
+When creating or modifying a Lit element:
+
+1. Extend `DatabaseElement<typeof myPlugin>` (directly or indirectly) with the required plugin specified.
+2. Split into binding element (reactive) and presentation (pure).
+3. Use a single `useObservableValues` in the binding element. Observe only minimal values; use `Observe.withDefault` for slow-resolving
+   values.
+4. Pass observed values and action callbacks to presentation.
+5. Keep presentation pure — no hooks (see `.claude/rules/hooks.md` for exceptions).
+6. Add `@property` only when entity binding requires it (multiple instances).
+7. Presentation exports only `render` (and localization bundles where appropriate). Binding element sets `static styles` from `*.css.ts`.
+8. Add `*-presentation.test.ts` for presentation when appropriate; do not unit test binding elements.
+9. Never include business logic within binding elements. Move into computed values or action handlers.
+10. Good binding elements should be extremely small.

package/.claude/rules/namespace.md

@@ -1,160 +1,118 @@
 ---
 paths:
-  - 'packages/**/src/**/*.ts'
+  - '**/*.ts'
 ---
 
 # Type namespace pattern
 
-Each type lives in its own folder. The folder's eponymous file is the only
-public import surface; a `<Type>` namespace re-exports every helper.
+Single import surface per type: `<type-name>/<type-name>.ts`. Schema in `-schema.ts`, namespace re-export from `public.js`. Types live in
+the `types/` layer.
 
-```
-src/types/<type-name>/
-  <type-name>.ts   # type alias + `export * as <Type> from "./public.js"`
-  schema.ts        # `export const schema = { ... } as const satisfies Schema`
-  public.ts        # re-exports every public helper
-  <helper>.ts      # one declaration per file, camelCase
-```
+## Authority
 
-## Example
+This rule defines the canonical pattern. **Follow this standard for all new and refactored type folders.** The codebase may contain legacy
+patterns (e.g., inline `export namespace` in shared files) that do not conform — do not copy those; follow this rule instead.
 
-```ts
-// types/log-level/schema.ts
-export const schema = { type: "string", enum: ["debug", "info", "warn", "error"] }
-    as const satisfies Schema;
-
-// types/log-level/log-level.ts
-import { Schema } from "@adobe/data/schema";
-import { schema } from "./schema.js";
-export type LogLevel = Schema.ToType<typeof schema>;
-export * as LogLevel from "./public.js";
-
-// types/log-level/public.ts
-export { schema } from "./schema.js";
-export { is } from "./is.js";          // when external code narrows broader input
-export { values } from "./values.js";  // when external code iterates the set
-```
+## Naming conventions
 
-Consumers import only `LogLevel` from `log-level/log-level.ts` and use it
-as both type and namespace (`LogLevel.is(x)`, `LogLevel.values`).
-
-## Rules
-
-- Never import `schema.ts` or `public.ts` from outside the folder.
-- Consumers use one import: `import { LogLevel } from "./log-level.js"`.
-  The same identifier serves as type *and* namespace — a separate
-  `import type` is unnecessary and produces a duplicate-identifier error.
-- Helper files use `import type` from the sibling `<type-name>.ts` to
-  avoid cycling through `public.ts`.
-- Add `is` / `values` / per-member descriptors only when a consumer
-  actually needs them — not preemptively. A consumer in a not-yet-built
-  higher layer counts: a presentational descriptor the `ui/` will need
-  (per-member glyphs, a keypad `values` list) may be authored with the
-  data type, but give it a one-line doc naming the intended consumer (as
-  `player-mark/mark-color.ts` does) so the need is recorded, not guessed.
-
-## Strict single public export per file
-
-**One public export per file** — this is strict, not a preference. A file
-that *declares* exports exactly one public symbol (private declarations
-inside it are fine and are tested through the public export). The reason is
-cohesion: when several declarations share one file, each pulls its own
-external imports to the top and the file becomes a jumble that belongs to no
-single concept. One declaration → one file → imports that are about that one
-thing.
-
-More than one public export in a file is allowed **only when explicitly
-approved on a per-file or per-file-type basis** — the deliberate, named
-patterns below, nothing else. There is no "shared imports" or "cohesive set"
-escape hatch: a folder of sibling pure functions over one type (e.g. the
-`vec3`/`vec4`/`mat4x4` math) is one function per file, collected by the
-folder's `public.ts` barrel — dozens of one-line files is the intended shape,
-not a reason to lump.
-
-- **Barrels** — `index.ts` and a namespace's `public.ts` *only* re-export
-  (`export … from "./…"`); they never declare. Many re-exports is their job.
-- **The eponymous namespace file** (`<type>.ts`) — the type alias plus
-  `export * as <Type> from "./public.js"` (a type and its namespace value).
-- **The single-file pattern** (below) — one value export plus type-only
-  exports, for a trivial namespace not worth a folder.
-- **`<format>-schema.ts`** — a borrowed data-format projection (plain
-  `interface`s), next to its parser/emitter.
-- **Explicit authoring-cohesion files** — where two exports are genuinely one
-  unit to author, e.g. a presentation's `render` plus a co-located fixture
-  bundle (`unlocalized`). Rare; the pair must truly belong together.
-
-Everything else is one-per-file. In particular, **ECS facet folders
-(`components/`, `resources/`, `archetypes/`, `indexes/`, …) are not exempt**:
-one component / resource / archetype / index per file, collected by the
-folder's `index.ts` barrel. Collapsing several into one `index.ts` is exactly
-the anti-pattern this rule exists to prevent.
-
-Never `*-types.ts`. "Types" is a meta-word the `.ts` extension already
-implies; the name has to predict the contents. If you can't beat
-`-types`, the file isn't a real lump — split per type, or inline at use
-site.
-
-## Casing: `PascalCase` for types, `camelCase` for everything else
-
-Capitalize a name **only** when it is a type, or a value that *represents a
-type*. Everything else — functions, values, methods — is `camelCase`.
-
-A `Schema` is a runtime type, so this extends to schema helpers:
-
-- A **schema value that is a type** is `PascalCase`: the namespace schemas
-  `F32`, `Boolean`, `Guid`, `True` (each *is* a type's schema).
-- A **higher-order schema function that returns a new type-representing
-  schema** is a runtime **type constructor** — the value-level analogue of
-  `Readonly<T>` / `Partial<T>` — and is `PascalCase`: `Nullable(schema)`,
-  `Tuple(item, n)`, `SuccessResultSchema(v)`, `ProgressiveResultSchema(v, e)`.
-- Everything else stays `camelCase`, even when it touches schemas: functions
-  that **annotate the same type** (`withValidation`), **build from a spec**
-  (`fromArchetype`, `fromObjectProperties`, `fromStructProperties`),
-  **resolve/transform** (`getDynamicSchema`, `toVertexBufferLayout`), or hang
-  off a namespace (`Guid.create`, `FractionalIndex.between`).
-
-The test: *does calling it yield a new runtime type?* Yes → `PascalCase`
-constructor. No → `camelCase`.
-
-## Domain namespaces (for types you don't own)
-
-When utility functions operate on a platform or third-party type (e.g.
-`GPUDevice`, `GPUTexture`), use a **domain namespace** instead: a folder
-named after the concept, with a namespace export but *no type re-export*.
+- Constants are **camelCase** (`flicksPerSecond`, not `FLICKS_PER_SECOND`) — strong team preference
+- Each function/type gets its own file matching its name
 
-```
-src/gpu/
-  gpu.ts       # `export * as GPU from "./public.js"` — no type alias
-  public.ts    # re-exports every public helper
-  <helper>.ts  # one declaration per file
-```
+## Constant types
+
+| Visibility | Definition                      |
+| ---------- | ------------------------------- |
+| private    | Single-file only, not exported  |
+| exported   | Sole export from eponymous file |
+| public     | Re-exported from public.ts      |
+| internal   | Exported, not in public.ts      |
+
+## Constraints
+
+- `<type-name>/<type-name>.ts` is the only public import surface
+- Export a single type alias: `export type <type-name> = <type>` (or `export type * from "./<type-name>-types.js"` when the type lives in a
+  separate file)
+- Schema-based types: schema in `<type-name>-schema.ts`, named `schema` (not `<type-name>Schema`), derive with
+  `Schema.ToType<typeof schema>`
+- Export namespace: `export * as <type-name> from "./public.js"`
+- In public.ts, re-export every public constant file
+- Filenames map deterministically to single export:
+  - `foo.ts` → `export type Foo = ...`
+  - `do-bar.ts` → `export function doBar() { }`
+  - DO NOT append other suffixes like `-type` etc.
+- Function files: name by purpose only (e.g., `add.ts`, `sub.ts`). **Do not prefix** with the type name — the folder provides the namespace
+  context.
+
+## Anti-patterns (do not copy)
+
+- **`export namespace <TypeName> { ... }`** — Use `export * as <TypeName> from "./public.js"` instead.
+- **Prefixing function files with the type name** (e.g., `vec2-add.ts`) — Use `add.ts`; the folder provides context.
+- **Importing from `public.js` or `-schema.js`** outside the type folder — Consumers must import only from `<type-name>/<type-name>.ts`.
+
+## Consumers
+
+**Never:**
+
+- Import from `public.js` outside the type namespace folder
+- Import from `<type-name>-schema.js` outside the type namespace folder
+
+**Do:**
+
+- `import { Volume } from "../../types/volume/volume.js"`
+- For schema: `import { PlayerMark } from "../../types/player-mark/player-mark.js"`, then `PlayerMark.schema`
+
+## Schema pattern example
 
 ```ts
-// gpu/gpu.ts
-export * as GPU from "./public.js";
+// src/types/player-mark/player-mark-schema.ts
+export const schema = { enum: ['X', 'O'] } as const;
+
+// src/types/player-mark/public.ts
+export { schema } from './player-mark-schema.js';
 
-// gpu/public.ts
-export { createCubemap } from "./create-cubemap.js";
-export { cubeFaceView }  from "./cube-face-view.js";
+// src/types/player-mark/player-mark.ts
+import { Schema } from '@adobe/data/schema';
+import { schema } from './player-mark-schema.js';
+export type PlayerMark = Schema.ToType<typeof schema>;
+export * as PlayerMark from './public.js';
 ```
 
-Consumers import the namespace and get discoverability without shadowing
-the platform type:
+## Example: `Point` type refactor
+
+Starting file `src/types/point.ts`:
 
 ```ts
-import { GPU } from "@adobe/data-graphics";
-GPU.createCubemap(device, 256, "rgba16float");
+export type Point = { x: number; y: number };
+export const length = ({ x, y }: Point) => Math.hypot(x, y);
+export const add = ({ x: x1, y: y1 }: Point, { x: x2, y: y2 }: Point): Point => ({ x: x1 + x2, y: y1 + y2 });
 ```
 
-**Name by purpose, not by the external type.** `GPU`, not `GPUDevice`.
+After applying the namespace pattern:
+
+```ts
+// src/types/point/point.ts
+export type Point = { x: number; y: number };
+export * as Point from './public.js';
+
+// src/types/point/public.ts
+export * from './length.js';
+export * from './add.js';
+
+// src/types/point/length.ts
+export const length = ({ x, y }: Point) => Math.hypot(x, y);
+
+// src/types/point/add.ts
+export const add = ({ x: x1, y: y1 }: Point, { x: x2, y: y2 }: Point): Point => ({ x: x1 + x2, y: y1 + y2 });
+```
 
-**Tree-shaking still works**: bundlers (Rollup/Rolldown) trace static
-property accesses (`GPU.createCubemap`) and exclude unused helpers.
-Dynamic access (`GPU[name]`) defeats this — avoid it.
+## Execute
 
-**When NOT to use a domain namespace**: if a utility is only useful as
-an internal implementation detail of a specific plugin (not callable by
-consumers), keep it private to that plugin's folder instead.
+1. **Follow this rule** — Do not copy patterns from existing code; apply this standard.
+2. Identify constants in the current file.
+3. Extract them into the standard pattern.
+4. Identify all consumers of public namespaces.
+5. Check each consumer: ensure imports use `<type-name>.ts` only, never public.js or -schema.js.
+6. Ensure unit tests exist per function file, splitting as needed.
 
 ## Single file pattern