@adobe/data 0.9.82 → 0.9.84

package/references/data-lit-tictactoe/src/features/main/ecs/conformance/expect-conforms.ts

@@ -0,0 +1,42 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { it } from "vitest";
+import type { State } from "../../data/state/state.js";
+import type { ConformanceCase } from "../../data/state/conformance-case.js";
+import { expectStateMatches } from "../../data/state/expect-state-matches.js";
+import type { CoreDatabase } from "../core-database/core-database.js";
+import { createStore } from "./create-store.js";
+import { fromState } from "./from-state.js";
+import { toState } from "./to-state.js";
+
+// The conformance runner, bound to THIS feature's projection (`fromState` /
+// `toState`). For each case it proves the one conformance property
+//
+//   toState(apply(fromState(before), args)) ≡ spec(before, args)
+//
+// in two asserted halves:
+//   1. `spec(before, args) ≡ after` — keeps the shared case honest (a
+//      mis-authored `after` is caught here, independent of the ecs path).
+//   2. seed `fromState(before)` → run the caller's `apply` → `toState ≡ after`
+//      — the ecs implementation reproduces the pure transform.
+//
+// `apply` receives the seeded writable store and calls the raw transaction
+// function directly (a transaction is `(store, args) => void`, so no `Database`
+// is involved). tictactoe's transactions take plain data args (a board index,
+// or nothing), so no entity resolution is needed in `apply`. Entity collections
+// compare as multisets; scalars and resources exactly (see `expectStateMatches`).
+export const expectConforms = <Args>(config: {
+  readonly cases: readonly ConformanceCase<Args>[];
+  readonly spec: (before: State, args: Args) => State;
+  readonly apply: (store: CoreDatabase.Store, args: Args) => void;
+}): void => {
+  for (const testCase of config.cases) {
+    it(testCase.name, () => {
+      expectStateMatches(config.spec(testCase.before, testCase.args), testCase.after);
+
+      const store = createStore();
+      fromState(store, testCase.before);
+      config.apply(store, testCase.args);
+      expectStateMatches(toState(store), testCase.after);
+    });
+  }
+};

package/references/data-lit-tictactoe/src/features/main/ecs/conformance/from-state.ts

@@ -0,0 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { State } from "../../data/state/state.js";
+import { PlayerMark } from "../../data/player-mark/player-mark.js";
+import type { CoreDatabase } from "../core-database/core-database.js";
+
+// Seed a store to exactly match a `data/` `State`: clear every placed mark, set
+// the scalar resources, then insert one PlacedMark entity per occupied board
+// cell. The inverse of `toState`. Test-only — the bridge that lets an ecs
+// mutation be checked against the pure transform it stands for (see
+// `expect-conforms.ts`).
+//
+// Clearing iterates tail→head so each delete is from the tail (no hole-fill
+// shift). The board string carries the marks (tictactoe stores each mark as an
+// entity), so `PlayerMark.is` narrows each cell and skips the blanks.
+export const fromState = (store: CoreDatabase.Store, state: State): void => {
+  for (const arch of store.queryArchetypes(store.archetypes.PlacedMark.components)) {
+    for (let row = arch.rowCount - 1; row >= 0; row--) {
+      store.delete(arch.columns.id.get(row));
+    }
+  }
+  store.resources.firstPlayer = state.firstPlayer;
+  store.resources.xWins = state.xWins;
+  store.resources.oWins = state.oWins;
+  store.resources.draws = state.draws;
+  for (let index = 0; index < state.board.length; index++) {
+    const cell = state.board[index];
+    if (PlayerMark.is(cell)) {
+      store.archetypes.PlacedMark.insert({ mark: cell, index });
+    }
+  }
+};

package/references/data-lit-tictactoe/src/features/main/ecs/conformance/projection.test.ts

