@wibly/sdk 0.1.0

package/src/predictive.ts

@@ -0,0 +1,51 @@
+/**
+ * Predictive (optimistic) rendering helpers.
+ *
+ * Per chunk B7 build: "predictive.ts — optimistic update helpers for
+ * fast UI feedback. Apply a local projection, then reconcile against
+ * the next state_diff. Roll back if the server rejected the input."
+ *
+ * The flow is:
+ *
+ *   1. The caller invokes `session.submitWithPrediction(input,
+ *      projection)`. The SDK stamps a fresh `msg_…` id, registers
+ *      `projection` against that id in the store, and sends the
+ *      `submit` envelope.
+ *
+ *   2. The server emits a matching `state_diff` (the side effect of
+ *      the submit). The SDK removes the projection on receipt — the
+ *      authoritative state now reflects the change.
+ *
+ *   3. If the server emits an `error` with `causeMessageId === id`,
+ *      the SDK rolls back the projection (drops it without applying)
+ *      and surfaces the error to the caller as `submit_rejected`.
+ *
+ * The chunk-B7 trap is "Don't try to invent predictive logic outside
+ * of `predictive.ts`." Anything that needs to know about pending
+ * projections (the React view layer, the testkit's envelope assertion)
+ * imports from this module.
+ */
+
+import type { OptimisticProjection, SessionStore } from './store.js';
+
+export type PendingProjectionHandle = {
+  /** Envelope id that the projection is tied to. */
+  readonly id: string;
+  /** Forced rollback (drop the projection without applying it). */
+  readonly rollback: () => void;
+  /** Forced commit (drop the projection — server confirmed). */
+  readonly commit: () => void;
+};
+
+export const registerProjection = (
+  store: SessionStore,
+  id: string,
+  projection: OptimisticProjection,
+): PendingProjectionHandle => {
+  store.addProjection(id, projection);
+  return {
+    id,
+    rollback: () => store.removeProjection(id),
+    commit: () => store.removeProjection(id),
+  };
+};

package/src/react.ts

