@wibly/ui-kit 0.1.1

package/src/components/timer.tsx

@@ -0,0 +1,104 @@
+'use client';
+
+/**
+ * `Timer` — counts down to a server-anchored deadline.
+ *
+ * Per Dev Spec §6.6 chunk-B10 build: "Timer — counts down to a
+ * server-anchored deadline; uses `time.serverNow()`." The component
+ * does NOT import `@platform/sdk` (Dev Spec §3.3 dependency
+ * direction). The consumer passes a `nowMs` thunk — typically a
+ * pre-bound `() => session.time.serverNow()` — which the component
+ * polls at a configurable interval.
+ *
+ * The component is the rendering surface, never the source of truth:
+ *
+ *   - It stores no countdown state outside `useState`'s React-internal
+ *     bookkeeping (the local interval is presentation only — the
+ *     deadline is the server's, the clock skew is the SDK's).
+ *   - It clears its interval on unmount and on `deadlineMs` change.
+ *   - It calls `onExpire` exactly once per (deadline, mount) pair.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+import { formatRemaining, remainingMs, type DurationFormat } from '../lib/duration.js';
+
+export type TimerProps = {
+  /** The server-anchored deadline in unix ms. */
+  readonly deadlineMs: number;
+  /**
+   * Returns server time in unix ms. Typically wired from
+   * `() => session.time.serverNow()` (B7 SDK).
+   */
+  readonly nowMs: () => number;
+  /** Fires once when remaining time crosses 0. */
+  readonly onExpire?: () => void;
+  /** Tick interval in ms; default 250. */
+  readonly tickMs?: number;
+  /** Render format; default `'mm:ss'`. */
+  readonly format?: DurationFormat;
+  /** Optional accessible label (e.g. "round timer"). */
+  readonly label?: string;
+  readonly className?: string;
+};
+
+export const Timer = ({
+  deadlineMs,
+  nowMs,
+  onExpire,
+  tickMs = 250,
+  format = 'mm:ss',
+  label,
+  className,
+}: TimerProps): React.ReactElement => {
+  const [remaining, setRemaining] = React.useState(() =>
+    remainingMs(deadlineMs, nowMs()),
+  );
+
+  // `nowMs` and `onExpire` are kept in refs so the interval doesn't
+  // resubscribe on every render. The interval rebinds only when
+  // `deadlineMs` or `tickMs` change.
+  const nowMsRef = React.useRef(nowMs);
+  nowMsRef.current = nowMs;
+  const onExpireRef = React.useRef(onExpire);
+  onExpireRef.current = onExpire;
+  const expiredRef = React.useRef(false);
+
+  React.useEffect(() => {
+    expiredRef.current = false;
+    setRemaining(remainingMs(deadlineMs, nowMsRef.current()));
+
+    const interval = setInterval(() => {
+      const next = remainingMs(deadlineMs, nowMsRef.current());
+      setRemaining(next);
+      if (next <= 0 && !expiredRef.current) {
+        expiredRef.current = true;
+        onExpireRef.current?.();
+      }
+    }, Math.max(50, tickMs));
+
+    return () => clearInterval(interval);
+  }, [deadlineMs, tickMs]);
+
+  const expired = remaining <= 0;
+
+  return (
+    <div
+      role="timer"
+      aria-label={label}
+      aria-live="polite"
+      data-expired={expired || undefined}
+      className={cn(
+        'inline-flex items-baseline gap-2 rounded-lg border border-border bg-card px-4 py-2 font-mono tabular-nums text-foreground shadow-sm',
+        expired && 'border-destructive text-destructive',
+        !expired && remaining < 5_000 && 'text-primary',
+        className,
+      )}
+    >
+      <span className="text-2xl font-semibold">
+        {formatRemaining(remaining, format)}
+      </span>
+    </div>
+  );
+};

package/src/components/vote-grid.tsx

