@wibly/sdk 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # `@wibly/sdk` — Changelog
 
+## 0.1.3 — 2026-06-08
+
+## 0.1.3 — 2026-06-08
+
+### Added
+
+- `session.ttsPlayback` — client-side TTS playback telemetry
+  (`subscribe` / `getSnapshot`) exposing `{ isPlaying, speechLevel }`.
+  The Host shell samples speech energy from its single `<audio>` element
+  and pushes smoothed levels via `setTtsPlaybackTelemetry(session, …)` so
+  Experience bundles can drive amplitude-synced avatar animation without
+  high-frequency `voice.*` events on the wire.
+- `@wibly/sdk/react` — `useTtsPlayback()` hook wrapping the telemetry
+  store for shell and bundle React trees.
+
+## 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

package/package.json

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

package/src/client.ts

@@ -77,6 +77,11 @@ import {
   createServerTimeSource,
   type ServerTimeSource,
 } from './time.js';
+import {
+  createTtsPlaybackStore,
+  registerTtsPlaybackStore,
+  type TtsPlaybackTelemetry,
+} from './tts-playback.js';
 import {
   createTransport,
   type Transport,
@@ -181,10 +186,36 @@ 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;
   readonly voice: SessionVoice;
+  /**
+   * Client-side TTS playback telemetry (speech energy + playing
+   * flag). Populated by the Host shell from the local audio element;
+   * read by Experience bundles to drive avatar animation. Never
+   * crosses the wire. See `tts-playback.ts`.
+   */
+  readonly ttsPlayback: TtsPlaybackTelemetry;
   readonly events: Pick<EventBus, 'onEvent' | 'onAnyEvent'>;
   readonly lifecycle: LifecycleBindings;
   /** Server-time helper. See `time.ts`. */
@@ -221,6 +252,7 @@ const DEFAULT_VOICE_SPEAK_TIMEOUT_MS = 30_000;
 export const createSession = (config: SessionConfig): Session => {
   const store = createSessionStore();
   const bus = createEventBus();
+  const ttsPlaybackStore = createTtsPlaybackStore();
   const time = createServerTimeSource({ now: config.now });
   const lifecycle = createLifecycleBindings(bus);
   let isPreviewFlag: boolean = config.isPreview ?? false;
@@ -310,9 +342,11 @@ export const createSession = (config: SessionConfig): Session => {
           ? '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;
@@ -481,6 +515,8 @@ export const createSession = (config: SessionConfig): Session => {
       audioBase64: string;
       contentType?: unknown;
       durationMs?: unknown;
+      beat?: unknown;
+      cues?: unknown;
     },
     caption: string | null | undefined,
   ): void => {
@@ -499,6 +535,11 @@ export const createSession = (config: SessionConfig): Session => {
             ? 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 } : {}),
       },
     });
   };
@@ -510,37 +551,57 @@ export const createSession = (config: SessionConfig): Session => {
       contentType?: string;
       durationMs?: number;
       kind?: string;
+      beat?: unknown;
+      cues?: unknown;
     } | null;
-    if (!data || typeof data.causeMessageId !== 'string') return;
-    const causeId = data.causeMessageId as unknown as MessageId;
-    const pending = pendingVoice.get(causeId);
-    const caption = pending?.caption;
-    const audioBase64 = data.audioBase64;
+    if (!data) return;
 
-    if (
+    const audioBase64 = data.audioBase64;
+    const isSpeakResult =
       payload.eventType === 'voice.speak.result' &&
-      typeof audioBase64 === 'string'
-    ) {
+      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,
         },
-        caption ?? null,
+        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(causeId);
-    transport.confirmSend(causeId);
+    pendingVoice.delete(causeMessageId);
+    transport.confirmSend(causeMessageId);
 
-    if (
-      payload.eventType === 'voice.speak.result' &&
-      typeof audioBase64 === 'string'
-    ) {
+    if (isSpeakResult) {
       pending.resolve(
         ok({
           audioBase64,
@@ -711,6 +772,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,
@@ -732,6 +819,10 @@ export const createSession = (config: SessionConfig): Session => {
       scheduleTimer,
       voiceSpeakTimeoutMs,
     ),
+    ttsPlayback: {
+      subscribe: ttsPlaybackStore.subscribe,
+      getSnapshot: ttsPlaybackStore.getSnapshot,
+    },
     events: { onEvent: bus.onEvent, onAnyEvent: bus.onAnyEvent },
     lifecycle,
     time: { serverNow: time.serverNow, recordEvent: time.recordEvent },
@@ -762,6 +853,8 @@ export const createSession = (config: SessionConfig): Session => {
     },
   };
 
+  registerTtsPlaybackStore(session, ttsPlaybackStore);
+
   transport.start();
   return session;
 };
@@ -805,7 +898,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);
@@ -824,16 +917,6 @@ 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: 'host_judge' }),
-    classify: (input) => call({ ...input, callKind: 'classify' }),
   };
 };
 