@@ -0,0 +1,223 @@
+/**
+ * React bindings for the Studio SDK.
+ *
+ * Per chunk B7 build: "state.ts — reactive state subscription.
+ * Returns React hooks that read from a synchronised store: …
+ * `useSessionState()`, `useSessionEvent(eventType)`,
+ * `useConnectionState()`."
+ *
+ * The hooks are surface-thin — they use `useSyncExternalStore`
+ * against the session's store / event bus and otherwise stay out of
+ * the way. The chunk-B7 trap is "Don't try to invent predictive
+ * logic outside of `predictive.ts`. Don't let the AI inline state
+ * stores per call site." The hooks read from the session-owned
+ * store; they never construct their own.
+ *
+ * The `react` peer-dependency is **optional** (see `package.json`'s
+ * `peerDependenciesMeta`). Consumers using the SDK from a non-React
+ * shell (a node script, a CLI) can import everything from the SDK
+ * root without pulling React into the bundle.
+ */
+
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from 'react';
+
+import type { EventPayload, LifecyclePayload } from '@wibly/internal-protocol';
+
+import type { ConsentDecision, ConsentRequiredPayload } from './consent.js';
+import type { Session, SessionState } from './client.js';
+
+const SessionContext = createContext<Session | null>(null);
+
+export type SessionProviderProps = {
+  readonly session: Session;
+  readonly children: ReactNode;
+};
+
+/**
+ * Provider that exposes a `Session` to the React tree. The host
+ * component creates the session via `createSession(...)` and wraps
+ * its tree once — every hook below reads from this provider.
+ */
+export const SessionProvider = (props: SessionProviderProps): ReactNode =>
+  createElement(
+    SessionContext.Provider,
+    { value: props.session },
+    props.children,
+  );
+
+/**
+ * Access the live `Session`. Throws if no provider is mounted (a
+ * deliberate fail-fast — the alternative is a silent null that
+ * makes every downstream hook misbehave).
+ */
+export const useSession = (): Session => {
+  const session = useContext(SessionContext);
+  if (session === null) {
+    throw new Error(
+      'useSession: no <SessionProvider> in the React tree. ' +
+        'Wrap the tree that uses SDK hooks in <SessionProvider session={...}>.',
+    );
+  }
+  return session;
+};
+
+/**
+ * Subscribe to the session's reactive store. Returns the current
+ * `SessionState` snapshot (re-renders on each store change).
+ */
+export const useSessionState = (): SessionState => {
+  const session = useSession();
+  return useSyncExternalStore(
+    session.subscribe,
+    session.getState,
+    session.getState,
+  );
+};
+
+/** Convenience hook: just the connection state. */
+export const useConnectionState = (): SessionState['connectionState'] => {
+  const state = useSessionState();
+  return state.connectionState;
+};
+
+/**
+ * Subscribe to a server-emitted event by `eventType`. The handler
+ * fires on every matching `event` frame. Unsubscribes on unmount.
+ *
+ * Per the chunk-B7 trap "no `useEffect` for data fetching" — this
+ * hook only registers / disposes a listener; it never fetches.
+ */
+export const useSessionEvent = <P = unknown>(
+  eventType: string,
+  handler: (payload: EventPayload & { data: P }) => void,
+): void => {
+  const session = useSession();
+  const ref = useEventCallback(handler);
+  useEffect(() => {
+    return session.events.onEvent<P>(eventType, ref);
+  }, [session, eventType, ref]);
+};
+
+/**
+ * Subscribe to a lifecycle transition by name. Same shape as
+ * `useSessionEvent` but reading the `lifecycle` channel.
+ */
+export const useSessionLifecycle = (
+  transition: string,
+  handler: (payload: LifecyclePayload) => void,
+): void => {
+  const session = useSession();
+  const ref = useEventCallback(handler);
+  useEffect(() => {
+    if (transition === 'session.opened') {
+      return session.lifecycle.onSessionOpened(ref);
+    }
+    if (transition === 'session.closed') {
+      return session.lifecycle.onSessionClosed(ref);
+    }
+    if (transition.startsWith('phase.entered')) {
+      return session.lifecycle.onPhaseEntered(ref);
+    }
+    if (transition.startsWith('phase.exited')) {
+      return session.lifecycle.onPhaseExited(ref);
+    }
+    if (transition === 'host.reclaimed') {
+      return session.lifecycle.onHostReclaimed(ref);
+    }
+    // Fall back to the raw bus for unknown transitions.
+    return session.events.onAnyEvent(() => {
+      // Lifecycle frames go through `lifecycle.*`, not `events`.
+      // For unknown transitions, the consumer should use
+      // `session.lifecycle` directly.
+    });
+  }, [session, transition, ref]);
+};
+
+/**
+ * Subscribe to consent-required events as a React hook. Returns a
+ * tuple `[payload, decide]`. While `payload` is non-null, a prompt
+ * is pending; call `decide('accepted' | 'declined')` to resolve it.
+ *
+ * Equivalent to wiring `onConsentRequired` on `createSession`, but
+ * scoped to a component lifetime. Use this in the Player shell's
+ * consent bridge.
+ */
+export const useConsentPrompt = (): [
+  ConsentRequiredPayload | null,
+  (decision: ConsentDecision) => void,
+] => {
+  const session = useSession();
+  const [state, setState] = useState<{
+    payload: ConsentRequiredPayload | null;
+    resolve: ((d: ConsentDecision) => void) | null;
+  }>({
+    payload: null,
+    resolve: null,
+  });
+
+  useSessionEvent<ConsentRequiredPayload>('consent_required', (event) => {
+    setState({
+      payload: event.data,
+      resolve: (decision) => {
+        setState({ payload: null, resolve: null });
+        if (decision === 'accepted') {
+          void session.requestConsent(event.data).then((result) => {
+            session.emit({
+              eventType: 'consent.decision',
+              data: {
+                personaId: event.data.personaId,
+                scope: event.data.scope,
+                decision,
+                persistOk: result.ok,
+                persistError: result.ok ? null : result.error.kind,
+              },
+            });
+          });
+        } else {
+          session.emit({
+            eventType: 'consent.decision',
+            data: {
+              personaId: event.data.personaId,
+              scope: event.data.scope,
+              decision,
+              persistOk: false,
+              persistError: null,
+            },
+          });
+        }
+      },
+    });
+  });
+
+  const decide = useCallback(
+    (decision: ConsentDecision) => {
+      state.resolve?.(decision);
+    },
+    [state],
+  );
+
+  return [state.payload, decide];
+};
+
+/**
+ * Stable callback ref — the returned function never changes identity
+ * even though it always calls the latest passed-in `handler`. Used
+ * by event hooks so the effect doesn't re-subscribe on every render.
+ */
+const useEventCallback = <Args extends readonly unknown[], R>(
+  handler: (...args: Args) => R,
+): ((...args: Args) => R) => {
+  const ref = useMemo(() => ({ current: handler }), []);
+  ref.current = handler;
+  return useCallback((...args: Args) => ref.current(...args), [ref]);
+};

package/src/store.ts

