@wibly/sdk 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,6 +1,32 @@
 # `@wibly/sdk` — Changelog
 
-## Unreleased
+## 0.1.2 — 2026-06-08
+
+### Added
+
+- `session.host.abort()` — a universal mid-game abort. Emits the new
+  `host.abort` control verb; the Runtime force-jumps to the manifest's
+  `workflow.abortPhaseId` (or the last declared phase when omitted) from
+  any phase. Games no longer need per-phase abort transitions.
+
+## 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 +46,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.2",
   "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.2",
+    "@wibly/internal-protocol": "0.1.2",
+    "@wibly/internal-shared": "0.1.2",
     "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. */
@@ -148,6 +181,25 @@ export type Session = {
     readonly advancePhase: (
       detail?: unknown,
     ) => Result<{ readonly id: string }, SdkError>;
+    /**
+     * Universal mid-game abort. The Runtime force-jumps to the
+     * manifest's abort/terminal phase (`workflow.abortPhaseId`, else
+     * the last declared phase) from wherever the session currently is.
+     * No per-phase wiring required.
+     */
+    readonly abort: () => Result<{ readonly id: string }, SdkError>;
+    readonly reportTtsPlayback: (detail: {
+      readonly state: 'active' | 'idle';
+    }) => Result<{ readonly id: string }, SdkError>;
+    readonly reportTtsBeat: (detail: {
+      readonly beatId: string;
+      readonly event: 'clip_start' | 'clip_end';
+      readonly clipId?: string;
+      readonly reveal?: {
+        readonly kind: 'none' | 'player_submission';
+        readonly playerId?: string;
+      };
+    }) => Result<{ readonly id: string }, SdkError>;
     readonly reclaim: () => Result<{ readonly id: string }, SdkError>;
   };
   readonly inference: SessionInference;
@@ -160,7 +212,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 +229,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 +272,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 +294,60 @@ 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);
+      time.freeze();
+    }
+    if (payload.transition === 'continued') {
+      store.setSessionPaused(false, null);
+      time.unfreeze();
+    }
+    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 +390,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 +496,121 @@ export const createSession = (config: SessionConfig): Session => {
     cb(ok(payload.data));
   };
 
