@dreamboard-games/ui-sdk 0.0.41

package/src/components/surfaces/BoardSurface.tsx

@@ -0,0 +1,340 @@
+import { useCallback, useEffect, useMemo, type ReactNode } from "react";
+import { useStore } from "zustand";
+import { useInteractionUiStore } from "../../context/InteractionDraftContext.js";
+import {
+  useInteractionHandle,
+  type InteractionHandle,
+} from "../../hooks/useInteractionHandle.js";
+import { usePluginState } from "../../context/PluginStateContext.js";
+import type { InteractionDescriptor } from "../../types/plugin-state.js";
+import {
+  eligibleTargetsByInput,
+  eligibleTargetsByBoardKind,
+  hasBoardTargetInput,
+  interactionArmScope,
+  interactionInputKeys,
+  type BoardTargetKind,
+} from "../../utils/interaction-inputs.js";
+
+/** Standard board surface tags produced by the trusted bundle. */
+export type BoardSurfaceTag =
+  | "board-vertex"
+  | "board-edge"
+  | "board-tile"
+  | "board-space";
+
+/**
+ * Context handed to the `<BoardSurface>` children render-prop. Covers
+ * everything callers need to route hex/vertex/edge/space clicks into the
+ * correct interaction with a single `select(targetId)` call.
+ */
+export interface BoardSurfaceContext<I extends string = string> {
+  /** All available board-* interactions (armed and unarmed). */
+  interactions: ReadonlyArray<InteractionDescriptor<I>>;
+  /** Key of the currently armed interaction, or null. */
+  armedId: string | null;
+  /** Handle of the armed interaction, or null when nothing is armed. */
+  armed: InteractionHandle | null;
+  /**
+   * Eligible target ids for the armed interaction, keyed by
+   * input-collector name (e.g. `{ vertexId: Set(['v-1','v-2']) }`).
+   */
+  eligible: Readonly<Record<string, ReadonlySet<string>>>;
+  /** Arm a specific interaction key on its surface (or disarm when null). */
+  arm: (interactionKey: string | null) => void;
+  /**
+   * Commit a target click. Writes `targetId` into the first draft input
+   * whose eligible-set includes it (preferring inputs that are still
+   * empty) and submits as soon as every required input is filled.
+   */
+  select: (targetId: string) => Promise<void>;
+  /**
+   * Whether `targetId` is eligible under the armed interaction.
+   * Pass `inputKey` to scope the check to a specific input.
+   */
+  isEligible: (targetId: string, inputKey?: string) => boolean;
+}
+
+export interface BoardSurfaceProps<I extends string = string> {
+  /**
+   * Required children-as-function. Receives a
+   * {@link BoardSurfaceContext} with the armed interaction, eligible
+   * targets and a click-routing `select(targetId)` helper.
+   */
+  children: (ctx: BoardSurfaceContext<I>) => ReactNode;
+  /** Rendered when no board-* interactions are available. */
+  empty?: ReactNode;
+  /**
+   * When true (default), auto-arm the single available interaction so
+   * single-choice boards don't need explicit arming UI.
+   */
+  autoArmSingle?: boolean;
+  /** Surface tags included in this instance. Defaults to all four. */
+  surfaces?: readonly BoardSurfaceTag[];
+}
+
+/**
+ * Surface for any interaction tagged `board-vertex`, `board-edge`,
+ * `board-tile` or `board-space`.
+ *
+ * `BoardSurface` does **not** render board geometry (that stays with
+ * the app). Instead it exposes an opinionated click-routing context so
+ * that a plain SVG/canvas board wired via `select(targetId)`
+ * automatically participates in arming, eligibility highlighting, and
+ * submission.
+ *
+ * ```tsx
+ * <BoardSurface>
+ *   {({ eligible, select, armedId }) => (
+ *     <HexBoard
+ *       highlightedVertices={eligible.vertexId}
+ *       onVertexClick={(id) => select(id)}
+ *       armedInteractionId={armedId}
+ *     />
+ *   )}
+ * </BoardSurface>
+ * ```
+ */
+export function BoardSurface<I extends string = string>({
+  children,
+  empty = null,
+  autoArmSingle = true,
+  surfaces = ["board-vertex", "board-edge", "board-tile", "board-space"],
+}: BoardSurfaceProps<I>) {
+  const store = useInteractionUiStore();
+  const subscribedArmedBySurface = useStore(store, (state) => state.arms);
+  const armedBySurface = store.getState().arms ?? subscribedArmedBySurface;
+  const descriptors = usePluginState(
+    (state) => state.gameplay.availableInteractions ?? [],
+  );
+
+  const armedIds = useMemo(
+    () => new Set(Object.values(armedBySurface)),
+    [armedBySurface],
+  );
+  const interactions = useMemo(() => {
+    const targetKinds = new Set(surfaces.map(boardTargetKindForSurface));
+    return descriptors.filter(
+      (descriptor) =>
+        armedIds.has(descriptor.interactionKey) ||
+        (hasBoardTargetInput(descriptor) &&
+          (targetKinds.size === 0 ||
+            (
+              Object.keys(
+                eligibleTargetsByBoardKind(descriptor),
+              ) as BoardTargetKind[]
+            ).some((kind) => targetKinds.has(kind)))),
+    ) as unknown as ReadonlyArray<InteractionDescriptor<I>>;
+  }, [armedIds, descriptors, surfaces]);
+
+  const armedId = useMemo(() => {
+    const interactionKeys = new Set<string>(
+      interactions.map((descriptor) => descriptor.interactionKey),
+    );
+    return (
+      Object.values(armedBySurface).find((id) => interactionKeys.has(id)) ??
+      null
+    );
+  }, [armedBySurface, interactions]);
+  const armedDescriptor = useMemo(
+    () =>
+      interactions.find(
+        (descriptor) => descriptor.interactionKey === armedId,
+      ) ??
+      interactions.find((descriptor) =>
+        armedIds.has(descriptor.interactionKey),
+      ) ??
+      null,
+    [armedIds, interactions, armedId],
+  );
+
+  useEffect(() => {
+    if (!autoArmSingle) return;
+    if (interactions.length !== 1) return;
+    const only = interactions[0];
+    if (!only || !only.available) return;
+    const scope = interactionArmScope(only);
+    if (store.getArmed(scope) === only.interactionKey) return;
+    store.arm(scope, only.interactionKey);
+  }, [autoArmSingle, interactions, store]);
+
+  // Disarm stale ids (interaction disappeared from the inbox).
+  useEffect(() => {
+    for (const [surface, interactionKey] of Object.entries(armedBySurface)) {
+      const stillPresent = interactions.some(
+        (descriptor) => descriptor.interactionKey === interactionKey,
+      );
+      if (!stillPresent) {
+        store.arm(surface, null);
+      }
+    }
+  }, [armedBySurface, interactions, store]);
+
+  if (interactions.length === 0) {
+    return <>{empty}</>;
+  }
+
+  if (armedDescriptor) {
+    return (
+      <ArmedBoardBody<I>
+        interactions={interactions}
+        armedDescriptor={armedDescriptor}
+      >
+        {children}
+      </ArmedBoardBody>
+    );
+  }
+
+  return (
+    <UnarmedBoardBody<I> interactions={interactions}>
+      {children}
+    </UnarmedBoardBody>
+  );
+}
+
+function ArmedBoardBody<I extends string>({
+  interactions,
+  armedDescriptor,
+  children,
+}: {
+  interactions: ReadonlyArray<InteractionDescriptor<I>>;
+  armedDescriptor: InteractionDescriptor<I>;
+  children: (ctx: BoardSurfaceContext<I>) => ReactNode;
+}) {
+  const armed = useInteractionHandle(armedDescriptor);
+  const store = useInteractionUiStore();
+
+  const eligible = useMemo<
+    Readonly<Record<string, ReadonlySet<string>>>
+  >(() => {
+    const result: Record<string, ReadonlySet<string>> = {};
+    const raw = eligibleTargetsByInput(armed.descriptor);
+    for (const [key, values] of Object.entries(raw)) {
+      result[key] = new Set(values ?? []);
+    }
+    return result;
+  }, [armed.descriptor]);
+
+  const arm = useCallback(
+    (interactionKey: string | null) => {
+      if (interactionKey === null) {
+        store.arm(interactionArmScope(armedDescriptor), null);
+        return;
+      }
+      const target = interactions.find(
+        (d) => d.interactionKey === interactionKey,
+      );
+      if (!target) return;
+      store.arm(interactionArmScope(target), interactionKey);
+    },
+    [armedDescriptor, interactions, store],
+  );
+
+  const isEligible = useCallback(
+    (targetId: string, inputKey?: string) => {
+      if (inputKey !== undefined) {
+        return eligible[inputKey]?.has(targetId) ?? false;
+      }
+      return Object.values(eligible).some((set) => set.has(targetId));
+    },
+    [eligible],
+  );
+
+  const select = useCallback(
+    async (targetId: string) => {
+      const keys = Object.keys(eligible);
+      if (keys.length === 0) return;
+      const currentDraft = armed.draft;
+      const emptyMatch = keys.find(
+        (k) =>
+          eligible[k]?.has(targetId) &&
+          (currentDraft[k] === undefined || currentDraft[k] === null),
+      );
+      const fallback = keys.find((k) => eligible[k]?.has(targetId));
+      const match = emptyMatch ?? fallback;
+      if (!match) return;
+      armed.setInput(match, targetId);
+      const nextDraft: Record<string, unknown> = {
+        ...currentDraft,
+        [match]: targetId,
+      };
+      const required = interactionInputKeys(armed.descriptor);
+      const ready = required.every(
+        (key) => nextDraft[key] !== undefined && nextDraft[key] !== null,
+      );
+      if (ready) {
+        await armed.submit(nextDraft);
+      }
+    },
+    [armed, eligible],
+  );
+
+  const ctx: BoardSurfaceContext<I> = {
+    interactions,
+    armedId: armed.descriptor.interactionKey,
+    armed,
+    eligible,
+    arm,
+    select,
+    isEligible,
+  };
+
+  return <>{children(ctx)}</>;
+}
+
+function UnarmedBoardBody<I extends string>({
+  interactions,
+  children,
+}: {
+  interactions: ReadonlyArray<InteractionDescriptor<I>>;
+  children: (ctx: BoardSurfaceContext<I>) => ReactNode;
+}) {
+  const store = useInteractionUiStore();
+
+  const arm = useCallback(
+    (interactionKey: string | null) => {
+      if (interactionKey === null) {
+        for (const descriptor of interactions) {
+          store.arm(interactionArmScope(descriptor), null);
+        }
+        return;
+      }
+      const target = interactions.find(
+        (d) => d.interactionKey === interactionKey,
+      );
+      if (!target) return;
+      store.arm(interactionArmScope(target), interactionKey);
+    },
+    [interactions, store],
+  );
+
+  const noop = useCallback(async () => {}, []);
+  const never = useCallback(() => false, []);
+
+  const ctx: BoardSurfaceContext<I> = {
+    interactions,
+    armedId: null,
+    armed: null,
+    eligible: EMPTY_ELIGIBLE,
+    arm,
+    select: noop,
+    isEligible: never,
+  };
+
+  return <>{children(ctx)}</>;
+}
+
+const EMPTY_ELIGIBLE: Readonly<Record<string, ReadonlySet<string>>> = {};
+
+function boardTargetKindForSurface(surface: BoardSurfaceTag): BoardTargetKind {
+  switch (surface) {
+    case "board-edge":
+      return "edge";
+    case "board-space":
+      return "space";
+    case "board-tile":
+      return "tile";
+    case "board-vertex":
+      return "vertex";
+  }
+}

