@wibly/sdk 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,6 +1,23 @@
 # `@wibly/sdk` — Changelog
 
-## Unreleased
+## 0.1.1 — 2026-05-30
+
+### Fixed
+
+- `SdkCallKind` and `SdkQualityTier` are now type-only re-exports of
+  `@platform/manifest`'s `CallKind` and `QualityTier` instead of
+  hand-duplicated string-literal unions that had drifted from the
+  manifest's `CallKindSchema` / `QualityTierSchema`. The previous
+  literals included `judge_submissions` and `host_persona_response`
+  (neither valid manifest call kinds) and `preview` / `high` quality
+  tiers (the manifest set is `fast | standard | premium | creative`);
+  any caller using those literals would have failed Gateway request
+  validation at the first network hop. Type-only `import` keeps the
+  SDK's runtime weight unchanged. The `inference.judge` convenience
+  wrapper now sends `callKind: 'host_judge'` (was the invalid
+  `judge_submissions`).
+
+## 0.1.0 — 2026-05-18
 
 Initial Studio SDK surface (chunk B7).
 
@@ -20,7 +37,7 @@ Initial Studio SDK surface (chunk B7).
   - `events.{onEvent, onAnyEvent}` and `lifecycle.{onSessionOpened,
     onSessionClosed, onPhaseEntered, onPhaseExited, onHostReclaimed}`.
   - `requestConsent(payload)` to forward an accepted consent decision