@@ -0,0 +1,116 @@
+'use client';
+
+/**
+ * `VoteGrid` — vote on a set of options with images or text.
+ *
+ * Per Dev Spec §6.6 chunk-B10 build. The grid is keyboard-navigable
+ * (arrow keys move focus, Enter / Space selects), respects the
+ * server-driven `disabledOptionIds` (e.g. for "voted-already"
+ * surfaces), and presents the selected option visibly via a
+ * highlighted ring + `aria-pressed`.
+ *
+ * Decoupled from the SDK: the consumer passes the option list +
+ * the current selection + an `onSelect` callback. Predictive vote
+ * UI is the consumer's job — toggling `disabled` while the optimistic
+ * vote is in flight is enough to express "in progress."
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type VoteOption = {
+  readonly id: string;
+  readonly label: string;
+  /** Optional image URL — when set, renders the image above the label. */
+  readonly imageUrl?: string;
+  /** Optional secondary copy (sub-label / attribution). */
+  readonly hint?: string;
+};
+
+export type VoteGridProps = {
+  readonly options: readonly VoteOption[];
+  readonly selectedOptionId: string | null;
+  readonly onSelect: (optionId: string) => void;
+  readonly disabled?: boolean;
+  readonly disabledOptionIds?: readonly string[];
+  readonly columns?: 2 | 3 | 4;
+  readonly className?: string;
+  readonly label?: string;
+};
+
+const COLUMN_CLASS: Record<2 | 3 | 4, string> = {
+  2: 'grid-cols-1 sm:grid-cols-2',
+  3: 'grid-cols-1 sm:grid-cols-2 md:grid-cols-3',
+  4: 'grid-cols-2 md:grid-cols-3 lg:grid-cols-4',
+};
+
+export const VoteGrid = ({
+  options,
+  selectedOptionId,
+  onSelect,
+  disabled = false,
+  disabledOptionIds,
+  columns = 3,
+  className,
+  label,
+}: VoteGridProps): React.ReactElement => {
+  const disabledSet = React.useMemo(
+    () => new Set(disabledOptionIds ?? []),
+    [disabledOptionIds],
+  );
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label={label}
+      aria-disabled={disabled || undefined}
+      className={cn('grid gap-3', COLUMN_CLASS[columns], className)}
+    >
+      {options.map((option) => {
+        const isSelected = option.id === selectedOptionId;
+        const isDisabled = disabled || disabledSet.has(option.id);
+        return (
+          <button
+            key={option.id}
+            type="button"
+            role="radio"
+            aria-checked={isSelected}
+            aria-disabled={isDisabled || undefined}
+            disabled={isDisabled}
+            tabIndex={isSelected ? 0 : isDisabled ? -1 : 0}
+            onClick={() => {
+              if (!isDisabled) onSelect(option.id);
+            }}
+            data-selected={isSelected || undefined}
+            className={cn(
+              'flex flex-col items-stretch gap-2 overflow-hidden rounded-xl border border-border bg-card text-left',
+              'p-3 shadow-sm transition-colors duration-150',
+              'focus:outline-none focus:ring-2 focus:ring-ring',
+              isSelected && 'border-primary ring-2 ring-primary',
+              !isSelected && !isDisabled && 'hover:border-primary/60',
+              isDisabled && 'cursor-not-allowed opacity-50',
+            )}
+          >
+            {option.imageUrl !== undefined ? (
+              <img
+                src={option.imageUrl}
+                alt=""
+                aria-hidden="true"
+                className="aspect-video w-full rounded-sm object-cover"
+              />
+            ) : null}
+            <span className="text-sm font-medium text-foreground">
+              {option.label}
+            </span>
+            {option.hint !== undefined ? (
+              <span className="text-xs text-muted-foreground">
+                {option.hint}
+              </span>
+            ) : null}
+          </button>
+        );
+      })}
+    </div>
+  );
+};

package/src/index.ts