package/src/components/surfaces/ChromeSurface.tsx

@@ -0,0 +1,123 @@
+import type { ReactNode } from "react";
+import { useSeatInbox } from "../../hooks/useSeatInbox.js";
+import {
+  useInteractionHandle,
+  type InteractionHandle,
+} from "../../hooks/useInteractionHandle.js";
+import { useTheme } from "../../theme/ThemeProvider.js";
+import type { InteractionDescriptor } from "../../types/plugin-state.js";
+import { DefaultInteractionButton } from "./internal/DefaultInteractionButton.js";
+import type {
+  InteractionDefaultedKeysOf,
+  InteractionParamsByKeyShape,
+  InteractionParamsOf,
+  SurfaceRenderMap,
+} from "./types.js";
+
+export interface ChromeSurfaceProps<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+> {
+  /**
+   * Optional per-interaction overrides. Omit to fall back to the default
+   * `DefaultInteractionButton` for every chrome interaction.
+   */
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  /**
+   * Fallback renderer for chrome interactions without a `render` entry.
+   * Defaults to the built-in `DefaultInteractionButton`.
+   */
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+  /** Interaction keys intentionally rendered elsewhere, such as auto primary actions. */
+  excludeInteractionKeys?: readonly string[];
+  /** Shown when no chrome interactions are available. */
+  empty?: ReactNode;
+}
+
+/**
+ * Default renderer for legacy chrome interactions — persistent controls like
+ * menu buttons or status indicators. Renders a layout-less horizontal flex row
+ * so callers can own positioning and spacing.
+ *
+ * Visual styling is sourced entirely from the active {@link useTheme}.
+ */
+export function ChromeSurface<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  render,
+  renderItem,
+  excludeInteractionKeys,
+  empty = null,
+}: ChromeSurfaceProps<I, ParamsByKey>) {
+  const theme = useTheme();
+  const inbox = useSeatInbox();
+  const excluded = new Set(excludeInteractionKeys ?? []);
+  const items = (
+    (inbox.bySurface.chrome ?? []) as ReadonlyArray<InteractionDescriptor<I>>
+  ).filter((descriptor) => !excluded.has(descriptor.interactionKey));
+  if (items.length === 0) return <>{empty}</>;
+  return (
+    <div
+      role="toolbar"
+      aria-label="Chrome actions"
+      data-surface="chrome"
+      style={{
+        display: "flex",
+        gap: theme.space[2],
+        alignItems: "center",
+      }}
+    >
+      {items.map((descriptor) => (
+        <ChromeItem<I, ParamsByKey>
+          key={descriptor.interactionKey}
+          descriptor={descriptor}
+          render={render}
+          renderItem={renderItem}
+        />
+      ))}
+    </div>
+  );
+}
+
+function ChromeItem<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  descriptor,
+  render,
+  renderItem,
+}: {
+  descriptor: InteractionDescriptor<I>;
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+}) {
+  const handle = useInteractionHandle<
+    InteractionParamsOf<ParamsByKey, I>,
+    InteractionDefaultedKeysOf<ParamsByKey, I>
+  >(descriptor);
+  const override = render?.[descriptor.interactionKey] as
+    | ((
+        descriptor: InteractionDescriptor<I>,
+        handle: InteractionHandle<
+          InteractionParamsOf<ParamsByKey, I>,
+          InteractionDefaultedKeysOf<ParamsByKey, I>
+        >,
+      ) => ReactNode)
+    | undefined;
+  if (override) return <>{override(descriptor, handle)}</>;
+  if (renderItem) return <>{renderItem(descriptor, handle)}</>;
+  return <DefaultInteractionButton descriptor={descriptor} handle={handle} />;
+}