@@ -0,0 +1,38 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Guards the projection itself. `fromState` and `toState` are the bridge every
+// transaction conformance test trusts; a symmetric bug in the pair (e.g. both
+// dropping the same field) would cancel out and mask a real ecs defect. This
+// identity test — `toState(fromState(s)) ≡ s` over representative states —
+// proves the projection round-trips faithfully on its own.
+import { describe, it } from "vitest";
+import type { State } from "../../data/state/state.js";
+import { expectStateMatches } from "../../data/state/expect-state-matches.js";
+import { createStore } from "./create-store.js";
+import { fromState } from "./from-state.js";
+import { toState } from "./to-state.js";
+
+const states: readonly { readonly name: string; readonly state: State }[] = [
+  {
+    name: "a full board with non-zero counters",
+    state: { board: "XOXXOOOXX", firstPlayer: "O", xWins: 3, oWins: 2, draws: 1 },
+  },
+  {
+    name: "an empty board (just the resources)",
+    state: { board: "         ", firstPlayer: "X", xWins: 0, oWins: 0, draws: 0 },
+  },
+  {
+    name: "a game in progress",
+    state: { board: "X O X    ", firstPlayer: "O", xWins: 1, oWins: 0, draws: 0 },
+  },
+];
+
+describe("ecs/conformance projection round-trips (toState ∘ fromState ≡ identity)", () => {
+  for (const { name, state } of states) {
+    it(name, () => {
+      const store = createStore();
+      fromState(store, state);
+      expectStateMatches(toState(store), state);
+    });
+  }
+});

package/references/data-lit-tictactoe/src/features/main/ecs/conformance/to-state.ts

@@ -0,0 +1,30 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { State } from "../../data/state/state.js";
+import { BoardState } from "../../data/board-state/board-state.js";
+import type { PlacedMark } from "../../data/placed-mark/placed-mark.js";
+import type { CoreDatabase } from "../core-database/core-database.js";
+
+// Read a store back into a `data/` `State` — the inverse of `fromState`. The
+// placed marks are read through the PlacedMark archetype's full component set
+// (not an incidental single column) and folded into the compact board string,
+// then joined with the scalar resources. Test-only.
+const readBoard = (store: CoreDatabase.Store): BoardState => {
+  const marks: PlacedMark[] = [];
+  for (const arch of store.queryArchetypes(store.archetypes.PlacedMark.components)) {
+    for (let row = 0; row < arch.rowCount; row++) {
+      marks.push({
+        mark: arch.columns.mark.get(row),
+        index: arch.columns.index.get(row),
+      });
+    }
+  }
+  return BoardState.fromMarks(marks);
+};
+
+export const toState = (store: CoreDatabase.Store): State => ({
+  board: readBoard(store),
+  firstPlayer: store.resources.firstPlayer,
+  xWins: store.resources.xWins,
+  oWins: store.resources.oWins,
+  draws: store.resources.draws,
+});

package/references/data-lit-tictactoe/src/features/main/ecs/core-database/archetypes.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { Schema } from "@adobe/data/schema";
+import type { Assert, Equal } from "@adobe/data/types";
+import type { PlacedMark as PlacedMarkRow } from "../../data/placed-mark/placed-mark.js";
+import { components } from "./components.js";
+
+export const archetypes = Database.archetypes(components, {
+  PlacedMark: ["mark", "index"],
+});
+
+// Drift guard: the archetype's inferred row shape must equal the PlacedMark
+// data type. Fails to compile if the component set and the type diverge.
+const placedMarkSchema = Schema.fromArchetype(components, archetypes.PlacedMark);
+type _PlacedMarkMatches = Assert<
+  Equal<Schema.ToType<typeof placedMarkSchema>, PlacedMarkRow>
+>;

package/references/data-lit-tictactoe/src/features/main/ecs/core-database/components.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { CellIndex } from "../../data/cell-index/cell-index.js";
+import { PlayerMark } from "../../data/player-mark/player-mark.js";
+
+export const components = Database.components({
+  document: {
+    mark: PlayerMark.schema,
+    index: CellIndex.schema,
+  },
+});

package/references/data-lit-tictactoe/src/features/main/ecs/core-database/core-database.ts

@@ -0,0 +1,35 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import type { Store } from "@adobe/data/ecs";
+import { components } from "./components.js";
+import { resources } from "./resources.js";
+import { archetypes } from "./archetypes.js";
+
+// The core schema: all components, resources, and archetypes for the feature,
+// grouped by scope inside components.ts / resources.ts. tictactoe is
+// document-only (shared + durable) — no settings/presence/session state.
+const coreDatabasePlugin = Database.Plugin.create({
+  components,
+  resources,
+  archetypes,
+});
+
+export type CoreDatabase = Database.Plugin.ToDatabase<typeof coreDatabasePlugin>;
+
+// Resolved component map, declared at module scope so the imported `Store`
+// namespace isn't shadowed by `CoreDatabase.Store` below.
+type CoreComponents = Store.Components<
+  Database.Plugin.ToStore<typeof coreDatabasePlugin>
+>;
+
+export namespace CoreDatabase {
+  export const plugin = coreDatabasePlugin;
+  /**
+   * The store this database's transactions operate on: entities, resources,
+   * archetypes, index handles, and the initiating `userId`. A store *is* the
+   * transaction context — there is no separate transaction type.
+   */
+  export type Store = Database.Plugin.ToStore<typeof coreDatabasePlugin>;
+  /** Index-declaration type bound to this database's components. */
+  export type Index = Database.Index<CoreComponents>;
+}