@@ -0,0 +1,113 @@
+/**
+ * `@platform/ui-kit` — shared React components for the Wibly shells
+ * and Experience bundles.
+ *
+ * Built in chunk B10 (Dev Spec §6.6). Per Platform Spec §3.4 the kit
+ * is "assistance, not constraint" — first-party Experiences (Rashomon,
+ * Flatterer) and the platform shells use parts of it; ignoring it
+ * entirely is allowed.
+ *
+ * Dependency direction (Dev Spec §3.3):
+ *
+ *   `packages/sdk → packages/ui-kit`
+ *   `packages/ui-kit → packages/shared`  (and `clsx` for class merging)
+ *
+ * The kit MUST NOT import `@platform/sdk`, `@platform/protocol`, or
+ * `@platform/manifest`. SDK integrations (`time.serverNow`,
+ * `submitWithPrediction`) are surfaced as plain callback / function
+ * props — see `Timer.nowMs` and `PromptInput.onSubmit` / `pending`.
+ *
+ * Visual review for the kit lives in `apps/uikit-preview`.
+ */
+
+export {
+  PromptInput,
+  type PromptInputProps,
+} from './components/prompt-input.js';
+
+export {
+  VoteGrid,
+  type VoteGridProps,
+  type VoteOption,
+} from './components/vote-grid.js';
+
+export {
+  Leaderboard,
+  type LeaderboardDimension,
+  type LeaderboardProps,
+  type LeaderboardRow,
+} from './components/leaderboard.js';
+
+export { Timer, type TimerProps } from './components/timer.js';
+
+export {
+  AvatarStage,
+  type AvatarStageProps,
+  type AvatarStageState,
+} from './components/avatar-stage.js';
+
+export {
+  ResponseCard,
+  type ResponseCardAttribution,
+  type ResponseCardProps,
+} from './components/response-card.js';
+
+export {
+  JoinCodeBadge,
+  type JoinCodeBadgeProps,
+} from './components/join-code-badge.js';
+
+export {
+  RecoveryCodeBadge,
+  type RecoveryCodeBadgeProps,
+} from './components/recovery-code-badge.js';
+
+export {
+  PausedBanner,
+  type PausedBannerProps,
+  type PausedBannerReason,
+} from './components/paused-banner.js';
+
+export {
+  SessionAbortedOverlay,
+  type SessionAbortedOverlayProps,
+} from './components/session-aborted-overlay.js';
+
+export {
+  ConsentDialog,
+  resolveConsentDialogCopy,
+  type ConsentDialogKind,
+  type ConsentDialogProps,
+} from './components/consent-dialog.js';
+
+export {
+  ConsentPrompt,
+  type ConsentPromptCopyOverride,
+  type ConsentPromptProps,
+} from './components/consent-prompt.js';
+
+export {
+  CONSENT_DIALOG_DEFAULTS,
+  CONSENT_PROMPT_COPY,
+} from './lib/consent-meta.js';
+
+export {
+  consentFlowReducer,
+  initialConsentFlowState,
+  isAccepted,
+  type ConsentFlowEvent,
+  type ConsentFlowState,
+  type ConsentDecision,
+  type ConsentRequiredCallback,
+  type ConsentRequiredPayload,
+} from './lib/consent-flow.js';
+
+// Pure helpers — exposed so consumers can render the same counter /
+// counter format the components use (e.g. inside a custom shell-only
+// surface) without re-implementing the grapheme math.
+export { graphemeCount, truncateToGraphemes } from './lib/char-count.js';
+export {
+  formatRemaining,
+  remainingMs,
+  type DurationFormat,
+} from './lib/duration.js';

