@dreamboard-games/ui-sdk 0.0.41

package/src/components/PluginRuntime.tsx

@@ -0,0 +1,92 @@
+import React from "react";
+import { InteractionUiProvider } from "../context/InteractionDraftContext.js";
+import { RuntimeProvider } from "../context/RuntimeContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { usePluginRuntime } from "../hooks/usePluginRuntime.js";
+import { GameSkeleton } from "./GameSkeleton.js";
+
+export interface PluginRuntimeProps {
+  /** Child components to render after state sync has started */
+  children: React.ReactNode;
+  /**
+   * Timeout in milliseconds to wait for the first state-sync snapshot.
+   * @default 10000 (10 seconds)
+   */
+  timeout?: number;
+  /** Custom loading component to show while waiting for state sync */
+  loadingComponent?: React.ReactNode;
+  /** Custom error component to show when initialization fails */
+  errorComponent?: (error: string) => React.ReactNode;
+}
+
+/**
+ * PluginRuntime provides the RuntimeContext for plugin components.
+ *
+ * This component:
+ * - Creates a RuntimeAPI instance using the SDK-provided implementation
+ * - Waits for the first reducer-native state-sync snapshot before rendering children
+ * - Provides RuntimeAPI and session state to all child components
+ *
+ * @example
+ * ```tsx
+ * // In your plugin's index.tsx
+ * import { PluginRuntime } from "./components/dreamboard";
+ * import App from './App';
+ *
+ * ReactDOM.createRoot(document.getElementById('root')!).render(
+ *   <PluginRuntime>
+ *     <App />
+ *   </PluginRuntime>
+ * );
+ * ```
+ */
+export function PluginRuntime({
+  children,
+  timeout = 10000,
+  loadingComponent,
+  errorComponent,
+}: PluginRuntimeProps) {
+  const { runtime, isReady, error } = usePluginRuntime({ timeout });
+
+  if (error) {
+    if (errorComponent) {
+      return <>{errorComponent(error)}</>;
+    }
+    return (
+      <div className="flex h-full w-full items-center justify-center bg-gray-50">
+        <div className="text-center p-6">
+          <p className="text-red-600 font-medium mb-2">Failed to load game</p>
+          <p className="text-gray-600 text-sm">{error}</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (!isReady) {
+    if (loadingComponent) {
+      return <>{loadingComponent}</>;
+    }
+    return <GameSkeleton message="Waiting for game state..." />;
+  }
+
+  return (
+    <RuntimeProvider runtime={runtime}>
+      <SessionScopedInteractionUiProvider>
+        {children}
+      </SessionScopedInteractionUiProvider>
+    </RuntimeProvider>
+  );
+}
+
+function SessionScopedInteractionUiProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const { controllingPlayerId } = usePluginSession();
+  return (
+    <InteractionUiProvider key={controllingPlayerId ?? "__no_player__"}>
+      {children}
+    </InteractionUiProvider>
+  );
+}

package/src/components/PrimaryActionButton.test.tsx

@@ -0,0 +1,138 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import { ThemeProvider } from "../theme/ThemeProvider.js";
+import type { InteractionHandle } from "../hooks/useInteractionHandle.js";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+import { PrimaryActionButton } from "./PrimaryActionButton.js";
+
+function makeHandle(
+  overrides: Partial<InteractionDescriptor> = {},
+  handleOverrides: Partial<InteractionHandle> = {},
+): InteractionHandle {
+  const descriptor: InteractionDescriptor = {
+    phaseName: "play",
+    interactionKey: "play.rollDice",
+    interactionId: "rollDice",
+    kind: "action",
+    inputs: [],
+    commit: { mode: "manual" },
+    available: true,
+    ...overrides,
+  };
+  return {
+    descriptor,
+    commit: descriptor.commit,
+    submit: async () => {},
+    validate: async () => {},
+    validateDraft: () => ({
+      ok: true,
+      params: {},
+      fieldErrors: {},
+      formErrors: [],
+      missing: [],
+    }),
+    validateDraftServer: async () => {},
+    submitDraft: async () => {},
+    available: descriptor.available,
+    unavailableReason: descriptor.unavailableReason,
+    draft: {},
+    values: {},
+    setInput: () => {},
+    clearInput: () => {},
+    isReady: true,
+    isArmed: false,
+    arm: () => {},
+    disarm: () => {},
+    ...handleOverrides,
+  };
+}
+
+test("PrimaryActionButton renders fallback label and interaction id", () => {
+  const html = renderToString(
+    <ThemeProvider>
+      <PrimaryActionButton handle={makeHandle()} />
+    </ThemeProvider>,
+  );
+
+  expect(html).toContain("data-dreamboard-primary-action");
+  expect(html).toContain('data-available="true"');
+  expect(html).toContain('data-interaction-id="rollDice"');
+  expect(html).toContain("Roll Dice");
+});
+
+test("PrimaryActionButton disables and surfaces unavailableReason", () => {
+  const handle = makeHandle({
+    available: false,
+    unavailableReason: "Wait for your turn",
+  });
+  const html = renderToString(
+    <ThemeProvider>
+      <PrimaryActionButton handle={handle} />
+    </ThemeProvider>,
+  );
+
+  expect(html).toContain('data-available="false"');
+  // Native `disabled` and `aria-disabled` both flip on so screen
+  // readers and pointer devices both see the disabled state.
+  expect(html).toContain("disabled=");
+  expect(html).toContain('aria-disabled="true"');
+  // The unavailable reason becomes the `title` tooltip so the
+  // player can see why the action is blocked.
+  expect(html).toContain("Wait for your turn");
+});
+
+test("PrimaryActionButton supports a label override", () => {
+  const html = renderToString(
+    <ThemeProvider>
+      <PrimaryActionButton handle={makeHandle()} label="Confirm" />
+    </ThemeProvider>,
+  );
+
+  // Override wins over the generated fallback label.
+  expect(html).toContain("Confirm");
+  expect(html).not.toContain("Roll Dice");
+});
+
+test("PrimaryActionButton suppresses the halo when attention='off'", () => {
+  // The halo is implemented via `motion.span` siblings of the
+  // `<button>`. With `attention="off"` they should be absent so the
+  // button stands alone — useful for screens where the author does
+  // not want a pulse competing with a richer custom indicator.
+  const htmlWithHalo = renderToString(
+    <ThemeProvider>
+      <PrimaryActionButton handle={makeHandle()} attention="always" />
+    </ThemeProvider>,
+  );
+  const htmlWithoutHalo = renderToString(
+    <ThemeProvider>
+      <PrimaryActionButton handle={makeHandle()} attention="off" />
+    </ThemeProvider>,
+  );
+
+  // The halo wrappers are detected via the `boxShadow` keyframe
+  // that the announce pulse renders inline. With the halo off the
+  // wrapper still mounts but the inner motion spans are gone.
+  expect(htmlWithHalo).toContain("box-shadow");
+  // Sanity: the button itself still mounts in both cases.
+  expect(htmlWithoutHalo).toContain('data-interaction-id="rollDice"');
+  // The announce-pulse motion span uses an inset:0 absolute layer.
+  // It is present with the halo on, absent with attention="off".
+  expect(htmlWithHalo.split("position:absolute").length).toBeGreaterThan(
+    htmlWithoutHalo.split("position:absolute").length,
+  );
+});
+
+test("PrimaryActionButton skips the halo entirely when reduced motion is requested", () => {
+  // Reduced-motion pulses would defeat the accessibility contract.
+  // The button must still render — only the decorative halo is
+  // suppressed.
+  const html = renderToString(
+    <ThemeProvider reducedMotion="force">
+      <PrimaryActionButton handle={makeHandle()} attention="always" />
+    </ThemeProvider>,
+  );
+
+  expect(html).toContain('data-interaction-id="rollDice"');
+  // No motion spans — only the static button frame.
+  expect(html.split("position:absolute").length).toBe(1);
+});

package/src/components/PrimaryActionButton.tsx

@@ -0,0 +1,351 @@
+/**
+ * Theme-aware primary CTA button — the dominant call-to-action on
+ * the screen at any given moment ("Roll dice", "End turn", "Confirm
+ * trade", "Place settlement").
+ *
+ * The shell's `chrome.primaryAction` slot accepts either a
+ * pre-rendered React node *or* an {@link InteractionHandle}. When a
+ * handle is supplied, the shell wraps it in this component so the
+ * call site collapses from ~10 lines to one. Authors who need a
+ * fully bespoke CTA can still pass any node.
+ *
+ * Visual contract (Laws of UX cross-references):
+ *
+ * - **Fitts** — defaults to `lg` size (min 56px tall, generous
+ *   horizontal padding) so the dock target is easy to land on.
+ *   Authors can opt down to `md`.
+ * - **Von Restorff (isolation)** — uses `intent.primary.solid` with
+ *   `elevation.lifted` and an animated halo when `attention="auto"`
+ *   and the descriptor is available, so the button outranks every
+ *   other element in its peripheral neighbourhood.
+ * - **Peak-end** — when the action becomes available (handle flips
+ *   from disabled → enabled), the halo pulses for one breath cycle
+ *   so the eye finds the change without re-scanning the screen.
+ * - **Doherty / responsiveness** — clicks set an internal `pending`
+ *   flag the moment submit fires so the button visibly absorbs the
+ *   tap, even on slow networks. Throwing submitters are swallowed
+ *   here for the same reason `<DefaultInteractionButton>` does:
+ *   descriptor availability is authoritative.
+ * - **Accessibility** — minimum 56×56 hit area satisfies WCAG 2.5.5.
+ *   `prefers-reduced-motion` zeroes out the halo and press
+ *   transitions through the theme's `motion.reducedMotion` token.
+ */
+
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import { motion } from "framer-motion";
+import { useTheme } from "../theme/ThemeProvider.js";
+import {
+  intentForVariant,
+  type ButtonSize,
+  type ButtonVariant,
+} from "../theme/derive.js";
+import type {
+  InteractionHandle,
+  InteractionParamsShape,
+} from "../hooks/useInteractionHandle.js";
+import { interactionLabel } from "../utils/interaction-labels.js";
+import { ThemedButton } from "./ThemedButton.js";
+import type { SubmittedActionConfig } from "./surfaces/internal/DefaultInteractionButton.js";
+
+/** Attention-pulse policy for the trailing halo. */
+export type PrimaryActionAttention = "auto" | "always" | "off";
+
+export interface PrimaryActionButtonProps<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+> {
+  /**
+   * Bound interaction handle (typically from `useInteractionByKey`).
+   * The button mirrors `descriptor.label`, disables itself when the
+   * descriptor is unavailable, surfaces `unavailableReason` as a
+   * tooltip, and submits explicit `params` or the current draft on click.
+   */
+  handle: InteractionHandle<Params>;
+  /**
+   * Override the visual variant. Defaults to `primary` (which maps
+   * to `intent.primary` regardless of the descriptor's `emphasis`
+   * hint — the shell's primary slot is, by definition, primary).
+   */
+  variant?: ButtonVariant;
+  /**
+   * Sizing. Defaults to `lg` so the dock target is comfortable on
+   * touch and visually outranks panel buttons sized `md`.
+   */
+  size?: ButtonSize;
+  /**
+   * Override the label inferred from `descriptor.label`. Use only
+   * when the descriptor's label needs phase-specific copy that the
+   * authoring layer can't express.
+   */
+  label?: ReactNode;
+  /** Client-side draft readiness. Reducer availability remains authoritative. */
+  ready?: boolean;
+  /** Copy and visual overrides once this interaction has been submitted. */
+  whenSubmitted?: SubmittedActionConfig;
+  /**
+   * Optional leading icon override. When omitted, falls back to
+   * `descriptor.icon` (an emoji glyph from the authoring spec).
+   */
+  icon?: ReactNode;
+  /**
+   * Submit params forwarded to `handle.submit`. When omitted, the button
+   * submits the handle's current draft via `handle.submitDraft()`.
+   */
+  params?: Record<string, unknown>;
+  /**
+   * Attention-halo policy. `auto` (default) pulses the halo for one
+   * breath when the button transitions from disabled → enabled (so
+   * the user sees the moment the action becomes available), then
+   * settles into a slow ambient breath while the action remains
+   * available. `always` keeps the breath running unconditionally.
+   * `off` suppresses the halo entirely.
+   *
+   * Ignored when `theme.motion.reducedMotion === "true"`.
+   */
+  attention?: PrimaryActionAttention;
+  /** Additional inline style merged after the resolved button style. */
+  style?: CSSProperties;
+  /** Optional className for downstream styling hooks. */
+  className?: string;
+}
+
+/**
+ * @see PrimaryActionButtonProps
+ */
+export function PrimaryActionButton<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+>({
+  handle,
+  variant = "primary",
+  size = "lg",
+  label,
+  ready = true,
+  whenSubmitted,
+  icon,
+  params,
+  attention = "auto",
+  style,
+  className,
+}: PrimaryActionButtonProps<Params>) {
+  const theme = useTheme();
+  const reducedMotion = theme.motion.reducedMotion === "true";
+  const [pending, setPending] = useState(false);
+
+  const descriptor = handle.descriptor;
+  const submitted = handle.status === "submitted";
+  const submitting = handle.status === "submitting" || pending;
+  const available = descriptor.available && ready && !submitted && !submitting;
+  const resolvedVariant = submitted
+    ? (whenSubmitted?.variant ?? "submitted")
+    : variant;
+  const disabled = !available;
+  const intent = intentForVariant(theme, resolvedVariant);
+
+  // Pulse the halo for one breath when availability flips on. After
+  // the breath we settle into the ambient cadence (or stop, when
+  // `attention` is `off`). Tracking the previous availability lets
+  // us catch the transition without re-mounting the component.
+  const previouslyAvailableRef = useRef(available);
+  const [pulseKey, setPulseKey] = useState(0);
+  useEffect(() => {
+    if (!previouslyAvailableRef.current && available) {
+      setPulseKey((n) => n + 1);
+    }
+    previouslyAvailableRef.current = available;
+  }, [available]);
+
+  const haloEnabled =
+    !reducedMotion && available && attention !== "off" && !submitted;
+
+  const fallbackLabel = interactionLabel(descriptor);
+  const tooltip = available
+    ? undefined
+    : formatUnavailableReason(descriptor.unavailableReason);
+
+  const resolvedLabel: ReactNode = submitted
+    ? (whenSubmitted?.label ?? label ?? fallbackLabel)
+    : (label ?? fallbackLabel);
+  const resolvedIcon: ReactNode =
+    submitted && whenSubmitted?.icon ? (
+      <span aria-hidden style={{ fontSize: "1.15em" }}>
+        {whenSubmitted.icon}
+      </span>
+    ) : (
+      (icon ?? null)
+    );
+
+  return (
+    <span
+      data-dreamboard-primary-action
+      data-available={available ? "true" : "false"}
+      data-pending={submitting ? "true" : undefined}
+      data-action-state={
+        submitted
+          ? "submitted"
+          : submitting
+            ? "submitting"
+            : available
+              ? "available"
+              : "unavailable"
+      }
+      style={{
+        position: "relative",
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        // The halo overflows the button bounds; the wrapper reserves
+        // a transparent buffer so it doesn't get clipped by the
+        // dock's safe-area frame.
+        padding: theme.space[1],
+      }}
+    >
+      {haloEnabled ? (
+        <>
+          {/*
+            Ambient breath — slow, low-amplitude, runs as long as the
+            action is available. The outer `haloEnabled` already
+            short-circuits when `attention === "off"`, so this layer
+            is gated purely on the availability + reduced-motion
+            checks.
+          */}
+          <motion.span
+            aria-hidden
+            style={{
+              position: "absolute",
+              inset: 0,
+              borderRadius: theme.radius.md,
+              background: intent.soft,
+              opacity: 0.55,
+              pointerEvents: "none",
+            }}
+            animate={{
+              scale: [1, 1.06, 1],
+              opacity: [0.45, 0.18, 0.45],
+            }}
+            transition={{
+              repeat: Infinity,
+              duration: 2.4,
+              ease: "easeInOut",
+            }}
+          />
+          {/*
+            One-shot announce pulse keyed on `pulseKey` — re-mounts
+            (and thus re-runs) every time availability flips on so the
+            eye registers the change. We use a separate layer (rather
+            than retriggering the ambient breath) so the announce is
+            visibly louder than the steady-state cadence.
+          */}
+          <motion.span
+            key={pulseKey}
+            aria-hidden
+            style={{
+              position: "absolute",
+              inset: 0,
+              borderRadius: theme.radius.md,
+              boxShadow: `0 0 0 0 ${intent.solid}`,
+              pointerEvents: "none",
+            }}
+            initial={{ opacity: 0.7 }}
+            animate={{
+              boxShadow: [
+                `0 0 0 0 ${withAlpha(intent.solid, 0.55)}`,
+                `0 0 0 14px ${withAlpha(intent.solid, 0)}`,
+              ],
+              opacity: [0.7, 0],
+            }}
+            transition={{ duration: 0.9, ease: "easeOut" }}
+          />
+        </>
+      ) : null}
+      <ThemedButton
+        type="button"
+        variant={resolvedVariant}
+        size={size}
+        pressed={submitting}
+        className={className}
+        aria-label={
+          typeof resolvedLabel === "string" ? resolvedLabel : fallbackLabel
+        }
+        aria-disabled={disabled || undefined}
+        data-interaction-id={descriptor.interactionId}
+        data-emphasis="primary"
+        title={tooltip}
+        disabled={disabled}
+        style={{
+          // Sit above the halo so clicks land on the button.
+          position: "relative",
+          zIndex: 1,
+          boxShadow: disabled || submitted ? undefined : theme.elevation.lifted,
+          ...style,
+        }}
+        onClick={async (event) => {
+          event.preventDefault();
+          if (disabled) return;
+          setPending(true);
+          try {
+            if (params !== undefined) {
+              await handle.submit(params as Params);
+            } else {
+              await handle.submitDraft();
+            }
+          } catch {
+            // Descriptor availability is authoritative; submit errors
+            // surface via the runtime's error channel.
+          } finally {
+            setPending(false);
+          }
+        }}
+      >
+        {resolvedIcon}
+        <span>{resolvedLabel}</span>
+      </ThemedButton>
+    </span>
+  );
+}
+
+function formatUnavailableReason(
+  reason: string | undefined,
+): string | undefined {
+  if (reason === "INSUFFICIENT_RESOURCES") {
+    return "Insufficient resources";
+  }
+  return reason;
+}
+
+/**
+ * Add an alpha channel to a CSS colour string. Supports `#rgb`,
+ * `#rrggbb`, and any colour the browser can paint via a fallback to
+ * `color-mix` (modern Safari/Chrome/Firefox all support this; older
+ * runtimes get the original colour without alpha which is still
+ * visible — the halo is decorative).
+ */
+function withAlpha(color: string, alpha: number): string {
+  const trimmed = color.trim();
+  if (trimmed.startsWith("#")) {
+    const hex = trimmed.slice(1);
+    if (hex.length === 3) {
+      // `String.prototype.slice` always returns a string (possibly
+      // empty) — never `undefined` — so duplicating each digit is
+      // safe to feed to `parseInt` without further narrowing.
+      const r = parseInt(hex.slice(0, 1).repeat(2), 16);
+      const g = parseInt(hex.slice(1, 2).repeat(2), 16);
+      const b = parseInt(hex.slice(2, 3).repeat(2), 16);
+      return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+    }
+    if (hex.length === 6) {
+      const r = parseInt(hex.slice(0, 2), 16);
+      const g = parseInt(hex.slice(2, 4), 16);
+      const b = parseInt(hex.slice(4, 6), 16);
+      return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+    }
+  }
+  // Best-effort fallback for non-hex colours (rgb/hsl/named): use
+  // `color-mix` with transparent. Safe to land in inline style — the
+  // halo is purely decorative and will gracefully degrade.
+  return `color-mix(in srgb, ${trimmed} ${Math.round(alpha * 100)}%, transparent)`;
+}

package/src/components/PrimaryButton.tsx

@@ -0,0 +1,44 @@
+/**
+ * Minimally-styled primary action button.
+ *
+ * Visual styling now flows through {@link buttonStyle}: the background,
+ * border, foreground, radius, typography and elevation all derive from
+ * the active {@link useTheme}'s `intent.primary` slot. Override the
+ * variant when a non-primary call site needs a different emphasis (the
+ * underlying `<DefaultInteractionButton>` is the canonical button for
+ * interaction-bound submission).
+ */
+
+import type { ButtonHTMLAttributes } from "react";
+import type { ButtonSize, ButtonVariant } from "../theme/derive.js";
+import { ThemedButton } from "./ThemedButton.js";
+
+export interface PrimaryButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Intent slot — defaults to `primary`. */
+  variant?: ButtonVariant;
+  /** Sizing token — defaults to `md`. */
+  size?: ButtonSize;
+}
+
+export function PrimaryButton({
+  children,
+  disabled,
+  style,
+  variant = "primary",
+  size = "md",
+  ...rest
+}: PrimaryButtonProps) {
+  return (
+    <ThemedButton
+      type="button"
+      disabled={disabled}
+      variant={variant}
+      size={size}
+      style={style}
+      {...rest}
+    >
+      {children}
+    </ThemedButton>
+  );
+}