@adobe/data 0.9.56 → 0.9.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data",
-  "version": "0.9.56",
+  "version": "0.9.58",
   "description": "Adobe data oriented programming library",
   "type": "module",
   "sideEffects": false,

package/references/data-lit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-lit",
-  "version": "0.9.56",
+  "version": "0.9.58",
   "description": "Adobe data Lit bindings - hooks, elements, decorators",
   "type": "module",
   "private": false,

package/references/data-lit/src/elements/application-element.ts

@@ -10,6 +10,15 @@ export class ApplicationElement<MainService extends Service> extends LitElement
   @property({ type: Object, reflect: false })
   service!: MainService;
 
+  // Defaults to `isService`: any Service in the ancestor chain is acceptable.
+  // Subclasses with a more specific MainService should override this with a
+  // narrower guard so unrelated services in the chain are skipped over. The
+  // cast is sound because callers that *don't* override are by definition
+  // accepting any Service as a valid MainService.
+  @property({ attribute: false })
+  typeGuard: (service: unknown) => service is MainService =
+    isService as (service: unknown) => service is MainService;
+
   constructor() {
     super();
     attachDecorator(this, 'render', withHooks);
@@ -27,9 +36,10 @@ export class ApplicationElement<MainService extends Service> extends LitElement
   }
 
   protected findAncestorService(): MainService | void {
+    const { typeGuard } = this;
     for (const element of iterateSelfAndAncestors(this)) {
       const { service } = element as Partial<ApplicationElement<MainService>>;
-      if (isService(service)) {
+      if (typeGuard(service)) {
         return service;
       }
     }

package/references/data-lit/src/elements/database-element.ts

@@ -4,12 +4,13 @@ import { LitElement } from 'lit';
 import { property } from 'lit/decorators.js';
 import { iterateSelfAndAncestors } from '../functions/index.js';
 import { Database } from '@adobe/data/ecs';
+import { UIService } from '@adobe/data/service';
 import { attachDecorator, withHooks } from '../index.js';
 
 export abstract class DatabaseElement<P extends Database.Plugin> extends LitElement {
 
   @property({ type: Object, reflect: false })
-  service!: Database.Plugin.ToDatabase<P>;
+  service!: UIService.FromService<Database.Plugin.ToDatabase<P>>;
 
   constructor() {
     super();
@@ -21,7 +22,7 @@ export abstract class DatabaseElement<P extends Database.Plugin> extends LitElem
   connectedCallback(): void {
     if (!this.service) {
       const service = this.findAncestorDatabase();
-      this.service = (service?.extend(this.plugin) ?? Database.create(this.plugin)) as unknown as Database.Plugin.ToDatabase<P>;
+      this.service = (service?.extend(this.plugin) ?? Database.create(this.plugin)) as unknown as UIService.FromService<Database.Plugin.ToDatabase<P>>;
     }
     super.connectedCallback();
   }

package/references/data-lit/src/elements/database-element.type-test.ts

@@ -0,0 +1,85 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * Compile-time tests proving that `DatabaseElement.service` exposes a
+ * UI-safe view of the underlying Database — every Database method that
+ * originally returned a non-`void`, non-`Observe` result has its return
+ * type rewritten to `void`, while Observe surfaces pass through unchanged.
+ *
+ * If `UIService.FromService` ever stops applying to the inferred
+ * `service` type, one or more of these assertions will fail at build time.
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import { Database } from "@adobe/data/ecs";
+import { Observe } from "@adobe/data/observe";
+import { UIService } from "@adobe/data/service";
+import { DatabaseElement } from "./database-element.js";
+
+const plugin = Database.Plugin.create({
+  resources: {
+    count: { default: 0 as number },
+  },
+  transactions: {
+    increment: (t) => {
+      t.resources.count = t.resources.count + 1;
+    },
+  },
+});
+
+class _CountElement extends DatabaseElement<typeof plugin> {
+  get plugin() {
+    return plugin;
+  }
+}
+
+type ServiceType = _CountElement["service"];
+type RawDatabase = Database.Plugin.ToDatabase<typeof plugin>;
+
+// 1. The exposed service type is the UIService-restricted view of the database.
+type _CheckRestricted = Assert<Equal<ServiceType, UIService.FromService<RawDatabase>>>;
+
+// 2. Observe surfaces survive the restriction.
+type _CheckResourceObserveSurvives = Assert<
+  Equal<ServiceType["observe"]["resources"]["count"], Observe<number>>
+>;
+type _CheckEnvelopeObserveSurvives = Assert<
+  Equal<ServiceType["observe"]["envelopes"], RawDatabase["observe"]["envelopes"]>
+>;
+
+// 3. `apply` raw return type is non-void; restriction rewrites it to void.
+type RawApply = RawDatabase["apply"];
+type RestrictedApply = ServiceType["apply"];
+type _CheckRawApplyIsNotVoid = Assert<NotEqual<ReturnType<RawApply>, void>>;
+type _CheckRestrictedApplyIsVoid = Assert<Equal<ReturnType<RestrictedApply>, void>>;
+type _CheckRestrictedApplyKeepsArgs = Assert<
+  Equal<Parameters<RestrictedApply>, Parameters<RawApply>>
+>;
+
+// 4. `toData` raw return is `unknown`; restriction rewrites to void.
+type _CheckRawToDataNotVoid = Assert<NotEqual<ReturnType<RawDatabase["toData"]>, void>>;
+type _CheckRestrictedToDataVoid = Assert<Equal<ReturnType<ServiceType["toData"]>, void>>;
+
+// 5. Already-void functions pass through unchanged.
+type _CheckResetStillVoid = Assert<Equal<ReturnType<ServiceType["reset"]>, void>>;
+type _CheckCancelStillVoid = Assert<Equal<ReturnType<ServiceType["cancel"]>, void>>;
+
+// 6. Transaction functions (nested under `transactions`) get their return
+//    rewritten to void by the same recursion. The plugin's `increment`
+//    happens to already be void, so we check the structure stays a function
+//    returning void after the restriction.
+type _CheckIncrementReturnsVoid = Assert<
+  Equal<ReturnType<ServiceType["transactions"]["increment"]>, void>
+>;
+
+// ----------------------------------------------------------------------------
+// Local helpers (kept inline so this file stays a self-contained type test).
+// ----------------------------------------------------------------------------
+
+type Assert<T extends true> = T;
+type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2)
+  ? true
+  : false;
+type NotEqual<X, Y> = Equal<X, Y> extends true ? false : true;

package/references/data-lit/src/hooks/index.ts

@@ -17,5 +17,7 @@ export * from "./with-hooks.js";
 export * from "./attach-decorator.js";
 export * from "./use-drag-transaction.js";
 export * from "./use-drag-observe.js";
+export * from "./use-drag-generator.js";
 export * from "./use-draggable.js";
 export * from "./use-updated.js";
+export * from "./use-pointer-observe.js";

package/references/data-lit/src/hooks/use-drag-generator.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Observe } from '@adobe/data/observe';
+import { DragObserveProps, DragState, useDragObserve } from './use-drag-observe.js';
+import { useEffect } from './use-effect.js';
+
+/**
+ * When a drag starts, invokes `callback` with an async generator that yields
+ * {@link DragState} values until the drag ends or is cancelled. Built on
+ * {@link useDragObserve}.
+ *
+ * The callback also receives the `PointerEvent` that triggered `'start'` —
+ * i.e. the `pointermove` whose cumulative distance first exceeded
+ * `minDragDistance`. Callers that need the initial `clientX` / `clientY`
+ * synchronously (before any transaction runs or any Lit re-render has flushed)
+ * can use this event without awaiting the generator.
+ *
+ * The generator pairs naturally with an ECS transaction that accepts an
+ * `AsyncArgsProvider`: feed each yielded `DragState` into a transient envelope
+ * by returning the desired transaction args from the generator, and the ECS
+ * (and any attached sync transport) replicates each intermediate state to
+ * peers. The transaction commits when the drag ends and is cancelled when the
+ * drag is cancelled.
+ */
+export function useDragGenerator(
+    props: DragObserveProps,
+    dependencies: unknown[],
+    callback: (drag: AsyncGenerator<DragState>, startEvent: PointerEvent) => void,
+) {
+    const dragObserve = useDragObserve(props, dependencies);
+
+    useEffect(() => {
+        return dragObserve(value => {
+            if (value.type === 'start') {
+                const generator = Observe.toAsyncGenerator(
+                    dragObserve,
+                    v => v.type === 'end' || v.type === 'cancel',
+                );
+                callback(generator, value.event!);
+            }
+        });
+    }, dependencies);
+}

package/references/data-lit/src/hooks/use-drag-observe.ts

@@ -11,6 +11,12 @@ export type DragObserveProps = Pick<
 >;
 export type DragStart = {
     readonly type: 'start' | 'cancel';
+    /**
+     * The `PointerEvent` whose cumulative drag distance first exceeded
+     * `minDragDistance`. Only present when `type === 'start'`. Useful for
+     * callers that need the originating `clientX`/`clientY` synchronously.
+     */
+    readonly event?: PointerEvent;
 };
 export type DragMove = {
     readonly type: 'move';
@@ -36,8 +42,8 @@ export function useDragObserve(props: DragObserveProps, dependencies: unknown[])
     useDraggable(element,
         {
             ...props,
-            onDragStart: _e => {
-                setDragState({ type: 'start' });
+            onDragStart: e => {
+                setDragState({ type: 'start', event: e });
             },
             onDrag: (_e, position, delta) => {
                 setDragState({

package/references/data-lit/src/hooks/use-pointer-observe.ts

@@ -0,0 +1,79 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Observe } from "@adobe/data/observe";
+import { Vec2 } from "@adobe/data/math";
+import { useElement } from "./use-element.js";
+import { useEffect } from "./use-effect.js";
+import { useMemo } from "./use-memo.js";
+
+/**
+ * Returns an `Observe<Vec2>` that fires on every `pointermove` over the host
+ * element. Coordinates are relative to the element's bounding box, in pixels.
+ *
+ * This is the primitive for **continuous** pointer tracking — presence
+ * indicators, live cursors, heat-maps, etc. It is intentionally simpler than
+ * `useDragObserve`: it emits without a drag start/end lifecycle.
+ *
+ * ### Driving a never-ending presence transaction
+ *
+ * Pair with `Observe.toAsyncGenerator` to feed a never-ending async-generator
+ * transaction. Each `yield` becomes a transient envelope that the sync
+ * service forwards as `kind: "transient"`. The reconciler's `(userId, id)`
+ * compound key replaces the previous sample, so each peer has at most one
+ * outstanding cursor sample at any time.
+ *
+ * ```ts
+ * const pointerPos = usePointerObserve([]);
+ *
+ * useEffect(() => {
+ *   const positions = Observe.toAsyncGenerator(pointerPos, () => false);
+ *
+ *   async function* presenceArgs() {
+ *     for await (const [px, py] of positions) {
+ *       const { width, height } = element.getBoundingClientRect();
+ *       if (!width || !height) continue;
+ *       yield { userId, x: px / width, y: py / height };
+ *     }
+ *   }
+ *
+ *   // The wrapper returns a Promise when invoked with a generator factory.
+ *   // It rejects when we `.throw()` on dispose; swallow that — we threw
+ *   // precisely so the wrapper would cancel the in-flight transient
+ *   // instead of promoting the last sample to a commit.
+ *   db.transactions.movePresence(presenceArgs).catch(() => undefined);
+ *
+ *   return () => {
+ *     void positions.throw(new Error("disposed")).catch(() => undefined);
+ *   };
+ * }, []);
+ * ```
+ *
+ * ### Why `() => false` as the `finished` predicate?
+ *
+ * `Observe.toAsyncGenerator` stops when `finished(value)` returns `true`.
+ * Passing `() => false` makes the generator run until `gen.throw()` (or
+ * `gen.return()`) is called from the effect cleanup — the correct lifetime
+ * for a presence stream.
+ */
+export function usePointerObserve(dependencies: unknown[]): Observe<Vec2> {
+    // useMemo ensures the same [observe, notify] pair is reused across renders
+    // as long as dependencies are stable — critical so subscribers registered
+    // in a sibling useEffect don't miss events fired between renders.
+    const [pos, setPos] = useMemo(
+        () => Observe.createEvent<Vec2>(),
+        dependencies,
+    );
+
+    const element = useElement();
+
+    useEffect(() => {
+        const handler = (e: PointerEvent) => {
+            const rect = element.getBoundingClientRect();
+            setPos([e.clientX - rect.left, e.clientY - rect.top]);
+        };
+        element.addEventListener("pointermove", handler);
+        return () => element.removeEventListener("pointermove", handler);
+    }, [element, setPos]);
+
+    return pos;
+}

package/references/data-lit-tictactoe/package.json

@@ -1,9 +1,12 @@
 {
   "name": "data-lit-tictactoe",
-  "version": "0.9.56",
+  "version": "0.9.58",
   "description": "Tic-Tac-Toe sample - Lit web components with @adobe/data-lit and AgenticService",
   "type": "module",
   "private": true,
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "scripts": {
     "build": "vite build",
     "dev": "vite",

package/references/data-lit-tictactoe/src/elements/tictactoe-app/tictactoe-app-element.ts

@@ -0,0 +1,23 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement } from "lit/decorators.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-app.css.js";
+import * as presentation from "./tictactoe-app-presentation.js";
+
+const tagName = "tictactoe-app";
+
+declare global {
+    interface HTMLElementTagNameMap {
+        [tagName]: TictactoeAppElement;
+    }
+}
+
+@customElement(tagName)
+export class TictactoeAppElement extends TictactoeElement {
+    static styles = styles;
+
+    render() {
+        return presentation.render();
+    }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-app/tictactoe-app-presentation.ts

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { html } from "lit";
+import { TictactoeBoard } from "../tictactoe-board/tictactoe-board.js";
+import { TictactoeHud } from "../tictactoe-hud/tictactoe-hud.js";
+
+export function render() {
+    return html`
+        ${TictactoeBoard()}
+        ${TictactoeHud()}
+    `;
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-app/tictactoe-app.ts

@@ -1,22 +1,18 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
-import { customElement } from "lit/decorators.js";
-import { html } from "lit";
-import { TictactoeElement } from "../../tictactoe-element.js";
-import { styles } from "./tictactoe-app.css.js";
-import "../tictactoe-board/tictactoe-board.js";
-import "../tictactoe-hud/tictactoe-hud.js";
+import { html, type TemplateResult } from "lit";
+import type { Database } from "@adobe/data/ecs";
+import type { tictactoePlugin } from "../../state/tictactoe-plugin.js";
 
-export const tagName = "tictactoe-app";
+type TictactoeService = Database.Plugin.ToDatabase<typeof tictactoePlugin>;
 
-@customElement(tagName)
-export class TictactoeApp extends TictactoeElement {
-  static styles = styles;
-
-  render() {
-    return html`
-      <tictactoe-board></tictactoe-board>
-      <tictactoe-hud></tictactoe-hud>
-    `;
-  }
-}
+/**
+ * Generic over `S` so callers may pass a database built from any plugin
+ * that extends `tictactoePlugin` (for example one that adds AI agents
+ * or peer presence). The element class itself is typed on the minimal
+ * `tictactoePlugin` surface and ignores the extra capabilities.
+ */
+export const Tictactoe = <S extends TictactoeService>(args: { service: S }): TemplateResult => {
+    void import("./tictactoe-app-element.js");
+    return html`<tictactoe-app .service=${args.service}></tictactoe-app>`;
+};

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board-element.ts

@@ -0,0 +1,23 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement } from "lit/decorators.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-board.css.js";
+import * as presentation from "./tictactoe-board-presentation.js";
+
+const tagName = "tictactoe-board";
+
+declare global {
+    interface HTMLElementTagNameMap {
+        [tagName]: TictactoeBoardElement;
+    }
+}
+
+@customElement(tagName)
+export class TictactoeBoardElement extends TictactoeElement {
+    static styles = styles;
+
+    render() {
+        return presentation.render();
+    }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board-presentation.ts

@@ -1,13 +1,12 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
 import { html } from "lit";
+import { TictactoeCell } from "../tictactoe-cell/tictactoe-cell.js";
 
 export function render() {
-  return html`
-    <div class="board">
-      ${[0, 1, 2, 3, 4, 5, 6, 7, 8].map(
-        (index) => html`<tictactoe-cell .index=${index}></tictactoe-cell>`,
-      )}
-    </div>
-  `;
+    return html`
+        <div class="board">
+            ${[0, 1, 2, 3, 4, 5, 6, 7, 8].map((index) => TictactoeCell({ index }))}
+        </div>
+    `;
 }

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board.ts

@@ -1,18 +1,8 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
-import { customElement } from "lit/decorators.js";
-import { TictactoeElement } from "../../tictactoe-element.js";
-import { styles } from "./tictactoe-board.css.js";
-import * as presentation from "./tictactoe-board-presentation.js";
-import "../tictactoe-cell/tictactoe-cell.js";
+import { html, type TemplateResult } from "lit";
 
-export const tagName = "tictactoe-board";
-
-@customElement(tagName)
-export class TictactoeBoard extends TictactoeElement {
-  static styles = styles;
-
-  render() {
-    return presentation.render();
-  }
-}
+export const TictactoeBoard = (): TemplateResult => {
+    void import("./tictactoe-board-element.js");
+    return html`<tictactoe-board></tictactoe-board>`;
+};

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell-element.ts

@@ -0,0 +1,45 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement, property } from "lit/decorators.js";
+import { useObservableValues } from "@adobe/data-lit";
+import { BoardState } from "../../types/board-state/board-state.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-cell.css.js";
+import * as presentation from "./tictactoe-cell-presentation.js";
+
+const tagName = "tictactoe-cell";
+
+declare global {
+    interface HTMLElementTagNameMap {
+        [tagName]: TictactoeCellElement;
+    }
+}
+
+@customElement(tagName)
+export class TictactoeCellElement extends TictactoeElement {
+    static styles = styles;
+
+    @property({ type: Number })
+    declare index: number;
+
+    render() {
+        const values = useObservableValues(
+            () => ({ board: this.service.observe.resources.board }),
+            [],
+        );
+
+        const board = values?.board ?? "         ";
+        const cell = BoardState.getCell(board, this.index);
+        const isWinning = BoardState.isCellWinning(board, this.index);
+        const isPlayable = BoardState.isCellPlayable(board, this.index);
+
+        return presentation.render({
+            cell,
+            isWinning,
+            isPlayable,
+            playMove: () => {
+                this.service.transactions.playMove({ index: this.index });
+            },
+        });
+    }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell-presentation.ts

@@ -1,6 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
 import { html } from "lit";
+import { PlayerMark } from "../../types/player-mark/player-mark.js";
 
 export function render(args: {
   cell: string;
@@ -9,7 +10,7 @@ export function render(args: {
   playMove: () => void;
 }) {
   const { cell, isWinning, isPlayable, playMove } = args;
-  const hasMark = cell === "X" || cell === "O";
+  const hasMark = PlayerMark.is(cell);
 
   return html`
     <div

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell.ts

@@ -1,41 +1,8 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
-import { customElement, property } from "lit/decorators.js";
-import { useObservableValues } from "@adobe/data-lit";
-import { BoardState } from "../../types/board-state/board-state.js";
-import { TictactoeElement } from "../../tictactoe-element.js";
-import { styles } from "./tictactoe-cell.css.js";
-import * as presentation from "./tictactoe-cell-presentation.js";
+import { html, type TemplateResult } from "lit";
 
-export const tagName = "tictactoe-cell";
-
-@customElement(tagName)
-export class TictactoeCell extends TictactoeElement {
-  static styles = styles;
-
-  @property({ type: Number })
-  declare index: number;
-
-  render() {
-    const values = useObservableValues(
-      () => ({
-        board: this.service.observe.resources.board,
-      }),
-      [],
-    );
-
-    const board = values?.board ?? "         ";
-    const cell = BoardState.getCell(board, this.index);
-    const isWinning = BoardState.isCellWinning(board, this.index);
-    const isPlayable = BoardState.isCellPlayable(board, this.index);
-
-    return presentation.render({
-      cell,
-      isWinning,
-      isPlayable,
-      playMove: () => {
-        this.service.transactions.playMove({ index: this.index });
-      },
-    });
-  }
-}
+export const TictactoeCell = (args: { index: number }): TemplateResult => {
+    void import("./tictactoe-cell-element.js");
+    return html`<tictactoe-cell .index=${args.index}></tictactoe-cell>`;
+};

package/references/data-lit-tictactoe/src/elements/tictactoe-hud/tictactoe-hud-element.ts

@@ -0,0 +1,57 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement } from "lit/decorators.js";
+import { useObservableValues } from "@adobe/data-lit";
+import { BoardState } from "../../types/board-state/board-state.js";
+import { PlayerMark } from "../../types/player-mark/player-mark.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-hud.css.js";
+import * as presentation from "./tictactoe-hud-presentation.js";
+
+const tagName = "tictactoe-hud";
+
+declare global {
+    interface HTMLElementTagNameMap {
+        [tagName]: TictactoeHudElement;
+    }
+}
+
+@customElement(tagName)
+export class TictactoeHudElement extends TictactoeElement {
+    static styles = styles;
+
+    render() {
+        const values = useObservableValues(
+            () => ({
+                board: this.service.observe.resources.board,
+                firstPlayer: this.service.observe.resources.firstPlayer,
+                xWins: this.service.observe.resources.xWins,
+                oWins: this.service.observe.resources.oWins,
+                draws: this.service.observe.resources.draws,
+            }),
+            [],
+        );
+
+        const board = values?.board ?? "         ";
+        const firstPlayer = values?.firstPlayer ?? PlayerMark.values[0];
+
+        const currentPlayer = BoardState.currentPlayer(board, firstPlayer);
+        const status = BoardState.deriveStatus(board);
+        const winner = BoardState.getWinner(board);
+
+        const statusText =
+            status === "won" && winner !== null
+                ? `${winner} wins!`
+                : status === "draw"
+                    ? "Draw!"
+                    : `${currentPlayer}'s turn`;
+
+        return presentation.render({
+            statusText,
+            xWins: values?.xWins ?? 0,
+            oWins: values?.oWins ?? 0,
+            draws: values?.draws ?? 0,
+            restartGame: () => this.service.transactions.restartGame(),
+        });
+    }
+}