@@ -0,0 +1,318 @@
+/**
+ * Reactive session store (per chunk B7 build: "state.ts — reactive
+ * state subscription. Returns React hooks that read from a
+ * synchronised store").
+ *
+ * The store holds the four pieces of session truth a client cares
+ * about: the connection state, the authoritative server projection
+ * (the `state` from `snapshot` plus any applied `state_diff` patches),
+ * the optimistic projections layered on top (predictive rendering),
+ * and the current `appliedSeq`. Consumers subscribe via `subscribe`
+ * (callback-style) or via the React hooks in `react.ts` (which use
+ * `useSyncExternalStore`).
+ *
+ * **One store per session.** Per the chunk-B7 trap "Do not let the AI
+ * inline state stores per call site. One store per session." The
+ * `createSession` factory owns exactly one store and never exposes
+ * the constructor; `useSessionState` and friends read from the
+ * session-attached store.
+ *
+ * **State shape.** The protocol is opaque about the projection's
+ * shape (`SnapshotPayload.state: unknown`). The store carries the
+ * raw value plus a thin per-recipient narrowing helper
+ * (`selectSlice`) so a React hook can pull `session`, `host`,
+ * `player.public`, `player.private`, or `team` without re-projecting
+ * the whole tree on every render. The per-Experience type narrowing
+ * lives at the consumer call-site (the SDK is type-agnostic).
+ *
+ * The store is implementation-detail to the SDK; nothing outside
+ * `client.ts` / `react.ts` / `transport.ts` constructs one directly.
+ */
+
+import type { JsonPatchOp } from '@wibly/internal-protocol';
+
+export type ConnectionState =
+  | 'idle'
+  | 'connecting'
+  | 'open'
+  | 'reconnecting'
+  | 'closed';
+
+export type SessionStoreSnapshot = {
+  readonly connectionState: ConnectionState;
+  readonly state: unknown;
+  readonly phaseId: string | null;
+  readonly appliedSeq: number;
+  /**
+   * Identifiers of the optimistic projections currently applied on
+   * top of `state`. The actual projection functions are stored
+   * separately so the snapshot stays serialisable.
+   */
+  readonly pendingProjectionIds: readonly string[];
+};
+
+export type OptimisticProjection<T = unknown> = (state: T) => T;
+
+export type SessionStore = {
+  /** Subscribe to store changes. Returns an unsubscribe function. */
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Current store snapshot. Returns the same reference between mutations. */
+  readonly getSnapshot: () => SessionStoreSnapshot;
+  /** Internal mutators — not exposed past `createSession`. */
+  readonly setConnectionState: (next: ConnectionState) => void;
+  readonly applySnapshot: (state: unknown, phaseId: string, baseSeq: number) => void;
+  readonly applyDiff: (
+    patches: readonly JsonPatchOp[],
+    fromSeq: number,
+    toSeq: number,
+  ) => 'applied' | 'resync_required';
+  readonly addProjection: (id: string, fn: OptimisticProjection) => void;
+  readonly removeProjection: (id: string) => void;
+  readonly hasProjection: (id: string) => boolean;
+  /**
+   * Render the projected view: `state` with every active projection
+   * applied in registration order. Cheap because projections are
+   * typically a small handful per session.
+   */
+  readonly getProjectedState: () => unknown;
+};
+
+export const createSessionStore = (): SessionStore => {
+  const listeners = new Set<() => void>();
+  const projections = new Map<string, OptimisticProjection>();
+  let snapshot: SessionStoreSnapshot = {
+    connectionState: 'idle',
+    state: null,
+    phaseId: null,
+    appliedSeq: 0,
+    pendingProjectionIds: [],
+  };
+
+  const emit = (): void => {
+    for (const l of listeners) {
+      try {
+        l();
+      } catch {
+        // listeners must not throw; swallow and continue.
+      }
+    }
+  };
+
+  const refreshSnapshot = (partial: Partial<SessionStoreSnapshot>): void => {
+    snapshot = {
+      ...snapshot,
+      ...partial,
+      pendingProjectionIds:
+        partial.pendingProjectionIds ?? snapshot.pendingProjectionIds,
+    };
+    emit();
+  };
+
+  return {
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot: () => snapshot,
+    setConnectionState: (next) => {
+      if (next === snapshot.connectionState) return;
+      refreshSnapshot({ connectionState: next });
+    },
+    applySnapshot: (state, phaseId, baseSeq) => {
+      refreshSnapshot({ state, phaseId, appliedSeq: baseSeq });
+    },
+    applyDiff: (patches, fromSeq, toSeq) => {
+      if (fromSeq !== snapshot.appliedSeq) {
+        return 'resync_required';
+      }
+      const next = applyPatches(snapshot.state, patches);
+      refreshSnapshot({ state: next, appliedSeq: toSeq });
+      return 'applied';
+    },
+    addProjection: (id, fn) => {
+      projections.set(id, fn);
+      refreshSnapshot({
+        pendingProjectionIds: Array.from(projections.keys()),
+      });
+    },
+    removeProjection: (id) => {
+      if (!projections.has(id)) return;
+      projections.delete(id);
+      refreshSnapshot({
+        pendingProjectionIds: Array.from(projections.keys()),
+      });
+    },
+    hasProjection: (id) => projections.has(id),
+    getProjectedState: () => {
+      let out = snapshot.state;
+      for (const fn of projections.values()) {
+        try {
+          out = fn(out);
+        } catch {
+          // projection that throws is dropped silently — its
+          // confirming submit failed, but a tasteless caller can
+          // still inspect server state.
+        }
+      }
+      return out;
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// JSON Patch application
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply a sequence of JSON-Patch operations to a JSON-shaped value.
+ *
+ * Supports the five operation kinds declared in `@platform/protocol`
+ * (`add` / `remove` / `replace` / `move` / `copy`). Paths use the
+ * RFC-6901 escaping (`/` becomes `~1`, `~` becomes `~0`); the empty
+ * path `''` targets the root document.
+ *
+ * Returns a NEW object tree — never mutates the input. The implementation
+ * is deliberately small (~100 lines) so the SDK doesn't pull in an
+ * external `fast-json-patch` dependency.
+ */
+export const applyPatches = (
+  root: unknown,
+  patches: readonly JsonPatchOp[],
+): unknown => {
+  let next = root;
+  for (const op of patches) {
+    next = applyOne(next, op);
+  }
+  return next;
+};
+
+const applyOne = (root: unknown, op: JsonPatchOp): unknown => {
+  switch (op.op) {
+    case 'add':
+      return setAt(root, parsePath(op.path), op.value, 'add');
+    case 'remove':
+      return removeAt(root, parsePath(op.path));
+    case 'replace':
+      return setAt(root, parsePath(op.path), op.value, 'replace');
+    case 'copy': {
+      const src = getAt(root, parsePath(op.from));
+      return setAt(root, parsePath(op.path), structuredCloneShallow(src), 'add');
+    }
+    case 'move': {
+      const src = getAt(root, parsePath(op.from));
+      const removed = removeAt(root, parsePath(op.from));
+      return setAt(removed, parsePath(op.path), src, 'add');
+    }
+  }
+};
+
+const parsePath = (path: string): readonly string[] => {
+  if (path === '') return [];
+  if (!path.startsWith('/')) {
+    throw new Error(`json-patch: path must start with '/' (got '${path}')`);
+  }
+  return path
+    .slice(1)
+    .split('/')
+    .map((seg) => seg.replace(/~1/g, '/').replace(/~0/g, '~'));
+};
+
+const getAt = (root: unknown, path: readonly string[]): unknown => {
+  let cur: unknown = root;
+  for (const seg of path) {
+    cur = step(cur, seg);
+  }
+  return cur;
+};
+
+const step = (cur: unknown, seg: string): unknown => {
+  if (Array.isArray(cur)) {
+    const idx = Number(seg);
+    return Number.isInteger(idx) ? cur[idx] : undefined;
+  }
+  if (cur && typeof cur === 'object') {
+    return (cur as Record<string, unknown>)[seg];
+  }
+  return undefined;
+};
+
+const removeAt = (root: unknown, path: readonly string[]): unknown => {
+  if (path.length === 0) return null;
+  return reduceWithCopy(root, path, (parent, last) => {
+    if (Array.isArray(parent)) {
+      const idx = Number(last);
+      const copy = parent.slice();
+      copy.splice(idx, 1);
+      return copy;
+    }
+    if (parent && typeof parent === 'object') {
+      const { [last]: _drop, ...rest } = parent as Record<string, unknown>;
+      void _drop;
+      return rest;
+    }
+    return parent;
+  });
+};
+
+const setAt = (
+  root: unknown,
+  path: readonly string[],
+  value: unknown,
+  mode: 'add' | 'replace',
+): unknown => {
+  if (path.length === 0) return value;
+  return reduceWithCopy(root, path, (parent, last) => {
+    if (Array.isArray(parent)) {
+      const copy = parent.slice();
+      if (last === '-') {
+        copy.push(value);
+      } else {
+        const idx = Number(last);
+        if (mode === 'add') copy.splice(idx, 0, value);
+        else copy[idx] = value;
+      }
+      return copy;
+    }
+    if (parent && typeof parent === 'object') {
+      return { ...(parent as Record<string, unknown>), [last]: value };
+    }
+    // Setting under a primitive parent — create an object with the key.
+    return { [last]: value };
+  });
+};
+
+const reduceWithCopy = (
+  root: unknown,
+  path: readonly string[],
+  mutate: (parent: unknown, last: string) => unknown,
+): unknown => {
+  if (path.length === 0) {
+    throw new Error('json-patch: cannot mutate root with empty path');
+  }
+  const first = path[0];
+  if (first === undefined) {
+    throw new Error('json-patch: empty path segment');
+  }
+  const rest = path.slice(1);
+  if (rest.length === 0) {
+    return mutate(root, first);
+  }
+  const child = step(root, first);
+  const nextChild = reduceWithCopy(child, rest, mutate);
+  if (Array.isArray(root)) {
+    const copy = root.slice();
+    copy[Number(first)] = nextChild;
+    return copy;
+  }
+  if (root && typeof root === 'object') {
+    return { ...(root as Record<string, unknown>), [first]: nextChild };
+  }
+  return { [first]: nextChild };
+};
+
+const structuredCloneShallow = (v: unknown): unknown => {
+  if (v === null || typeof v !== 'object') return v;
+  return structuredClone(v);
+};

package/src/submit.ts

@@ -0,0 +1,92 @@
+/**
+ * Submit / emit helpers (per chunk B7 build: "submit.ts — typed
+ * submit helpers (session.submit(input)) with idempotent retry on
+ * disconnect").
+ *
+ * `submit` is the workhorse for turn-based input collection. Each
+ * call:
+ *
+ *   1. Generates a stable `msg_…` id (the transport stamps it on the
+ *      envelope).
+ *   2. Optionally layers a predictive projection on the local store.
+ *   3. Sends a `submit` frame over the transport.
+ *   4. Returns a `PendingSubmit` handle the caller awaits or watches.
+ *      The handle resolves once the server confirms (with a matching
+ *      `state_diff` or `error`) — see `client.ts` for the wiring.
+ *
+ * The Runtime dedupes by envelope `id` (chunk B0). The transport
+ * re-queues the same frame on reconnect; the server collapses
+ * duplicates server-side.
+ *
+ * For chunk B7, this module exports the *typed* surface and the
+ * `PendingSubmit` shape; `client.ts` wires it up against the live
+ * transport.
+ */
+
+import type { SubmitPayload, EmitPayload } from '@wibly/internal-protocol';
+import type { Result } from '@wibly/internal-shared';
+
+import type { SdkError } from './errors.js';
+import type { OptimisticProjection } from './store.js';
+
+export type SubmitArgs = {
+  readonly phaseId: string;
+  readonly inputType: string;
+  readonly data: unknown;
+  /**
+   * Optional predictive projection. The SDK applies the projection
+   * to the local store immediately (so the UI updates without
+   * waiting for the server's `state_diff`) and removes it on
+   * confirmation / rollback.
+   */
+  readonly predictive?: OptimisticProjection;
+  /**
+   * How long to wait for the server's confirming `state_diff` /
+   * `error` before resolving with `Err({ kind: 'timeout' })`.
+   * Default 30s. A submit that times out is NOT rolled back — the
+   * server may still emit a confirming frame, in which case the
+   * store reconciles. Use `cancel()` to drop a pending submit
+   * explicitly.
+   */
+  readonly timeoutMs?: number;
+};
+
+export type EmitArgs = {
+  readonly eventType: string;
+  readonly data: unknown;
+};
+
+export type PendingSubmit = {
+  /** The envelope id the SDK generated for this submit. */
+  readonly id: string;
+  /** Resolves when the server confirms or the timeout fires. */
+  readonly promise: Promise<Result<void, SdkError>>;
+  /**
+   * Drop the predictive projection (if any) and stop waiting for
+   * confirmation. Does NOT cancel the server-side processing — the
+   * server may still emit a `state_diff` later, which the store
+   * reconciles normally.
+   */
+  readonly cancel: () => void;
+};
+
+export const buildSubmitPayload = (
+  sessionId: string,
+  args: SubmitArgs,
+): SubmitPayload =>
+  ({
+    sessionId,
+    phaseId: args.phaseId,
+    inputType: args.inputType,
+    data: args.data,
+  }) as SubmitPayload;
+
+export const buildEmitPayload = (
+  sessionId: string,
+  args: EmitArgs,
+): EmitPayload =>
+  ({
+    sessionId,
+    eventType: args.eventType,
+    data: args.data,
+  }) as EmitPayload;