package/references/data-lit-tictactoe/src/features/main/ecs/core-database/resources.ts

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { PlayerMark } from "../../data/player-mark/player-mark.js";
+import { Score } from "../../data/score/score.js";
+
+export const resources = Database.resources({
+  document: {
+    firstPlayer: PlayerMark.schema,
+    xWins: Score.schema,
+    oWins: Score.schema,
+    draws: Score.schema,
+  },
+});

package/references/data-lit-tictactoe/src/features/main/ecs/feature-database.ts

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// The assembled feature database. Its topmost layer is `service-database`
+// (adds the AI agent services). Every consumer — `ui/`, the app entry,
+// `ecs/conformance/` — references `FeatureDatabase`, never the topmost layer,
+// so adding or dropping a layer changes only this one line.
+export { ServiceDatabase as FeatureDatabase } from "./service-database/service-database.js";

package/references/data-lit-tictactoe/src/features/main/ecs/index-database/index-database.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { CoreDatabase } from "../core-database/core-database.js";
+import * as indexes from "./indexes/index.js";
+
+const indexDatabasePlugin = Database.Plugin.create({
+  extends: CoreDatabase.plugin,
+  indexes,
+});
+
+export type IndexDatabase = Database.Plugin.ToDatabase<typeof indexDatabasePlugin>;
+
+export namespace IndexDatabase {
+  export const plugin = indexDatabasePlugin;
+  export type Store = Database.Plugin.ToStore<typeof indexDatabasePlugin>;
+}

package/references/data-lit-tictactoe/src/features/main/ecs/index-database/indexes/by-cell.ts

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { CoreDatabase } from "../../core-database/core-database.js";
+
+// O(1) lookup of the mark occupying a given cell. Unique: a cell holds at most
+// one mark, so `db.indexes.byCell.get({ index }) → Entity | null`.
+export const byCell = {
+  key: "index",
+  unique: true,
+} as const satisfies CoreDatabase.Index;

package/references/data-lit-tictactoe/src/features/main/ecs/index-database/indexes/index.ts

@@ -0,0 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from "./by-cell.js";

package/references/data-lit-tictactoe/src/features/main/ecs/service-database/service-database.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { AgenticService } from "@adobe/data/service";
+import { ComputedDatabase } from "../computed-database/computed-database.js";
+import {
+  createAgentService,
+  createRootAgentService,
+} from "./services/index.js";
+
+const serviceDatabasePlugin = Database.Plugin.create({
+  extends: ComputedDatabase.plugin,
+  services: {
+    agent: (db): AgenticService => createRootAgentService(db),
+    agentX: (db): AgenticService => createAgentService(db, "X"),
+    agentO: (db): AgenticService => createAgentService(db, "O"),
+  },
+});
+
+export type ServiceDatabase = Database.Plugin.ToDatabase<
+  typeof serviceDatabasePlugin
+>;
+
+export namespace ServiceDatabase {
+  export const plugin = serviceDatabasePlugin;
+  export type Store = Database.Plugin.ToStore<typeof serviceDatabasePlugin>;
+}

package/references/data-lit-tictactoe/src/{state/agent-plugin.ts → features/main/ecs/service-database/services/create-agent-service.ts}

@@ -1,26 +1,27 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
-
-import { Database } from "@adobe/data/ecs";
 import { Observe } from "@adobe/data/observe";
 import { AgenticService } from "@adobe/data/service";
-import { BoardState } from "../types/board-state/board-state";
-import type { PlayerMark } from "../types/player-mark/player-mark";
-import { tictactoePlugin } from "./tictactoe-plugin";
-import type { TictactoeDatabase } from "./tictactoe-plugin";
+import { BoardState } from "../../../data/board-state/board-state.js";
+import type { PlayerMark } from "../../../data/player-mark/player-mark.js";
+import { board as boardComputed } from "../../computed-database/computed/board.js";
+import type { ComputedDatabase } from "../../computed-database/computed-database.js";
 
 const roleDescription = (mark: PlayerMark): string =>
   `You are playing as ${mark} in tic-tac-toe. Play to the best of your ability.`;
 