package/src/control.ts

@@ -15,6 +15,9 @@
  *   - `host.resume`         — resume from pause.
  *   - `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).
@@ -26,6 +29,9 @@ export const HOST_EVENT_TYPES = {
   pause: 'host.pause',
   resume: 'host.resume',
   advancePhase: 'host.advancePhase',
+  abort: 'host.abort',
+  ttsPlayback: 'host.ttsPlayback',
+  ttsBeat: 'host.ttsBeat',
   reclaim: 'host.reclaim',
 } as const;
 

package/src/index.ts

@@ -67,7 +67,6 @@ export {
   buildInferenceRequest,
   type InferenceCallInput,
   type InferenceCallSuccess,
-  type SdkCallKind,
   type SdkQualityTier,
   type SerialisedInferenceRequest,
   type SessionInference,
@@ -79,8 +78,20 @@ export {
   type SessionVoice,
   type SpeakInput,
   type SpeakSuccess,
+  type TtsBeatMeta,
+  type TtsBeatReveal,
+  type VoiceAudioPayload,
 } from './voice.js';
 
+export {
+  createTtsPlaybackStore,
+  registerTtsPlaybackStore,
+  setTtsPlaybackTelemetry,
+  type TtsPlaybackSnapshot,
+  type TtsPlaybackStore,
+  type TtsPlaybackTelemetry,
+} from './tts-playback.js';
+
 export {
   type EventBus,
   type EventHandler,

package/src/inference.ts

@@ -1,98 +1,25 @@
 /**
- * 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';
 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. 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 = QualityTier;
-
-/**
- * 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.
- *
- * 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 = CallKind | (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;
@@ -103,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;
@@ -112,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/react.ts

@@ -37,6 +37,7 @@ import type { EventPayload, LifecyclePayload } from '@wibly/internal-protocol';
 import type { ConsentDecision, ConsentRequiredPayload } from './consent.js';
 import type { Session, SessionConfig, SessionState } from './client.js';
 import { createSession } from './client.js';
+import type { TtsPlaybackSnapshot } from './tts-playback.js';
 
 const SessionContext = createContext<Session | null>(null);
 
@@ -121,6 +122,20 @@ export const useConnectionState = (): SessionState['connectionState'] => {
   return state.connectionState;
 };
 
+/**
+ * Subscribe to client-side TTS playback telemetry (speech energy +
+ * playing flag). Populated by the Host shell's audio sampler; idle
+ * until the first clip plays.
+ */
+export const useTtsPlayback = (): TtsPlaybackSnapshot => {
+  const session = useSession();
+  return useSyncExternalStore(
+    session.ttsPlayback.subscribe,
+    session.ttsPlayback.getSnapshot,
+    session.ttsPlayback.getSnapshot,
+  );
+};
+
 /**
  * Subscribe to a server-emitted event by `eventType`. The handler
  * fires on every matching `event` frame. Unsubscribes on unmount.

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/tts-playback.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createTtsPlaybackStore,
+  registerTtsPlaybackStore,
+  setTtsPlaybackTelemetry,
+} from './tts-playback.js';
+
+describe('createTtsPlaybackStore', () => {
+  it('starts idle', () => {
+    const store = createTtsPlaybackStore();
+    expect(store.getSnapshot()).toEqual({ isPlaying: false, speechLevel: 0 });
+  });
+
+  it('notifies subscribers when the snapshot changes', () => {
+    const store = createTtsPlaybackStore();
+    const listener = vi.fn();
+    const unsubscribe = store.subscribe(listener);
+
+    store.set({ isPlaying: true, speechLevel: 0.5 });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(store.getSnapshot()).toEqual({ isPlaying: true, speechLevel: 0.5 });
+
+    unsubscribe();
+    store.set({ isPlaying: false, speechLevel: 0 });
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats an identical set as a no-op and keeps a stable reference', () => {
+    const store = createTtsPlaybackStore();
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    const before = store.getSnapshot();
+    store.set({ isPlaying: false, speechLevel: 0 });
+
+    // useSyncExternalStore depends on a stable reference when nothing
+    // changed — otherwise it re-renders (or warns) every read.
+    expect(store.getSnapshot()).toBe(before);
+    expect(listener).not.toHaveBeenCalled();
+  });
+});
+
+describe('setTtsPlaybackTelemetry', () => {
+  it('routes a sample to the registered store', () => {
+    const session = {};
+    const store = createTtsPlaybackStore();
+    registerTtsPlaybackStore(session, store);
+
+    setTtsPlaybackTelemetry(session, { isPlaying: true, speechLevel: 0.8 });
+
+    expect(store.getSnapshot()).toEqual({ isPlaying: true, speechLevel: 0.8 });
+  });
+
+  it('is a no-op for a session with no registered store', () => {
+    expect(() =>
+      setTtsPlaybackTelemetry({}, { isPlaying: true, speechLevel: 1 }),
+    ).not.toThrow();
+  });
+});

package/src/tts-playback.ts

@@ -0,0 +1,99 @@
+/**
+ * Client-side TTS playback telemetry.
+ *
+ * This is a purely local, ephemeral signal — it never touches the
+ * WebSocket. The Host shell samples speech energy from the single
+ * `<audio>` element (Web Audio `AnalyserNode`) and pushes a smoothed
+ * `speechLevel` here at animation-frame cadence; Experience bundles
+ * read it through `session.ttsPlayback` to drive avatar animation
+ * (the amplitude-driven fallback the Platform Spec §3.5 describes for
+ * providers without phoneme metadata).
+ *
+ * Why a dedicated store and not a `voice.*` event: the signal updates
+ * ~60×/sec. Pumping that through `session.events` would flood every
+ * listener and the wire-shaped bus machinery. A tiny
+ * `useSyncExternalStore`-friendly snapshot store keeps the hot path
+ * cheap and matches the SDK's existing one-store-per-concern pattern.
+ *
+ * The read surface (`subscribe` / `getSnapshot`) is public on
+ * `Session.ttsPlayback`. The write surface lives behind
+ * `setTtsPlaybackTelemetry(session, snapshot)` so only the shell that
+ * owns the audio element mutates it — bundles consume, never produce.
+ */
+
+export type TtsPlaybackSnapshot = {
+  /** True while a TTS clip is actively playing. */
+  readonly isPlaying: boolean;
+  /** Smoothed speech energy, normalised to 0..1. */
+  readonly speechLevel: number;
+};
+
+/** Read surface exposed on `Session.ttsPlayback`. */
+export type TtsPlaybackTelemetry = {
+  readonly subscribe: (listener: () => void) => () => void;
+  readonly getSnapshot: () => TtsPlaybackSnapshot;
+};
+
+/** Full store — the read surface plus the shell-only setter. */
+export type TtsPlaybackStore = TtsPlaybackTelemetry & {
+  readonly set: (next: TtsPlaybackSnapshot) => void;
+};
+
+const IDLE: TtsPlaybackSnapshot = { isPlaying: false, speechLevel: 0 };
+
+export const createTtsPlaybackStore = (): TtsPlaybackStore => {
+  let snapshot: TtsPlaybackSnapshot = IDLE;
+  const listeners = new Set<() => void>();
+
+  return {
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot: () => snapshot,
+    set: (next) => {
+      if (
+        next.isPlaying === snapshot.isPlaying &&
+        next.speechLevel === snapshot.speechLevel
+      ) {
+        return;
+      }
+      snapshot = next;
+      for (const listener of Array.from(listeners)) {
+        try {
+          listener();
+        } catch {
+          // Listeners must not throw; swallow to avoid cascading.
+        }
+      }
+    },
+  };
+};
+
+/**
+ * Registry mapping a `Session` to its writable telemetry store. The
+ * `Session` only exposes the read surface, so the shell pushes
+ * samples through this side channel keyed by the session reference.
+ */
+const storeRegistry = new WeakMap<object, TtsPlaybackStore>();
+
+export const registerTtsPlaybackStore = (
+  session: object,
+  store: TtsPlaybackStore,
+): void => {
+  storeRegistry.set(session, store);
+};
+
+/**
+ * Push a telemetry sample for the given session. No-op if the session
+ * has no registered store (e.g. a stub session in a dev harness that
+ * supplies its own `ttsPlayback`).
+ */
+export const setTtsPlaybackTelemetry = (
+  session: object,
+  snapshot: TtsPlaybackSnapshot,
+): void => {
+  storeRegistry.get(session)?.set(snapshot);
+};

package/src/voice.ts

@@ -47,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>>;
 };