package/src/components/surfaces/ExhaustivenessAudit.tsx

@@ -0,0 +1,91 @@
+import { useEffect } from "react";
+import { useSeatInbox } from "../../hooks/useSeatInbox.js";
+import type { SurfaceRenderMap } from "./types.js";
+
+/**
+ * Per-surface renderer maps the shell is currently using. `undefined`
+ * values are treated as "use the surface's default renderer".
+ */
+export interface ExhaustivenessAuditProps {
+  panel?: SurfaceRenderMap<string>;
+  handledInteractionKeys?: readonly string[];
+  inbox?: SurfaceRenderMap<string>;
+  chrome?: SurfaceRenderMap<string>;
+  blocker?: SurfaceRenderMap<string>;
+  board?: SurfaceRenderMap<string>;
+}
+
+type SurfaceBucket = keyof ExhaustivenessAuditProps;
+
+const AUDITED_BUCKETS: ReadonlyArray<
+  Exclude<SurfaceBucket, "handledInteractionKeys">
+> = ["panel", "inbox", "chrome", "blocker", "board"];
+
+/**
+ * Development-only runtime audit that logs a single grouped warning per
+ * mount describing which interaction ids are currently projected onto the
+ * seat's inbox but do not have an explicit renderer override in the
+ * supplied render maps. Useful for catching "oops, I wired a new
+ * interaction but forgot to render it" regressions before CI notices.
+ *
+ * In production builds (`process.env.NODE_ENV === "production"`) this
+ * component is a no-op.
+ *
+ * ```tsx
+ * <ExhaustivenessAudit
+ *   panel={panelRenderers}
+ *   inbox={inboxRenderers}
+ * />
+ * ```
+ */
+export function ExhaustivenessAudit(props: ExhaustivenessAuditProps) {
+  const inbox = useSeatInbox();
+
+  useEffect(() => {
+    const proc = (globalThis as { process?: { env?: { NODE_ENV?: string } } })
+      .process;
+    if (!proc) return;
+    if (proc.env?.NODE_ENV === "production") return;
+
+    const unhandled: Array<{ surface: SurfaceBucket; interactionId: string }> =
+      [];
+    const handledInteractionKeys = new Set(props.handledInteractionKeys ?? []);
+
+    for (const bucket of AUDITED_BUCKETS) {
+      const bySurface =
+        bucket === "board"
+          ? [
+              ...(inbox.bySurface["board-vertex"] ?? []),
+              ...(inbox.bySurface["board-edge"] ?? []),
+              ...(inbox.bySurface["board-tile"] ?? []),
+              ...(inbox.bySurface["board-space"] ?? []),
+            ]
+          : (inbox.bySurface[bucket] ?? []);
+      const map = props[bucket];
+      for (const descriptor of bySurface) {
+        if (handledInteractionKeys.has(descriptor.interactionKey)) continue;
+        if (!map || !(descriptor.interactionKey in map)) {
+          unhandled.push({
+            surface: bucket,
+            interactionId: descriptor.interactionId,
+          });
+        }
+      }
+    }
+
+    if (unhandled.length === 0) return;
+
+    // eslint-disable-next-line no-console -- dev-only audit
+    console.groupCollapsed(
+      `[dreamboard/ui-sdk] ExhaustivenessAudit: ${unhandled.length} interaction(s) fell through to the default renderer`,
+    );
+    for (const entry of unhandled) {
+      // eslint-disable-next-line no-console -- dev-only audit
+      console.warn(`${entry.surface} · ${entry.interactionId}`);
+    }
+    // eslint-disable-next-line no-console -- dev-only audit
+    console.groupEnd();
+  }, [inbox, props]);
+
+  return null;
+}