-const createTictactoeAgentService = (
-  db: TictactoeDatabase,
+/**
+ * Build an {@link AgenticService} that plays a single mark. The service
+ * exposes the board, whether it is the agent's turn, the winner, and the
+ * `playMove` / `resetGame` actions gated on those conditions.
+ */
+export const createAgentService = (
+  db: ComputedDatabase,
   agentMark: PlayerMark,
 ): AgenticService => {
-  const board = db.observe.resources.board;
+  const board = boardComputed(db);
   const isGameOver = Observe.withFilter(board, BoardState.isGameOver);
-  const currentPlayer = Observe.withFilter(
-    board,
-    (nextBoard) =>
-      BoardState.currentPlayer(nextBoard, db.resources.firstPlayer),
+  const currentPlayer = Observe.withFilter(board, (nextBoard) =>
+    BoardState.currentPlayer(nextBoard, db.resources.firstPlayer),
   );
   const yourTurn = Observe.withMap(
     Observe.fromProperties({ isGameOver, currentPlayer }),
@@ -88,30 +89,3 @@ const createTictactoeAgentService = (
     },
   });
 };
-
-const tictactoeLinkDescriptions = { x: "Play as X", o: "Play as O" } as const;
-
-const createTictactoeRootAgentService = (
-  db: TictactoeDatabase,
-): AgenticService => {
-  const root = AgenticService.create({
-    interface: {
-      x: { type: "link", description: tictactoeLinkDescriptions.x },
-      o: { type: "link", description: tictactoeLinkDescriptions.o },
-    },
-    implementation: {
-      x: createTictactoeAgentService(db, "X"),
-      o: createTictactoeAgentService(db, "O"),
-    },
-  });
-  return { ...root, linkDescriptions: tictactoeLinkDescriptions } as AgenticService;
-};
-
-export const agentPlugin = Database.Plugin.create({
-  extends: tictactoePlugin,
-  services: {
-    agent: (db): AgenticService => createTictactoeRootAgentService(db),
-    agentX: (db): AgenticService => createTictactoeAgentService(db, "X"),
-    agentO: (db): AgenticService => createTictactoeAgentService(db, "O"),
-  },
-});

package/references/data-lit-tictactoe/src/features/main/ecs/service-database/services/create-root-agent-service.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { AgenticService } from "@adobe/data/service";
+import type { ComputedDatabase } from "../../computed-database/computed-database.js";
+import { createAgentService } from "./create-agent-service.js";
+
+const linkDescriptions = { x: "Play as X", o: "Play as O" } as const;
+
+/**
+ * Root agent exposing the two mark-specific agents as links, so a supervising
+ * agent can choose which side to drive.
+ */
+export const createRootAgentService = (
+  db: ComputedDatabase,
+): AgenticService => {
+  const root = AgenticService.create({
+    interface: {
+      x: { type: "link", description: linkDescriptions.x },
+      o: { type: "link", description: linkDescriptions.o },
+    },
+    implementation: {
+      x: createAgentService(db, "X"),
+      o: createAgentService(db, "O"),
+    },
+  });
+  return { ...root, linkDescriptions } as AgenticService;
+};

package/references/data-lit-tictactoe/src/features/main/ecs/service-database/services/index.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from "./create-agent-service.js";
+export * from "./create-root-agent-service.js";

package/references/data-lit-tictactoe/src/features/main/ecs/transaction-database/transaction-database.ts

@@ -0,0 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "@adobe/data/ecs";
+import { IndexDatabase } from "../index-database/index-database.js";
+import * as transactions from "./transactions/index.js";
+
+const transactionDatabasePlugin = Database.Plugin.create({
+  extends: IndexDatabase.plugin,
+  transactions,
+});
+
+export type TransactionDatabase = Database.Plugin.ToDatabase<
+  typeof transactionDatabasePlugin
+>;
+
+export namespace TransactionDatabase {
+  export const plugin = transactionDatabasePlugin;
+  export type Store = Database.Plugin.ToStore<typeof transactionDatabasePlugin>;
+}

package/references/data-lit-tictactoe/src/features/main/ecs/transaction-database/transactions/index.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from "./restart-game.js";
+export * from "./play-move.js";

package/references/data-lit-tictactoe/src/features/main/ecs/transaction-database/transactions/play-move.test.ts

@@ -0,0 +1,20 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// `playMove` conforms to `State.playMove`. Both take a plain board index, so the
+// `apply` closure calls the raw transaction directly on the seeded store — no
+// entity resolution needed. Every branch of the move guard (legal placement,
+// alternation, win, occupied / out-of-bounds / game-over no-ops) is covered by
+// the shared cases.
+import { describe } from "vitest";
+import { State } from "../../../data/state/state.js";
+import { cases } from "../../../data/state/play-move.cases.js";
+import { expectConforms } from "../../conformance/expect-conforms.js";
+import { playMove } from "./play-move.js";
+
+describe("playMove transaction conforms to State.playMove", () => {
+  expectConforms({
+    cases,
+    spec: State.playMove,
+    apply: playMove,
+  });
+});

package/references/data-lit-tictactoe/src/features/main/ecs/transaction-database/transactions/play-move.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { BoardState } from "../../../data/board-state/board-state.js";
+import { PlayMoveArgs } from "../../../data/play-move-args/play-move-args.js";
+import type { CoreDatabase } from "../../core-database/core-database.js";
+import { readBoard } from "./read-board.js";
+
+/**
+ * Play the current player's mark into `index` by creating a PlacedMark entity.
+ * In sync/P2P mode (`t.userId` set) a peer may only play their own mark;
+ * illegal or out-of-turn moves are silently ignored so the transaction stays
+ * idempotent under replay.
+ */
+export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
+  const board = readBoard(t);
+  const mark = BoardState.currentPlayer(board, t.resources.firstPlayer);
+  if (t.userId !== undefined && t.userId !== mark) return;
+  if (!PlayMoveArgs.canPlayMove({ board, index }).ok) return;
+  t.archetypes.PlacedMark.insert({ mark, index });
+};