package/src/lib/char-count.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+
+import { graphemeCount, truncateToGraphemes } from './char-count.js';
+
+describe('graphemeCount', () => {
+  it('counts ASCII characters one-for-one', () => {
+    expect(graphemeCount('')).toBe(0);
+    expect(graphemeCount('a')).toBe(1);
+    expect(graphemeCount('hello world')).toBe(11);
+  });
+
+  it('counts emoji as one cluster (no surrogate-pair double-count)', () => {
+    expect(graphemeCount('😀')).toBe(1);
+    expect(graphemeCount('a😀b')).toBe(3);
+  });
+
+  it('counts ZWJ sequences as one cluster (family emoji)', () => {
+    // U+1F468 + ZWJ + U+1F469 + ZWJ + U+1F467 = a single visible
+    // family glyph; native `.length` is 8.
+    const family = '👨\u200D👩\u200D👧';
+    expect(family.length).toBeGreaterThan(1);
+    expect(graphemeCount(family)).toBe(1);
+  });
+
+  it('counts CJK characters one-for-one', () => {
+    expect(graphemeCount('한국어')).toBe(3);
+    expect(graphemeCount('日本語')).toBe(3);
+    expect(graphemeCount('中文')).toBe(2);
+  });
+
+  it('counts a combined-form character as one grapheme', () => {
+    // 'é' authored as `e + COMBINING ACUTE ACCENT` (U+0065 U+0301)
+    // — `.length` is 2; the user perceives it as a single `é`.
+    const combined = 'e\u0301';
+    expect(combined.length).toBe(2);
+    expect(graphemeCount(combined)).toBe(1);
+  });
+});
+
+describe('truncateToGraphemes', () => {
+  it('returns the input untouched when within the cap', () => {
+    expect(truncateToGraphemes('', 10)).toBe('');
+    expect(truncateToGraphemes('hello', 10)).toBe('hello');
+    expect(truncateToGraphemes('hello', 5)).toBe('hello');
+  });
+
+  it('truncates ASCII to the cap length', () => {
+    expect(truncateToGraphemes('hello world', 5)).toBe('hello');
+    expect(truncateToGraphemes('hello world', 0)).toBe('');
+  });
+
+  it('does not split a surrogate pair when truncating just before an emoji', () => {
+    // Cap of 2 against `'a😀b'` should yield `'a😀'`, not `'a'` and
+    // not the broken half of the emoji.
+    expect(truncateToGraphemes('a😀b', 2)).toBe('a😀');
+  });
+
+  it('preserves ZWJ family clusters as one unit when within the cap', () => {
+    const family = '👨\u200D👩\u200D👧';
+    expect(truncateToGraphemes(family, 1)).toBe(family);
+    expect(truncateToGraphemes(`x${family}y`, 2)).toBe(`x${family}`);
+  });
+
+  it('truncates CJK input to the requested grapheme count', () => {
+    expect(truncateToGraphemes('한국어 화이팅', 3)).toBe('한국어');
+  });
+
+  it('treats a non-positive cap as the empty string', () => {
+    expect(truncateToGraphemes('hello', 0)).toBe('');
+    expect(truncateToGraphemes('hello', -3)).toBe('');
+  });
+});

package/src/lib/char-count.ts