-    to the User Portal endpoint (chunk B17a; returns
+    to the User Portal endpoint (chunk B19a; returns
     `consent_persistence_not_wired` until then).
   - `close()` to tear down the WebSocket + dispose listeners.
 - React bindings at `@wibly/sdk/react`: `SessionProvider`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wibly/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Wibly @wibly/sdk",
   "type": "module",
   "main": "./src/index.ts",
@@ -18,9 +18,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@wibly/internal-manifest": "0.1.0",
-    "@wibly/internal-protocol": "0.1.0",
-    "@wibly/internal-shared": "0.1.0",
+    "@wibly/internal-manifest": "0.1.1",
+    "@wibly/internal-protocol": "0.1.1",
+    "@wibly/internal-shared": "0.1.1",
     "zod": "^3.25.76"
   },
   "peerDependencies": {

package/src/client.ts

@@ -27,7 +27,7 @@
  * **Consent callback.** When the Runtime emits a `consent_required`
  * event, the SDK calls the registered callback and (on
  * `accepted`) calls `session.requestConsent(...)` to forward the
- * grant to the User Portal endpoint (chunk B17a).
+ * grant to the User Portal endpoint (chunk B19a).
  */
 
 import { ok, type Result } from '@wibly/internal-shared';
@@ -68,6 +68,7 @@ import {
   INFERENCE_EVENT_PREFIX,
 } from './inference.js';
 import {
+  estimateAudioDurationMs,
   type SessionVoice,
   type SpeakSuccess,
   VOICE_EVENT_PREFIX,
@@ -94,6 +95,17 @@ export type SessionConfig = {
   readonly wsUrl: string;
   readonly sessionId: SessionId;
   readonly auth?: string;
+  /**
+   * Marks the connected Session as a preview run (Chunk B16).
+   *
+   * The Portal/Admin that opens the Session passes this flag when
+   * the Runtime's `GET /sessions/:id` returned
+   * `visibility === 'preview'` (or the redemption response set
+   * `isPreview: true`). Shells use the value to render a "Preview"
+   * watermark on host/player chrome and to suppress production-only
+   * affordances. Defaults to `false`.
+   */
+  readonly isPreview?: boolean;
   readonly onConsentRequired?: ConsentRequiredCallback;
   /** Test seam — pass a fake WebSocket constructor. */
   readonly factory?: WebSocketFactory;
@@ -107,10 +119,12 @@ export type SessionConfig = {
    * Submit confirmation timeout. Default 30s. See `submit.ts`.
    */
   readonly submitTimeoutMs?: number;
+  /** Voice speak confirmation timeout. Default 30s. */
+  readonly voiceSpeakTimeoutMs?: number;
   /**
    * Persistence endpoint for accepted consents. When the player
    * accepts a consent prompt, the SDK invokes `persistConsent` to
-   * write the grant. Chunk B17a wires the real implementation
+   * write the grant. Chunk B19a wires the real implementation
    * against the User Portal; MVP leaves it `undefined` and
    * `requestConsent` returns `consent_persistence_not_wired`.
    */
@@ -129,10 +143,29 @@ export type SessionState = {
   readonly appliedSeq: number;
   /** Current phase id from the most recent snapshot. */
   readonly phaseId: string | null;
+  /** Whether the Runtime has broadcast a `lifecycle.paused` frame. */
+  readonly sessionPaused: boolean;
+  readonly pauseReason: 'host' | 'system' | null;
+  /** Host-visible orphan-seat recovery code, when active. */
+  readonly recoveryCode: string | null;
+  readonly recoveryCodeHint: string | null;
+  /**
+   * Whether the connected Session is a preview run (Chunk B16).
+   * Populated from `SessionConfig.isPreview` and updated when a
+   * lifecycle frame with `transition === 'session.metadata'`
+   * carries `{ isPreview: boolean }` in its detail.
+   */
+  readonly isPreview: boolean;
 };
 
 export type Session = {
   readonly sessionId: SessionId;
+  /**
+   * Whether the Session is a preview run (Chunk B16). Mirrors
+   * {@link SessionState.isPreview} so callers that don't need the
+   * full state snapshot can read the flag directly.
+   */
+  readonly isPreview: boolean;
   /** Current snapshot — calling getter triggers no work. */
   readonly getState: () => SessionState;
   /** Reactive subscription. The callback fires on store changes. */
@@ -160,7 +193,7 @@ export type Session = {
   readonly store: SessionStore;
   /**
    * Forward an accepted consent decision to the persistence path.
-   * Returns `consent_persistence_not_wired` until chunk B17a binds
+   * Returns `consent_persistence_not_wired` until chunk B19a binds
    * the User Portal endpoint.
    */
   readonly requestConsent: (
@@ -177,20 +210,31 @@ type PendingRecord = {
   readonly timer?: () => void;
 };
 
+type PendingVoiceRecord = {
+  readonly resolve: (r: Result<unknown, SdkError>) => void;
+  readonly caption: string | null | undefined;
+  readonly cancelTimeout: () => void;
+};
+
+const DEFAULT_VOICE_SPEAK_TIMEOUT_MS = 30_000;
+
 export const createSession = (config: SessionConfig): Session => {
   const store = createSessionStore();
   const bus = createEventBus();
   const time = createServerTimeSource({ now: config.now });
   const lifecycle = createLifecycleBindings(bus);
+  let isPreviewFlag: boolean = config.isPreview ?? false;
   const pendingSubmits = new Map<MessageId, PendingRecord>();
   const pendingInference = new Map<
     MessageId,
     (r: Result<unknown, SdkError>) => void
   >();
-  const pendingVoice = new Map<
-    MessageId,
-    (r: Result<unknown, SdkError>) => void
-  >();
+  const pendingVoice = new Map<MessageId, PendingVoiceRecord>();
+  const voiceSpeakTimeoutMs =
+    config.voiceSpeakTimeoutMs ?? DEFAULT_VOICE_SPEAK_TIMEOUT_MS;
+  const scheduleTimer =
+    config.schedule ??
+    ((cb: () => void, ms: number) => scheduleTimeout(ms, cb));
 
   const handleStateDiff = (payload: StateDiffPayload): void => {
     const action = store.applyDiff(
@@ -209,6 +253,18 @@ export const createSession = (config: SessionConfig): Session => {
 
   const handleEvent = (payload: EventPayload): void => {
     bus.dispatchEvent(payload);
+    if (payload.eventType === 'recovery_code.issued') {
+      const data = payload.data as {
+        code?: unknown;
+        seat?: unknown;
+      } | null;
+      if (data && typeof data.code === 'string') {
+        store.setRecoveryCode(
+          data.code,
+          typeof data.seat === 'string' ? data.seat : null,
+        );
+      }
+    }
     if (payload.eventType.startsWith(INFERENCE_EVENT_PREFIX)) {
       maybeResolveInference(payload);
     } else if (payload.eventType.startsWith(VOICE_EVENT_PREFIX)) {
@@ -219,6 +275,58 @@ export const createSession = (config: SessionConfig): Session => {
   };
 
   const handleLifecycle = (payload: LifecyclePayload): void => {
+    if (
+      payload.transition === 'session.metadata' &&
+      payload.detail !== null &&
+      typeof payload.detail === 'object' &&
+      'isPreview' in payload.detail &&
+      typeof (payload.detail as { isPreview: unknown }).isPreview === 'boolean'
+    ) {
+      isPreviewFlag = (payload.detail as { isPreview: boolean }).isPreview;
+      cachedSessionState = null;
+    }
+    if (
+      payload.transition === 'session.closed' ||
+      payload.transition === 'session.aborted' ||
+      payload.transition === 'aborted'
+    ) {
+      transport.close(1000, 'session ended');
+    }
+    if (payload.transition === 'phase.changed') {
+      const detail = payload.detail;
+      if (detail !== null && typeof detail === 'object') {
+        const toPhaseId = (detail as { toPhaseId?: unknown }).toPhaseId;
+        if (typeof toPhaseId === 'string') {
+          store.setPhaseId(toPhaseId);
+        }
+      }
+    }
+    if (payload.transition === 'paused') {
+      const detail = payload.detail;
+      const via =
+        detail !== null &&
+        typeof detail === 'object' &&
+        (detail as { via?: unknown }).via === 'host_control'
+          ? 'host'
+          : 'system';
+      store.setSessionPaused(true, via);
+    }
+    if (payload.transition === 'continued') {
+      store.setSessionPaused(false, null);
+    }
+    if (payload.transition === 'seat.recovery_code_issued') {
+      const detail = payload.detail;
+      if (detail !== null && typeof detail === 'object') {
+        const code = (detail as { code?: unknown }).code;
+        const seat = (detail as { seat?: unknown }).seat;
+        if (typeof code === 'string') {
+          store.setRecoveryCode(
+            code,
+            typeof seat === 'string' ? seat : null,
+          );
+        }
+      }
+    }
     bus.dispatchLifecycle(payload);
   };
 
@@ -261,9 +369,10 @@ export const createSession = (config: SessionConfig): Session => {
     }
     const voice = pendingVoice.get(causeId);
     if (voice !== undefined) {
+      voice.cancelTimeout();
       pendingVoice.delete(causeId);
       transport.confirmSend(causeId);
-      voice({
+      voice.resolve({
         ok: false,
         error: {
           kind: 'submit_rejected',
@@ -366,15 +475,94 @@ export const createSession = (config: SessionConfig): Session => {
     cb(ok(payload.data));
   };
 
+  const dispatchVoiceAudio = (
+    causeId: MessageId,
+    data: {
+      audioBase64: string;
+      contentType?: unknown;
+      durationMs?: unknown;
+    },
+    caption: string | null | undefined,
+  ): void => {
+    bus.dispatchEvent({
+      sessionId: config.sessionId,
+      eventType: 'voice.audio',
+      data: {
+        id: causeId,
+        audioBase64: data.audioBase64,
+        contentType:
+          typeof data.contentType === 'string'
+            ? data.contentType
+            : 'audio/mpeg',
+        durationMs:
+          typeof data.durationMs === 'number' && data.durationMs > 0
+            ? data.durationMs
+            : estimateAudioDurationMs(data.audioBase64),
+        caption: caption === undefined ? null : caption,
+      },
+    });
+  };
+
   const maybeResolveVoice = (payload: EventPayload): void => {
-    const data = payload.data as { causeMessageId?: string } | null;
+    const data = payload.data as {
+      causeMessageId?: string;
+      audioBase64?: string;
+      contentType?: string;
+      durationMs?: number;
+      kind?: string;
+    } | null;
     if (!data || typeof data.causeMessageId !== 'string') return;
     const causeId = data.causeMessageId as unknown as MessageId;
-    const cb = pendingVoice.get(causeId);
-    if (cb === undefined) return;
+    const pending = pendingVoice.get(causeId);
+    const caption = pending?.caption;
+    const audioBase64 = data.audioBase64;
+
+    if (
+      payload.eventType === 'voice.speak.result' &&
+      typeof audioBase64 === 'string'
+    ) {
+      dispatchVoiceAudio(
+        causeId,
+        {
+          audioBase64,
+          contentType: data.contentType,
+          durationMs: data.durationMs,
+        },
+        caption ?? null,
+      );
+    }
+
+    if (pending === undefined) return;
+    pending.cancelTimeout();
     pendingVoice.delete(causeId);
     transport.confirmSend(causeId);
-    cb(ok(payload.data));
+
+    if (
+      payload.eventType === 'voice.speak.result' &&
+      typeof audioBase64 === 'string'
+    ) {
+      pending.resolve(
+        ok({
+          audioBase64,
+          contentType:
+            typeof data.contentType === 'string'
+              ? data.contentType
+              : 'audio/mpeg',
+          durationMs:
+            typeof data.durationMs === 'number' && data.durationMs > 0
+              ? data.durationMs
+              : estimateAudioDurationMs(audioBase64),
+        } satisfies SpeakSuccess),
+      );
+      return;
+    }
+
+    if (payload.eventType === 'voice.speak.error') {
+      pending.resolve({
+        ok: false,
+        error: { kind: 'runtime_not_wired' },
+      });
+    }
   };
 
   const maybeHandleConsent = (payload: EventPayload): void => {
@@ -409,18 +597,40 @@ export const createSession = (config: SessionConfig): Session => {
     })();
   };
 
+  // `useSyncExternalStore` compares snapshots with `Object.is`. A fresh
+  // object on every `getState()` call makes React think the store
+  // changed on every read → infinite re-renders in shell hooks.
+  let cachedStoreSnapshot: ReturnType<SessionStore['getSnapshot']> | null =
+    null;
+  let cachedSessionState: SessionState | null = null;
+
+  const readSessionState = (): SessionState => {
+    const snap = store.getSnapshot();
+    if (cachedStoreSnapshot === snap && cachedSessionState !== null) {
+      return cachedSessionState;
+    }
+    cachedStoreSnapshot = snap;
+    cachedSessionState = {
+      connectionState: snap.connectionState,
+      state: snap.state,
+      projectedState: store.getProjectedState(),
+      appliedSeq: snap.appliedSeq,
+      phaseId: snap.phaseId,
+      sessionPaused: snap.sessionPaused,
+      pauseReason: snap.pauseReason,
+      recoveryCode: snap.recoveryCode,
+      recoveryCodeHint: snap.recoveryCodeHint,
+      isPreview: isPreviewFlag,
+    };
+    return cachedSessionState;
+  };
+
   const session: Session = {
     sessionId: config.sessionId,
-    getState: () => {
-      const snap = store.getSnapshot();
-      return {
-        connectionState: snap.connectionState,
-        state: snap.state,
-        projectedState: store.getProjectedState(),
-        appliedSeq: snap.appliedSeq,
-        phaseId: snap.phaseId,
-      };
+    get isPreview(): boolean {
+      return isPreviewFlag;
     },
+    getState: readSessionState,
     subscribe: (listener) => store.subscribe(listener),
     submit: (args) => {
       const payload = buildSubmitPayload(config.sessionId, args);
@@ -515,7 +725,13 @@ export const createSession = (config: SessionConfig): Session => {
       transport,
       pendingInference,
     ),
-    voice: buildVoiceVerbs(config.sessionId, transport, pendingVoice),
+    voice: buildVoiceVerbs(
+      config.sessionId,
+      transport,
+      pendingVoice,
+      scheduleTimer,
+      voiceSpeakTimeoutMs,
+    ),
     events: { onEvent: bus.onEvent, onAnyEvent: bus.onAnyEvent },
     lifecycle,
     time: { serverNow: time.serverNow, recordEvent: time.recordEvent },
@@ -537,8 +753,9 @@ export const createSession = (config: SessionConfig): Session => {
         cb({ ok: false, error: { kind: 'not_connected' } });
       }
       pendingInference.clear();
-      for (const [, cb] of pendingVoice) {
-        cb({ ok: false, error: { kind: 'not_connected' } });
+      for (const [, pending] of pendingVoice) {
+        pending.cancelTimeout();
+        pending.resolve({ ok: false, error: { kind: 'not_connected' } });
       }
       pendingVoice.clear();
       bus.dispose();
@@ -607,8 +824,15 @@ const buildInferenceVerbs = (
   };
   return {
     call,
+    // Convenience wrappers map to the most-common manifest `CallKind`s
+    // (per `@platform/manifest`'s `CallKindSchema` and
+    // `docs/conventions/prompt-composition.md`). Bundles that need a
+    // less-common kind (`host_resolve`, `host_recap`, `judge_funniness`,
+    // `compose_clue`, `narrate_event`) call `inference.call({ callKind,
+    // ... })` directly — the wrappers are a comfort for the dominant
+    // open-phase + judge paths, not an exhaustive cover.
     host: (input) => call({ ...input, callKind: 'host_open_phase' }),
-    judge: (input) => call({ ...input, callKind: 'judge_submissions' }),
+    judge: (input) => call({ ...input, callKind: 'host_judge' }),
     classify: (input) => call({ ...input, callKind: 'classify' }),
   };
 };
@@ -616,13 +840,17 @@ const buildInferenceVerbs = (
 const buildVoiceVerbs = (
   sessionId: SessionId,
   transport: Transport,
-  pending: Map<MessageId, (r: Result<unknown, SdkError>) => void>,
+  pending: Map<MessageId, PendingVoiceRecord>,
+  schedule: (cb: () => void, ms: number) => () => void,
+  timeoutMs: number,
 ): SessionVoice => ({
   speak: async (input) => {
     let resolveFn!: (r: Result<unknown, SdkError>) => void;
     const promise = new Promise<Result<unknown, SdkError>>((res) => {
       resolveFn = res;
     });
+    const caption =
+      input.caption === null ? null : (input.caption ?? input.text);
     const sent = transport.send('emit', {
       sessionId,
       eventType: `${VOICE_EVENT_PREFIX}speak`,
@@ -630,17 +858,21 @@ const buildVoiceVerbs = (
         personaId: input.personaId,
         text: input.text,
         options: input.options ?? {},
-        caption: input.caption === null ? null : (input.caption ?? input.text),
+        caption,
       },
     });
-    pending.set(sent.id, resolveFn);
-    setTimeout(() => {
-      const cb = pending.get(sent.id);
-      if (cb === undefined) return;
+    const cancelTimeout = schedule(() => {
+      const record = pending.get(sent.id);
+      if (record === undefined) return;
       pending.delete(sent.id);
       transport.confirmSend(sent.id);
-      cb({ ok: false, error: { kind: 'runtime_not_wired' } });
-    }, 0);
+      record.resolve({ ok: false, error: { kind: 'runtime_not_wired' } });
+    }, timeoutMs);
+    pending.set(sent.id, {
+      resolve: resolveFn,
+      caption,
+      cancelTimeout,
+    });
     const result = await promise;
     return result as Result<SpeakSuccess, SdkError>;
   },

package/src/consent.ts

@@ -18,12 +18,12 @@
  *
  * **Persistence path.** When the player accepts, the shell calls
  * `session.requestConsent(...)` which forwards to the User Portal's
- * consent endpoint (chunk B17a). Until B17a lands the endpoint, the
+ * consent endpoint (chunk B19a). Until B19a lands the endpoint, the
  * verb returns `Result.err({ kind: 'consent_persistence_not_wired' })`
  * — the prompt callback still fires; only the grant-write is deferred.
  *
  * **Trap discipline** (chunk B7): the consent management surface lives
- * in `apps/portal` (B17a), not here. The SDK exposes the mid-Session
+ * in `apps/portal` (B19a), not here. The SDK exposes the mid-Session
  * prompt verbs only — `requestConsent` (grant a fresh consent),
  * surfaces via `useEvent('consent_required')`. Revoke / list lives on
  * the User Portal Settings page.
@@ -34,6 +34,21 @@
  * change here is a PROTOCOL_VERSION bump.
  */
 
+/**
+ * Per-Persona override copy for the mid-Session consent dialog
+ * (chunk B15). Either sub-field may be omitted to fall back to the
+ * platform default copy in the Player Web Shell's
+ * `apps-shells/player-web/src/lib/player-meta.ts` (`CONSENT_PROMPT_COPY`).
+ *
+ * Sourced from `personas.consent_copy` (chunk B15 schema addition);
+ * the Runtime's persona-forwarder enriches the wire `consent_required`
+ * event payload with this field when the Persona has it set.
+ */
+export type ConsentCopyOverride = {
+  readonly title?: string;
+  readonly description?: string;
+};
+
 /**
  * Payload the SDK surfaces on a `consent_required` callback. Mirrors
  * the shape the Persona Service emits (chunk B3) when `readMemoryEntry`
@@ -44,11 +59,18 @@
  *                             prompt copy.
  *   - `scope`               — `session | group | player` per the
  *                             `player_consent_scope` enum.
+ *   - `consentCopy`         — chunk B15 per-Persona override copy.
+ *                             Optional; falls back to the
+ *                             platform-default copy when absent. The
+ *                             field itself is optional (back-compatible
+ *                             addition); a missing-or-undefined value
+ *                             behaves the same way.
  */
 export type ConsentRequiredPayload = {
   readonly personaId: string;
   readonly personaDisplayName: string;
   readonly scope: 'session' | 'group' | 'player';
+  readonly consentCopy?: ConsentCopyOverride;
 };
 
 /**
@@ -62,7 +84,7 @@ export type ConsentDecision = 'accepted' | 'declined';
 /**
  * The SDK callback signature the Player shell binds against. The
  * component resolves the returned promise; the SDK forwards the
- * decision to the persistence path (B17a) on accept.
+ * decision to the persistence path (B19a) on accept.
  */
 export type ConsentRequiredCallback = (
   payload: ConsentRequiredPayload,

package/src/control.ts

@@ -13,7 +13,7 @@
  *   - `host.pause`          — request a pause; the server emits a
  *                             `lifecycle` `session.paused`.
  *   - `host.resume`         — resume from pause.
- *   - `host.advance_phase`  — request the next phase. The Runtime
+ *   - `host.advancePhase`  — request the next phase. The Runtime
  *                             may reject if no transition matches.
  *   - `host.reclaim`        — reclaim the host slot from a hung
  *                             host (the player who fires this
@@ -25,7 +25,7 @@ import type { EmitPayload } from '@wibly/internal-protocol';
 export const HOST_EVENT_TYPES = {
   pause: 'host.pause',
   resume: 'host.resume',
-  advancePhase: 'host.advance_phase',
+  advancePhase: 'host.advancePhase',
   reclaim: 'host.reclaim',
 } as const;
 

package/src/errors.ts

@@ -22,8 +22,8 @@
  *                                 player shell renders the dialog.
  *   - `consent_persistence_not_wired` — the SDK forwards a granted
  *                                 consent to the User Portal endpoint
- *                                 (chunk B17a); MVP returns this until
- *                                 B17a ships the route. The mid-Session
+ *                                 (chunk B19a); MVP returns this until
+ *                                 B19a ships the route. The mid-Session
  *                                 callback still fires so the shell
  *                                 renders the prompt; this error is
  *                                 returned from `session.requestConsent`
@@ -79,7 +79,7 @@ export const formatSdkError = (e: SdkError): string => {
     case 'consent_required':
       return 'sdk: consent required';
     case 'consent_persistence_not_wired':
-      return 'sdk: consent persistence endpoint is not yet wired (chunk B17a)';
+      return 'sdk: consent persistence endpoint is not yet wired (chunk B19a)';
     case 'runtime_not_wired':
       return 'sdk: runtime endpoint is not yet wired (chunk B8a)';
     case 'timeout':

package/src/index.ts

@@ -36,6 +36,7 @@ export {
 
 export {
   CONSENT_REQUIRED_EVENT_TYPE,
+  type ConsentCopyOverride,
   type ConsentDecision,
   type ConsentRequiredCallback,
   type ConsentRequiredEventType,

package/src/inference.ts

@@ -36,34 +36,42 @@ import type { z, ZodTypeAny } from 'zod';
 
 import { zodToJsonSchema, type JsonSchema } from '@wibly/internal-shared';
 import type { Result } from '@wibly/internal-shared';
+import type { CallKind, QualityTier } from '@wibly/internal-manifest';
 
 import type { SdkError } from './errors.js';
 
 /**
- * Quality tier surfaced on the SDK boundary. Mirrors
- * `QualityTierSchema` from `@wibly/internal-manifest` but kept as a string
- * literal here so the SDK doesn't pull in the manifest's full Zod
- * runtime (the manifest schemas are heavy; the SDK only needs the
- * literal set).
+ * Quality tier surfaced on the SDK boundary. Type-only re-export of
+ * `@platform/manifest`'s `QualityTier` so the manifest stays the
+ * single source of truth for the on-the-wire enum. The `import type`
+ * is erased at compile time, so the SDK still does not pull in the
+ * manifest's Zod runtime — only the type literals.
+ *
+ * The B7 close note ("kept as a string literal here so the SDK
+ * doesn't pull in the manifest's full Zod runtime") was right about
+ * the runtime concern but wrong to duplicate the literals — the
+ * duplication had already drifted from the manifest's enum at chunk
+ * close. Type-only re-export gives the same runtime weight (zero)
+ * with the contract honoured at compile time.
  */
-export type SdkQualityTier = 'preview' | 'standard' | 'high';
+export type SdkQualityTier = QualityTier;
 
 /**
- * Recognised call kinds. Matches `CallKindSchema`'s enum; duplicated
- * here to keep the SDK type-only against the manifest package.
+ * Recognised call kinds. Type-only re-export of `@platform/manifest`'s
+ * `CallKind`; the manifest's `CallKindSchema` (enumerating
+ * `host_open_phase`, `host_judge`, `host_resolve`, `host_recap`,
+ * `judge_funniness`, `narrate_event`, `classify`, `compose_clue`) is
+ * the canonical wire-side set. New `callKind`s land in
+ * `@platform/manifest` and `docs/conventions/prompt-composition.md`
+ * in the same commit per chunk B4's convention; the SDK's enum
+ * follows automatically because it's a type alias.
  *
- * `host_open_phase` / `narrate_event` / `judge_submissions` /
- * `host_persona_response` / `classify` is the chunk-B2 set; chunk
- * B12 extends it. The SDK accepts any string at runtime — the
- * `CallKind` union exists as an authoring aid in TypeScript.
+ * The trailing `(string & {})` widening preserves the chunk-B7
+ * authoring-aid behaviour ("the SDK accepts any string at runtime")
+ * while keeping the literal set as IntelliSense-discoverable
+ * autocompletes for in-tree game bundles.
  */
-export type SdkCallKind =
-  | 'host_open_phase'
-  | 'narrate_event'
-  | 'judge_submissions'
-  | 'host_persona_response'
-  | 'classify'
-  | (string & {});
+export type SdkCallKind = CallKind | (string & {});
 
 export type InferenceCallInput<TOutput extends ZodTypeAny> = {
   readonly callKind: SdkCallKind;

package/src/lifecycle.ts

@@ -47,7 +47,16 @@ const PHASE_EXITED_PREFIX = 'phase.exited';
 
 export const createLifecycleBindings = (bus: EventBus): LifecycleBindings => ({
   onSessionOpened: (handler) => bus.onLifecycle('session.opened', handler),
-  onSessionClosed: (handler) => bus.onLifecycle('session.closed', handler),
+  onSessionClosed: (handler) => {
+    const offClosed = bus.onLifecycle('session.closed', handler);
+    const offAborted = bus.onLifecycle('session.aborted', handler);
+    const offLegacy = bus.onLifecycle('aborted', handler);
+    return () => {
+      offClosed();
+      offAborted();
+      offLegacy();
+    };
+  },
   onPhaseEntered: (handler) => {
     return bus.onAnyLifecycle((payload) => {
       if (
@@ -55,6 +64,18 @@ export const createLifecycleBindings = (bus: EventBus): LifecycleBindings => ({
         payload.transition.startsWith(`${PHASE_ENTERED_PREFIX}:`)
       ) {
         handler(payload);
+        return;
+      }
+      if (payload.transition === 'phase.changed') {
+        const detail = payload.detail;
+        if (detail === null || typeof detail !== 'object') return;
+        const toPhaseId = (detail as { toPhaseId?: unknown }).toPhaseId;
+        if (typeof toPhaseId !== 'string') return;
+        handler({
+          ...payload,
+          transition: `${PHASE_ENTERED_PREFIX}:${toPhaseId}`,
+          detail: { ...detail, phaseId: toPhaseId },
+        });
       }
     });
   },

package/src/react.ts

@@ -26,6 +26,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
   useSyncExternalStore,
   type ReactNode,
@@ -34,7 +35,8 @@ import {
 import type { EventPayload, LifecyclePayload } from '@wibly/internal-protocol';
 
 import type { ConsentDecision, ConsentRequiredPayload } from './consent.js';
-import type { Session, SessionState } from './client.js';
+import type { Session, SessionConfig, SessionState } from './client.js';
+import { createSession } from './client.js';
 
 const SessionContext = createContext<Session | null>(null);
 
@@ -55,6 +57,35 @@ export const SessionProvider = (props: SessionProviderProps): ReactNode =>
     props.children,
   );
 
+const clientSessionKey = (config: SessionConfig): string =>
+  `${config.sessionId}\0${config.wsUrl}\0${config.auth ?? ''}`;
+
+/**
+ * Create a {@link Session} only in the browser after mount.
+ *
+ * Shell surfaces must not call `createSession` during SSR — Node can
+ * open a WebSocket that is orphaned on hydration, and React Strict
+ * Mode's mount/unmount/remount cycle permanently closes a session
+ * created in `useMemo`. Returns `null` until the client effect runs.
+ */
+export const useClientSession = (config: SessionConfig): Session | null => {
+  const configRef = useRef(config);
+  configRef.current = config;
+  const [session, setSession] = useState<Session | null>(null);
+  const key = clientSessionKey(config);
+
+  useEffect(() => {
+    const live = createSession(configRef.current);
+    setSession(live);
+    return () => {
+      live.close();
+      setSession(null);
+    };
+  }, [key]);
+
+  return session;
+};
+
 /**
  * Access the live `Session`. Throws if no provider is mounted (a
  * deliberate fail-fast — the alternative is a silent null that

package/src/store.ts

@@ -43,6 +43,12 @@ export type SessionStoreSnapshot = {
   readonly state: unknown;
   readonly phaseId: string | null;
   readonly appliedSeq: number;
+  /** Set when the Runtime broadcasts `lifecycle.paused`. */
+  readonly sessionPaused: boolean;
+  readonly pauseReason: 'host' | 'system' | null;
+  /** Active orphan-seat recovery code for the host (chunk B8a). */
+  readonly recoveryCode: string | null;
+  readonly recoveryCodeHint: string | null;
   /**
    * Identifiers of the optimistic projections currently applied on
    * top of `state`. The actual projection functions are stored
@@ -61,6 +67,15 @@ export type SessionStore = {
   /** Internal mutators — not exposed past `createSession`. */
   readonly setConnectionState: (next: ConnectionState) => void;
   readonly applySnapshot: (state: unknown, phaseId: string, baseSeq: number) => void;
+  readonly setPhaseId: (phaseId: string | null) => void;
+  readonly setSessionPaused: (
+    paused: boolean,
+    reason?: 'host' | 'system' | null,
+  ) => void;
+  readonly setRecoveryCode: (
+    code: string | null,
+    hint?: string | null,
+  ) => void;
   readonly applyDiff: (
     patches: readonly JsonPatchOp[],
     fromSeq: number,
@@ -85,6 +100,10 @@ export const createSessionStore = (): SessionStore => {
     state: null,
     phaseId: null,
     appliedSeq: 0,
+    sessionPaused: false,
+    pauseReason: null,
+    recoveryCode: null,
+    recoveryCodeHint: null,
     pendingProjectionIds: [],
   };
 
@@ -123,6 +142,31 @@ export const createSessionStore = (): SessionStore => {
     applySnapshot: (state, phaseId, baseSeq) => {
       refreshSnapshot({ state, phaseId, appliedSeq: baseSeq });
     },
+    setPhaseId: (phaseId) => {
+      if (phaseId === snapshot.phaseId) return;
+      refreshSnapshot({ phaseId });
+    },
+    setSessionPaused: (paused, reason = null) => {
+      if (paused === snapshot.sessionPaused && reason === snapshot.pauseReason) {
+        return;
+      }
+      refreshSnapshot({
+        sessionPaused: paused,
+        pauseReason: paused ? reason : null,
+      });
+    },
+    setRecoveryCode: (code, hint = null) => {
+      if (
+        code === snapshot.recoveryCode &&
+        hint === snapshot.recoveryCodeHint
+      ) {
+        return;
+      }
+      refreshSnapshot({
+        recoveryCode: code,
+        recoveryCodeHint: hint,
+      });
+    },
     applyDiff: (patches, fromSeq, toSeq) => {
       if (fromSeq !== snapshot.appliedSeq) {
         return 'resync_required';

package/src/voice.ts

@@ -23,6 +23,7 @@
 import type { Result } from '@wibly/internal-shared';
 
 import type { SdkError } from './errors.js';
+import type { SdkQualityTier } from './inference.js';
 
 export type SpeakInput = {
   readonly personaId: string;
@@ -30,7 +31,7 @@ export type SpeakInput = {
   readonly options?: {
     readonly voiceId?: string;
     readonly modelId?: string;
-    readonly qualityTier?: 'preview' | 'standard' | 'high';
+    readonly qualityTier?: SdkQualityTier;
   };
   /**
    * Caption text rendered through the SDK's `voice.caption` event.