+  const dispatchVoiceAudio = (
+    causeId: MessageId,
+    data: {
+      audioBase64: string;
+      contentType?: unknown;
+      durationMs?: unknown;
+      beat?: unknown;
+      cues?: 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,
+        // Carry in-phase beat + lip-sync cues through to the Host shell.
+        // These drive Experience reveal choreography via `reportTtsBeat`
+        // → `onTtsBeat`; dropping them here silently breaks beat reveals.
+        ...(data.beat !== undefined ? { beat: data.beat } : {}),
+        ...(data.cues !== undefined ? { cues: data.cues } : {}),
+      },
+    });
+  };
+
   const maybeResolveVoice = (payload: EventPayload): void => {
-    const data = payload.data as { causeMessageId?: 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;
-    pendingVoice.delete(causeId);
-    transport.confirmSend(causeId);
-    cb(ok(payload.data));
+    const data = payload.data as {
+      causeMessageId?: string;
+      audioBase64?: string;
+      contentType?: string;
+      durationMs?: number;
+      kind?: string;
+      beat?: unknown;
+      cues?: unknown;
+    } | null;
+    if (!data) return;
+
+    const audioBase64 = data.audioBase64;
+    const isSpeakResult =
+      payload.eventType === 'voice.speak.result' &&
+      typeof audioBase64 === 'string';
+
+    const causeId = (() => {
+      if (typeof data.causeMessageId === 'string' && data.causeMessageId.length > 0) {
+        return data.causeMessageId as MessageId;
+      }
+      if (isSpeakResult) {
+        return `voice-server-${audioBase64.length}-${audioBase64.slice(0, 12)}` as MessageId;
+      }
+      return null;
+    })();
+
+    if (isSpeakResult && causeId !== null) {
+      const pending =
+        typeof data.causeMessageId === 'string' && data.causeMessageId.length > 0
+          ? pendingVoice.get(data.causeMessageId as MessageId)
+          : undefined;
+      dispatchVoiceAudio(
+        causeId,
+        {
+          audioBase64,
+          contentType: data.contentType,
+          durationMs: data.durationMs,
+          beat: data.beat,
+          cues: data.cues,
+        },
+        pending?.caption ?? null,
+      );
+    }
+
+    if (typeof data.causeMessageId !== 'string' || data.causeMessageId.length === 0) {
+      return;
+    }
+
+    const causeMessageId = data.causeMessageId as MessageId;
+    const pending = pendingVoice.get(causeMessageId);
+
+    if (pending === undefined) return;
+    pending.cancelTimeout();
+    pendingVoice.delete(causeMessageId);
+    transport.confirmSend(causeMessageId);
+
+    if (isSpeakResult) {
+      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 +645,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);
@@ -501,6 +759,32 @@ export const createSession = (config: SessionConfig): Session => {
         const sent = transport.send('emit', payload);
         return ok({ id: sent.id as unknown as string });
       },
+      abort: () => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.abort,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
+      reportTtsPlayback: (detail) => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.ttsPlayback,
+          detail,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
+      reportTtsBeat: (detail) => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.ttsBeat,
+          detail,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
       reclaim: () => {
         const payload = buildHostEmitPayload(
           config.sessionId,
@@ -515,7 +799,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 +827,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();
@@ -588,7 +879,7 @@ const buildInferenceVerbs = (
     });
     const sent = transport.send('emit', {
       sessionId,
-      eventType: `${INFERENCE_EVENT_PREFIX}${input.callKind}`,
+      eventType: `${INFERENCE_EVENT_PREFIX}${input.templateId}`,
       data: serialised,
     });
     pending.set(sent.id, resolveFn);
@@ -607,22 +898,23 @@ const buildInferenceVerbs = (
   };
   return {
     call,
-    host: (input) => call({ ...input, callKind: 'host_open_phase' }),
-    judge: (input) => call({ ...input, callKind: 'judge_submissions' }),
-    classify: (input) => call({ ...input, callKind: 'classify' }),
   };
 };
 
 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 +922,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,8 +13,11 @@
  *   - `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.abort`          — universal mid-game abort. The Runtime
+ *                             force-jumps to the manifest's abort/
+ *                             terminal phase (no per-phase wiring).
  *   - `host.reclaim`        — reclaim the host slot from a hung
  *                             host (the player who fires this
  *                             becomes the new host if allowed).
@@ -25,7 +28,10 @@ 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',
+  abort: 'host.abort',
+  ttsPlayback: 'host.ttsPlayback',
+  ttsBeat: 'host.ttsBeat',
   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,
@@ -66,7 +67,6 @@ export {
   buildInferenceRequest,
   type InferenceCallInput,
   type InferenceCallSuccess,
-  type SdkCallKind,
   type SdkQualityTier,
   type SerialisedInferenceRequest,
   type SessionInference,
@@ -78,6 +78,9 @@ export {
   type SessionVoice,
   type SpeakInput,
   type SpeakSuccess,
+  type TtsBeatMeta,
+  type TtsBeatReveal,
+  type VoiceAudioPayload,
 } from './voice.js';
 
 export {

package/src/inference.ts

@@ -1,37 +1,8 @@
 /**
- * Inference verbs (per chunk B7 build: "inference.ts — typed call
- * helpers: session.inference.host(slots), .judge(slots),
- * .classify(slots), etc. — calls the Gateway through the Runtime
- * (the SDK never holds the gateway-auth key).").
- *
- * The chunk-B7 contract is:
- *
- *   1. The caller invokes `session.inference.<verb>({ slots, output,
- *      qualityTier? })`.
- *   2. The SDK serialises any caller-declared Zod output schema to
- *      JSON Schema (via `@platform/shared/json-schema.ts`).
- *   3. The SDK sends an `emit` frame with a reserved `inference.*`
- *      event type. The Runtime (chunk B8a) receives it, signs the
- *      request, forwards to the Gateway, and emits a follow-up
- *      `event` frame with the result keyed by the original message
- *      id.
- *   4. The SDK matches the inbound event against the pending call's
- *      id and resolves the typed result.
- *
- * **Why `emit` and not a new wire kind?** The protocol already
- * carries `emit` for asynchronous client → server work; reserving an
- * `inference.*` namespace on `eventType` keeps the surface compact
- * and avoids a `PROTOCOL_VERSION` bump. The chunk-B8a Runtime is
- * what enforces the gating + signing.
- *
- * Until chunk B8a wires the Runtime-side handler, the SDK's
- * inference verbs return `Err({ kind: 'runtime_not_wired' })`. The
- * SDK still serialises the schema + payload so the chunk-B7 surface
- * is testable (the JSON Schema + outbound `emit` shape are
- * regression-protected); the runtime-side roundtrip lights up with
- * B8a.
+ * Inference verbs — game code calls by manifest `templateId`.
  */
 
+import type { QualityTier } from '@wibly/internal-manifest';
 import type { z, ZodTypeAny } from 'zod';
 
 import { zodToJsonSchema, type JsonSchema } from '@wibly/internal-shared';
@@ -39,52 +10,16 @@ import type { Result } from '@wibly/internal-shared';
 
 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).
- */
-export type SdkQualityTier = 'preview' | 'standard' | 'high';
-
-/**
- * Recognised call kinds. Matches `CallKindSchema`'s enum; duplicated
- * here to keep the SDK type-only against the manifest package.
- *
- * `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.
- */
-export type SdkCallKind =
-  | 'host_open_phase'
-  | 'narrate_event'
-  | 'judge_submissions'
-  | 'host_persona_response'
-  | 'classify'
-  | (string & {});
-
 export type InferenceCallInput<TOutput extends ZodTypeAny> = {
-  readonly callKind: SdkCallKind;
+  readonly templateId: string;
   readonly slots: Readonly<Record<string, unknown>>;
   readonly output?: TOutput;
-  readonly qualityTier?: SdkQualityTier;
-  /**
-   * Optional idempotency key. The Runtime forwards it to the
-   * Gateway's `metadata.idempotencyKey`. Use case: a host that
-   * wants to retry without double-billing.
-   */
   readonly idempotencyKey?: string;
 };
 
 export type InferenceCallSuccess<TOutput extends ZodTypeAny> = {
-  /** Raw model output (the Gateway's `output`). */
   readonly output: string;
-  /** Parsed structured response. `null` if no schema was provided. */
   readonly structured: TOutput extends ZodTypeAny ? z.infer<TOutput> | null : null;
-  /** Gateway usage block. Surface for debug; the operator-side
-   * dashboards use the audit ledger instead. */
   readonly usage: {
     readonly model: string;
     readonly tokensIn: number;
@@ -95,8 +30,7 @@ export type InferenceCallSuccess<TOutput extends ZodTypeAny> = {
 };
 
 export type SerialisedInferenceRequest = {
-  readonly callKind: SdkCallKind;
-  readonly qualityTier: SdkQualityTier;
+  readonly templateId: string;
   readonly slots: Readonly<Record<string, unknown>>;
   readonly outputSchema: JsonSchema | undefined;
   readonly idempotencyKey: string | undefined;
@@ -104,37 +38,19 @@ export type SerialisedInferenceRequest = {
 
 export const INFERENCE_EVENT_PREFIX = 'inference.' as const;
 
-/**
- * Build the wire payload for an inference call. Surfaced as a pure
- * helper so the testkit can assert the serialised shape without
- * spinning a transport.
- */
 export const buildInferenceRequest = <TOutput extends ZodTypeAny>(
   input: InferenceCallInput<TOutput>,
 ): SerialisedInferenceRequest => ({
-  callKind: input.callKind,
-  qualityTier: input.qualityTier ?? 'standard',
+  templateId: input.templateId,
   slots: input.slots,
   outputSchema: input.output ? zodToJsonSchema(input.output) : undefined,
   idempotencyKey: input.idempotencyKey,
 });
 
-/**
- * The async `Session.inference` namespace. Each verb is bound by
- * `client.ts` to the live transport; the Runtime wires up the
- * server-side response under chunk B8a.
- */
+export type SdkQualityTier = QualityTier;
+
 export type SessionInference = {
   readonly call: <TOutput extends ZodTypeAny = ZodTypeAny>(
     input: InferenceCallInput<TOutput>,
   ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
-  readonly host: <TOutput extends ZodTypeAny = ZodTypeAny>(
-    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
-  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
-  readonly judge: <TOutput extends ZodTypeAny = ZodTypeAny>(
-    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
-  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
-  readonly classify: <TOutput extends ZodTypeAny = ZodTypeAny>(
-    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
-  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
 };

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/time.ts

@@ -24,6 +24,10 @@ export type ServerTimeSource = {
   readonly recordedEvents: () => readonly RecordedEvent[];
   /** Internal: update the measured skew on a fresh pong. */
   readonly updateSkew: (skewMs: number) => void;
+  /** Freeze `serverNow()` while the session is paused. */
+  readonly freeze: () => void;
+  /** Resume advancing `serverNow()` after a pause. */
+  readonly unfreeze: () => void;
 };
 
 export type RecordedEvent = {
@@ -40,10 +44,14 @@ export const createServerTimeSource = (
 ): ServerTimeSource => {
   const nowFn = opts.now ?? (() => Date.now());
   let skew = 0;
+  let frozenServerNow: number | null = null;
   const events: RecordedEvent[] = [];
 
   return {
-    serverNow: () => nowFn() + skew,
+    serverNow: () => {
+      if (frozenServerNow !== null) return frozenServerNow;
+      return nowFn() + skew;
+    },
     recordEvent: (eventId) => {
       const clientTs = nowFn();
       events.push({ eventId, clientTs });
@@ -54,5 +62,13 @@ export const createServerTimeSource = (
     updateSkew: (newSkew) => {
       skew = newSkew;
     },
+    freeze: () => {
+      if (frozenServerNow === null) {
+        frozenServerNow = nowFn() + skew;
+      }
+    },
+    unfreeze: () => {
+      frozenServerNow = null;
+    },
   };
 };

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.
@@ -46,6 +47,27 @@ export type SpeakSuccess = {
   readonly durationMs: number;
 };
 
+/** Optional beat metadata for in-phase TTS choreography (chunk B26). */
+export type TtsBeatReveal = {
+  readonly kind: 'none' | 'player_submission';
+  readonly playerId?: string;
+};
+
+export type TtsBeatMeta = {
+  readonly beatId: string;
+  readonly sequence: number;
+  readonly reveal?: TtsBeatReveal;
+};
+
+/** Wire shape on `voice.audio` events (Host + Experience bundles). */
+export type VoiceAudioPayload = SpeakSuccess & {
+  readonly id?: string;
+  readonly causeMessageId?: string;
+  readonly caption?: string | null;
+  readonly beat?: TtsBeatMeta;
+  readonly cues?: ReadonlyArray<{ readonly at: number; readonly kind: string }>;
+};
+
 export type SessionVoice = {
   readonly speak: (input: SpeakInput) => Promise<Result<SpeakSuccess, SdkError>>;
 };