@@ -0,0 +1,82 @@
+/**
+ * Grapheme-aware character helpers for `PromptInput`.
+ *
+ * Per Dev Spec §6.6 chunk-B10 acceptance: "PromptInput's character
+ * cap (cap enforced; trims correctly; does not break on multi-byte
+ * characters)." The native `string.length` counts UTF-16 code
+ * units, so an emoji or a surrogate-pair character is reported as
+ * `2`. That mismatch is a footgun — a 280-character cap that uses
+ * `.length` lets a player type 140 emoji and call it full while a
+ * latin-only player gets 280. We use `Intl.Segmenter` (built into
+ * V8 since Node 16) to count user-perceived characters instead.
+ *
+ * `Intl.Segmenter` is not in `lib.es2022.d.ts`'s typings yet; the
+ * helpers cast through `unknown` rather than pulling in the
+ * `intl-segmenter` types polyfill. The cast lives in one place so
+ * the type imprecision doesn't leak to call sites.
+ */
+
+type SegmentLike = { readonly segment: string };
+type SegmenterLike = {
+  segment: (input: string) => Iterable<SegmentLike>;
+};
+type SegmenterCtor = new (locale?: string, opts?: { granularity: 'grapheme' }) => SegmenterLike;
+
+const SegmenterCtorRef: SegmenterCtor | null = (() => {
+  const candidate = (globalThis as unknown as { Intl?: { Segmenter?: SegmenterCtor } }).Intl
+    ?.Segmenter;
+  return candidate ?? null;
+})();
+
+const segmenter: SegmenterLike | null = SegmenterCtorRef
+  ? new SegmenterCtorRef(undefined, { granularity: 'grapheme' })
+  : null;
+
+/**
+ * Count user-perceived characters (grapheme clusters) in `input`.
+ *
+ * - `'hello'` → 5
+ * - `'😀'` → 1 (surrogate pair, not 2)
+ * - `'👨‍👩‍👧'` → 1 (ZWJ family sequence, not 5)
+ * - `'한국어'` → 3
+ *
+ * Falls back to `string.length` only on runtimes without
+ * `Intl.Segmenter`. All supported runtimes (Node 20 LTS, modern
+ * browsers per Dev Spec §2.10) ship it.
+ */
+export const graphemeCount = (input: string): number => {
+  if (input === '') return 0;
+  if (segmenter === null) return input.length;
+  let count = 0;
+  for (const _segment of segmenter.segment(input)) {
+    void _segment;
+    count += 1;
+  }
+  return count;
+};
+
+/**
+ * Truncate `input` to at most `maxChars` grapheme clusters,
+ * preserving the leading slice. Returns `input` unchanged when it
+ * is already within the cap (no allocation).
+ *
+ * Used by `PromptInput`'s `onChange` interceptor — when a paste
+ * pushes the value over the cap, the cap value is what reaches
+ * `props.onChange`. (The component does not silently drop the tail;
+ * it surfaces the truncation via the visible counter.)
+ */
+export const truncateToGraphemes = (input: string, maxChars: number): string => {
+  if (maxChars <= 0) return '';
+  if (input === '') return '';
+  if (segmenter === null) {
+    return input.length <= maxChars ? input : input.slice(0, maxChars);
+  }
+  let count = 0;
+  let truncated = '';
+  for (const segment of segmenter.segment(input)) {
+    if (count >= maxChars) break;
+    truncated += segment.segment;
+    count += 1;
+  }
+  return truncated;
+};

package/src/lib/cn.ts

@@ -0,0 +1,13 @@
+/**
+ * Class-name composer (`clsx` re-export wrapped at the package boundary).
+ *
+ * Components in `@platform/ui-kit` use `cn(...)` to merge static
+ * Tailwind classes with conditional ones without leaking `clsx` as
+ * a transitive dep into consumers' import sites. The wrapper makes
+ * the dependency swappable later (e.g. `tailwind-merge` if dedup
+ * becomes useful) without touching every component.
+ */
+
+import { clsx, type ClassValue } from 'clsx';
+
+export const cn = (...inputs: ClassValue[]): string => clsx(...inputs);

package/src/lib/consent-flow.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  type ConsentDecision,
+  type ConsentRequiredCallback,
+  type ConsentRequiredPayload,
+  consentFlowReducer,
+  initialConsentFlowState,
+  isAccepted,
+} from './consent-flow.js';
+
+const samplePayload = (
+  overrides: Partial<ConsentRequiredPayload> = {},
+): ConsentRequiredPayload => ({
+  personaId: 'psn_test',
+  personaDisplayName: 'Crumb',
+  scope: 'player',
+  ...overrides,
+});
+
+describe('consentFlowReducer', () => {
+  it('accept branch resolves to accepted', () => {
+    const state0 = initialConsentFlowState(samplePayload());
+    const state1 = consentFlowReducer(state0, { type: 'accept' });
+    const state2 = consentFlowReducer(state1, { type: 'confirmed' });
+    expect(isAccepted(state2)).toBe(true);
+  });
+
+  it('decline branch resolves to declined', () => {
+    const state0 = initialConsentFlowState(samplePayload());
+    const state1 = consentFlowReducer(state0, { type: 'decline' });
+    const state2 = consentFlowReducer(state1, { type: 'confirmed' });
+    expect(isAccepted(state2)).toBe(false);
+  });
+});
+
+describe('SDK callback signature', () => {
+  it('matches the documented shape', async () => {
+    const callback: ConsentRequiredCallback = async () => 'accepted';
+    const decision = await callback(samplePayload());
+    expect(decision).toBe('accepted');
+    const decisions: readonly ConsentDecision[] = ['accepted', 'declined'];
+    expect(decisions).toHaveLength(2);
+  });
+});