package/src/components/surfaces/InboxSurface.test.tsx

@@ -0,0 +1,149 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import { RuntimeContext } from "../../context/RuntimeContext.js";
+import { PluginSessionContext } from "../../context/PluginSessionContext.js";
+import type {
+  InteractionDescriptor,
+  PluginStateSnapshot,
+} from "../../types/plugin-state.js";
+import type {
+  PluginSessionState,
+  RuntimeAPI,
+} from "../../types/runtime-api.js";
+import { InboxSurface } from "./InboxSurface.js";
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createInboxDescriptor(
+  id: string,
+  overrides: Partial<InteractionDescriptor> = {},
+): InteractionDescriptor {
+  return {
+    phaseName: "respond",
+    interactionKey: `respond.${id}`,
+    interactionId: id,
+    kind: "action",
+    inputs: [],
+    commit: { mode: "manual" },
+    available: true,
+    ...overrides,
+  };
+}
+
+function createSnapshot(
+  session: PluginSessionState,
+  descriptors: InteractionDescriptor[],
+): PluginStateSnapshot {
+  return {
+    view: null,
+    gameplay: {
+      currentPhase: "respond",
+      currentStage: null,
+      activePlayers: ["player-1"],
+      availableInteractions: descriptors,
+      zones: {},
+    },
+    lobby: null,
+    notifications: [],
+    session,
+    history: null,
+    syncId: 1,
+  };
+}
+
+function createRuntime(snapshot: PluginStateSnapshot): RuntimeAPI & {
+  getSnapshot: () => PluginStateSnapshot;
+  subscribeToState: (
+    listener: (state: PluginStateSnapshot) => void,
+  ) => () => void;
+} {
+  return {
+    validateInteraction: async () => ({ valid: true }),
+    submitInteraction: async () => undefined,
+    getSessionState: () => snapshot.session,
+    disconnect: () => undefined,
+    getSnapshot: () => snapshot,
+    subscribeToState: () => () => undefined,
+  };
+}
+
+function renderShell(snapshot: PluginStateSnapshot): string {
+  const runtime = createRuntime(snapshot);
+  return renderToString(
+    <RuntimeContext.Provider value={runtime}>
+      <PluginSessionContext.Provider value={snapshot.session}>
+        <InboxSurface />
+      </PluginSessionContext.Provider>
+    </RuntimeContext.Provider>,
+  );
+}
+
+test("InboxSurface renders prompt options as immediate response buttons", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createInboxDescriptor("respondToTrade", {
+      kind: "prompt",
+      inputs: [
+        {
+          key: "response",
+          kind: "form",
+          domain: {
+            type: "choice",
+            choices: [
+              { value: "accept", label: "Accept" },
+              { value: "decline", label: "Decline" },
+            ],
+          },
+        },
+      ],
+      context: {
+        to: "player-1",
+        title: "Trade offer",
+        options: [
+          { id: "accept", label: "Accept" },
+          { id: "decline", label: "Decline" },
+        ],
+      },
+    }),
+  ]);
+
+  const html = renderShell(snapshot);
+
+  expect(html).toContain('data-surface="inbox"');
+  expect(html).toContain("Trade offer");
+  expect(html).toContain('data-option-id="accept"');
+  expect(html).toContain('data-option-id="decline"');
+});
+
+test("InboxSurface does not infer action-kind form interactions as inbox items", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createInboxDescriptor("counterOffer", {
+      inputs: [
+        {
+          key: "give",
+          kind: "form",
+          domain: {
+            type: "resourceMap",
+            resources: [{ resourceId: "wood", label: "Wood", min: 0, max: 2 }],
+          },
+        },
+      ],
+    }),
+  ]);
+
+  const html = renderShell(snapshot);
+
+  expect(html).not.toContain("Counter Offer");
+  expect(html).not.toContain("data-default-interaction");
+  expect(html).not.toContain('aria-expanded="false"');
+  expect(html).not.toContain("Wood");
+});