package/references/data-lit-tictactoe/src/features/main/ecs/transaction-database/transactions/read-board.ts

@@ -0,0 +1,20 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { BoardState } from "../../../data/board-state/board-state.js";
+import type { PlacedMark } from "../../../data/placed-mark/placed-mark.js";
+import type { CoreDatabase } from "../../core-database/core-database.js";
+
+// Synchronously project the placed-mark entities into a BoardState snapshot,
+// for transactions that need the current board (playMove, restartGame). The
+// board computed does the same projection reactively.
+export const readBoard = (t: CoreDatabase.Store): BoardState => {
+  const marks: PlacedMark[] = [];
+  for (const arch of t.queryArchetypes(t.archetypes.PlacedMark.components)) {
+    for (let row = 0; row < arch.rowCount; row++) {
+      marks.push({
+        mark: arch.columns.mark.get(row),
+        index: arch.columns.index.get(row),
+      });
+    }
+  }
+  return BoardState.fromMarks(marks);
+};

package/references/data-lit-tictactoe/src/features/main/ecs/transaction-database/transactions/restart-game.test.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// `restartGame` conforms to `State.restartGame`. It takes no args, so the
+// `apply` closure just dispatches the raw transaction on the seeded store. The
+// shared cases cover each scoreboard outcome — X win, O win, draw, and an
+// unfinished restart that bumps no counter.
+import { describe } from "vitest";
+import { State } from "../../../data/state/state.js";
+import { cases } from "../../../data/state/restart-game.cases.js";
+import { expectConforms } from "../../conformance/expect-conforms.js";
+import { restartGame } from "./restart-game.js";
+
+describe("restartGame transaction conforms to State.restartGame", () => {
+  expectConforms({
+    cases,
+    spec: State.restartGame,
+    apply: restartGame,
+  });
+});

package/references/data-lit-tictactoe/src/features/main/ecs/transaction-database/transactions/restart-game.ts

@@ -0,0 +1,25 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { BoardState } from "../../../data/board-state/board-state.js";
+import { PlayerMark } from "../../../data/player-mark/player-mark.js";
+import type { CoreDatabase } from "../../core-database/core-database.js";
+import { readBoard } from "./read-board.js";
+
+/**
+ * Tally the finished game into the win/draw counters, hand the first move to
+ * the opposite player, and clear the board by deleting every PlacedMark entity.
+ */
+export const restartGame = (t: CoreDatabase.Store) => {
+  const board = readBoard(t);
+  const winner = BoardState.getWinner(board);
+  const status = BoardState.deriveStatus(board);
+  if (winner === "X") t.resources.xWins = t.resources.xWins + 1;
+  else if (winner === "O") t.resources.oWins = t.resources.oWins + 1;
+  else if (status === "draw") t.resources.draws = t.resources.draws + 1;
+  t.resources.firstPlayer = PlayerMark.opponent[t.resources.firstPlayer];
+
+  for (const arch of t.queryArchetypes(t.archetypes.PlacedMark.components)) {
+    for (let row = arch.rowCount - 1; row >= 0; row--) {
+      t.delete(arch.columns.id.get(row));
+    }
+  }
+};