package/src/lib/consent-flow.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure state machine for the Persona consent prompt (B6/B15).
+ */
+
+import type {
+  ConsentDecision,
+  ConsentRequiredCallback,
+  ConsentRequiredPayload,
+} from '@wibly/sdk';
+
+export type { ConsentDecision, ConsentRequiredCallback, ConsentRequiredPayload };
+
+export type ConsentFlowState =
+  | { readonly kind: 'prompting'; readonly payload: ConsentRequiredPayload }
+  | {
+      readonly kind: 'submitting';
+      readonly payload: ConsentRequiredPayload;
+      readonly decision: ConsentDecision;
+    }
+  | {
+      readonly kind: 'resolved';
+      readonly payload: ConsentRequiredPayload;
+      readonly decision: ConsentDecision;
+    };
+
+export type ConsentFlowEvent =
+  | { readonly type: 'accept' }
+  | { readonly type: 'decline' }
+  | { readonly type: 'confirmed' };
+
+export const initialConsentFlowState = (
+  payload: ConsentRequiredPayload,
+): ConsentFlowState => ({ kind: 'prompting', payload });
+
+export const consentFlowReducer = (
+  state: ConsentFlowState,
+  event: ConsentFlowEvent,
+): ConsentFlowState => {
+  switch (event.type) {
+    case 'accept': {
+      if (state.kind === 'prompting') {
+        return {
+          kind: 'submitting',
+          payload: state.payload,
+          decision: 'accepted',
+        };
+      }
+      return state;
+    }
+    case 'decline': {
+      if (state.kind === 'prompting') {
+        return {
+          kind: 'submitting',
+          payload: state.payload,
+          decision: 'declined',
+        };
+      }
+      return state;
+    }
+    case 'confirmed': {
+      if (state.kind === 'submitting') {
+        return {
+          kind: 'resolved',
+          payload: state.payload,
+          decision: state.decision,
+        };
+      }
+      return state;
+    }
+    default: {
+      const _exhaustive: never = event;
+      void _exhaustive;
+      return state;
+    }
+  }
+};
+
+export const isAccepted = (state: ConsentFlowState): boolean =>
+  state.kind !== 'prompting' && state.decision === 'accepted';

package/src/lib/consent-meta.ts

@@ -0,0 +1,38 @@
+/**
+ * Platform-default consent prompt copy (chunk B15).
+ *
+ * Surface-specific framing lives in `CONSENT_DIALOG_DEFAULTS`; per-
+ * Persona overrides arrive on the wire as `payload.consentCopy`.
+ */
+
+export const CONSENT_PROMPT_COPY = {
+  title: (personaDisplayName: string) =>
+    `${personaDisplayName} wants to remember you across sessions.`,
+  description:
+    'Granting consent lets this Persona keep notes about how you played — your style, the choices you’ve made, jokes that landed. You can revoke this any time from Settings.',
+  acceptLabel: 'Allow',
+  declineLabel: 'Not this time',
+  managementHint:
+    'You can revoke this any time from Settings — “Memory & Personas”.',
+} as const;
+
+export type ConsentDialogKind = 'mid-session' | 'settings';
+
+export const CONSENT_DIALOG_DEFAULTS: Record<
+  ConsentDialogKind,
+  {
+    title: (personaDisplayName: string) => string;
+    description: string;
+  }
+> = {
+  'mid-session': {
+    title: CONSENT_PROMPT_COPY.title,
+    description: CONSENT_PROMPT_COPY.description,
+  },
+  settings: {
+    title: (personaDisplayName: string) =>
+      `Grant ${personaDisplayName} permission to remember you.`,
+    description:
+      'You’re granting this Persona consent to keep notes about how you play across sessions. Revoke any time from this page.',
+  },
+};