package/references/data-lit-tictactoe/src/{elements → features/main/ui}/tictactoe-app/tictactoe-app-element.ts

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
 import { customElement } from "lit/decorators.js";
-import { TictactoeElement } from "../../tictactoe-element.js";
+import { TictactoeElement } from "../tictactoe-element.js";
 import { styles } from "./tictactoe-app.css.js";
 import * as presentation from "./tictactoe-app-presentation.js";
 

package/references/data-lit-tictactoe/src/features/main/ui/tictactoe-app/tictactoe-app-presentation.test.ts

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment jsdom
+// jsdom only so the lazy child-element wrappers (`void import(...)`) can load;
+// the assertions never touch the DOM.
+import { describe, it, expect } from "vitest";
+import { Template } from "@adobe/data-lit";
+import { render } from "./tictactoe-app-presentation.js";
+
+describe("tictactoe-app-presentation", () => {
+  it("mounts the board and the hud", () => {
+    const t = Template.from(render());
+    expect(t.has("<tictactoe-board")).toBe(true);
+    expect(t.has("<tictactoe-hud")).toBe(true);
+  });
+});

package/references/data-lit-tictactoe/src/features/main/ui/tictactoe-app/tictactoe-app.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { html, type TemplateResult } from "lit";
+import type { ComputedDatabase } from "../../ecs/computed-database/computed-database.js";
+
+type TictactoeService = ComputedDatabase;
+
+/**
+ * Generic over `S` so callers may pass a database built from any plugin
+ * that extends the base game database (for example one that adds AI agents
+ * or peer presence). The element class itself is typed on the minimal
+ * `ComputedDatabase` 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 → features/main/ui}/tictactoe-board/tictactoe-board-element.ts

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 
 import { customElement } from "lit/decorators.js";
-import { TictactoeElement } from "../../tictactoe-element.js";
+import { TictactoeElement } from "../tictactoe-element.js";
 import { styles } from "./tictactoe-board.css.js";
 import * as presentation from "./tictactoe-board-presentation.js";
 

package/references/data-lit-tictactoe/src/features/main/ui/tictactoe-board/tictactoe-board-presentation.test.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment jsdom
+// jsdom only so the lazy cell wrapper (`void import(...)`) can load; the
+// assertions never touch the DOM.
+import { describe, it, expect } from "vitest";
+import { Template } from "@adobe/data-lit";
+import { render } from "./tictactoe-board-presentation.js";
+
+describe("tictactoe-board-presentation", () => {
+  it("renders a 3x3 board of nine cells", () => {
+    const t = Template.from(render());
+    expect(t.has("board")).toBe(true);
+    expect(t.has("<tictactoe-cell")).toBe(true);
+    expect(t.children).toHaveLength(9);
+  });
+});

package/references/data-lit-tictactoe/src/features/main/ui/tictactoe-cell/observe-cell.ts

@@ -0,0 +1,32 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Observe } from "@adobe/data/observe";
+import type { UIService } from "@adobe/data/service";
+import { BoardCell } from "../../data/board-cell/board-cell.js";
+import { GameStatus } from "../../data/game-status/game-status.js";
+import type { ComputedDatabase } from "../../ecs/computed-database/computed-database.js";
+
+// Reactive per-cell view. The mark is looked up through the `byCell` index —
+// the cell binds to whichever entity occupies its board position — while
+// winning-line membership and playability come from the game-level computeds.
+export const observeCell = (
+  db: UIService.FromService<ComputedDatabase>,
+  index: number,
+) =>
+  Observe.withMap(
+    Observe.fromProperties({
+      occupants: Observe.fromKeys(
+        db.indexes.byCell.observe({ index }),
+        (id) => db.observe.entity(id),
+      ),
+      winningLine: db.computed.winningLine,
+      status: db.computed.status,
+    }),
+    ({ occupants, winningLine, status }) => {
+      const cell: BoardCell = occupants[0]?.mark ?? BoardCell.blank;
+      return {
+        cell,
+        isWinning: winningLine?.includes(index) ?? false,
+        isPlayable: GameStatus.isActive(status) && cell === BoardCell.blank,
+      };
+    },
+  );