@voicethere/agent 0.7.12 → 0.7.13

package/dist/templates/spatial-showcase/agent.js

@@ -1137,6 +1137,8 @@ function resolveClipUrl(assetOrigin, clipId) {
 var SHOWCASE_DEMOS = /* @__PURE__ */ new Set(["orbit", "soundboard", "proximity"]);
 var MAX_SAY_TEXT_LENGTH = 200;
 var MAX_XZ = 5;
+var ORBIT_SINE_MIN_FREQUENCY_HZ = 110;
+var ORBIT_SINE_MAX_FREQUENCY_HZ = 1760;
 function isFiniteNumber(value) {
   return typeof value === "number" && Number.isFinite(value);
 }
@@ -1146,6 +1148,9 @@ function clampVolume(value) {
 function isInXzRange(value) {
   return value >= -MAX_XZ && value <= MAX_XZ;
 }
+function isOrbitSineFrequencyHz(value) {
+  return value >= ORBIT_SINE_MIN_FREQUENCY_HZ && value <= ORBIT_SINE_MAX_FREQUENCY_HZ;
+}
 function isMixPlacement(value) {
   return value === "center" || value === "left" || value === "right" || value === "front" || value === "behind" || value === "below" || value === "above";
 }
@@ -1194,15 +1199,33 @@ function parseShowcaseMessage(message) {
         if (set.paused !== void 0 && typeof set.paused !== "boolean") {
           return null;
         }
+        if (set.frequencyHz !== void 0 && (!isFiniteNumber(set.frequencyHz) || !isOrbitSineFrequencyHz(set.frequencyHz))) {
+          return null;
+        }
+        if (set.sinePlaying !== void 0 && typeof set.sinePlaying !== "boolean") {
+          return null;
+        }
         return {
           type: "orbit",
           action: "set",
           ...set.radius !== void 0 ? { radius: set.radius } : {},
           ...set.periodSec !== void 0 ? { periodSec: set.periodSec } : {},
           ...set.elevation !== void 0 ? { elevation: set.elevation } : {},
-          ...set.paused !== void 0 ? { paused: set.paused } : {}
+          ...set.paused !== void 0 ? { paused: set.paused } : {},
+          ...set.frequencyHz !== void 0 ? { frequencyHz: set.frequencyHz } : {},
+          ...set.sinePlaying !== void 0 ? { sinePlaying: set.sinePlaying } : {}
         };
       }
+      if (orbit.action === "place") {
+        const place = message;
+        if (!isFiniteNumber(place.x) || !isInXzRange(place.x)) {
+          return null;
+        }
+        if (!isFiniteNumber(place.z) || !isInXzRange(place.z)) {
+          return null;
+        }
+        return { type: "orbit", action: "place", x: place.x, z: place.z };
+      }
       if (orbit.action === "say") {
         const say = message;
         if (typeof say.text !== "string" || say.text.length === 0 || say.text.length > MAX_SAY_TEXT_LENGTH) {
@@ -1254,6 +1277,24 @@ function parseShowcaseMessage(message) {
       }
       return { type: "pad_status", playId: status.playId.trim() };
     }
+    case "pad_move": {
+      const padMove = message;
+      if (!isNonEmptyString(padMove.playId)) {
+        return null;
+      }
+      if (!isFiniteNumber(padMove.x) || !isInXzRange(padMove.x)) {
+        return null;
+      }
+      if (!isFiniteNumber(padMove.z) || !isInXzRange(padMove.z)) {
+        return null;
+      }
+      return {
+        type: "pad_move",
+        playId: padMove.playId.trim(),
+        x: padMove.x,
+        z: padMove.z
+      };
+    }
     case "move": {
       const move = message;
       if (!isFiniteNumber(move.x) || !isInXzRange(move.x)) {
@@ -1368,12 +1409,22 @@ var ProximityRoom = class {
 var ORBIT_SINE_DURATION_MS = 2e3;
 var ORBIT_SINE_FREQUENCY_HZ = 440;
 var ORBIT_SINE_AMPLITUDE = 8e3;
+var ORBIT_SINE_SAMPLE_RATE = 16e3;
 var ORBIT_SINE_INLINE_URL = "https://example.com/inline-orbit-sine.wav";
-function buildOrbitSineInlineClipBase64(durationMs = ORBIT_SINE_DURATION_MS, frequencyHz = ORBIT_SINE_FREQUENCY_HZ, amplitude = ORBIT_SINE_AMPLITUDE) {
-  const sampleRate = 16e3;
+function orbitSineSampleCount(durationMs = ORBIT_SINE_DURATION_MS, frequencyHz = ORBIT_SINE_FREQUENCY_HZ, sampleRate = ORBIT_SINE_SAMPLE_RATE) {
+  const targetCycles = durationMs / 1e3 * frequencyHz;
+  const cycles = Math.max(1, Math.floor(targetCycles));
+  return Math.round(cycles * sampleRate / frequencyHz);
+}
+function orbitSineClipDurationMs(durationMs = ORBIT_SINE_DURATION_MS, frequencyHz = ORBIT_SINE_FREQUENCY_HZ, sampleRate = ORBIT_SINE_SAMPLE_RATE) {
+  const numSamples = orbitSineSampleCount(durationMs, frequencyHz, sampleRate);
+  return numSamples / sampleRate * 1e3;
+}
+function buildOrbitSineInlineClipBase64(durationMs = ORBIT_SINE_DURATION_MS, frequencyHz = ORBIT_SINE_FREQUENCY_HZ, amplitude = ORBIT_SINE_AMPLITUDE, phaseRad = 0) {
+  const sampleRate = ORBIT_SINE_SAMPLE_RATE;
   const channels = 1;
   const bytesPerSample = 2;
-  const numSamples = Math.floor(sampleRate * durationMs / 1e3);
+  const numSamples = orbitSineSampleCount(durationMs, frequencyHz, sampleRate);
   const dataSize = numSamples * channels * bytesPerSample;
   const buffer = Buffer.alloc(44 + dataSize);
   buffer.write("RIFF", 0);
@@ -1392,7 +1443,7 @@ function buildOrbitSineInlineClipBase64(durationMs = ORBIT_SINE_DURATION_MS, fre
   for (let i = 0; i < numSamples; i++) {
     const t = i / sampleRate;
     const sample = Math.round(
-      amplitude * Math.sin(2 * Math.PI * frequencyHz * t)
+      amplitude * Math.sin(2 * Math.PI * frequencyHz * t + phaseRad)
     );
     buffer.writeInt16LE(sample, 44 + i * 2);
   }
@@ -1405,6 +1456,7 @@ var ORBIT_POSE_EMIT_MS = 100;
 var ROOM_STATE_TICK_MS = 100;
 var LOOP_PAD_POLL_MS = 250;
 var ORBIT_SINE_POLL_MS = 250;
+var ORBIT_SINE_GAPLESS_LEAD_MS = 200;
 var ORBIT_SINE_VOLUME = 0.25;
 var MAX_ACTIVE_PLAYS = 12;
 var SHOWCASE_ROOM_GROUP_ID = "showcase-room";
@@ -1467,6 +1519,9 @@ function defaultSessionState(demo, assetOrigin) {
     playIds: /* @__PURE__ */ new Set(),
     loopPads: /* @__PURE__ */ new Map(),
     loopPollTimers: /* @__PURE__ */ new Map(),
+    orbitSineFrequencyHz: 440,
+    orbitSineEnabled: true,
+    orbitSinePhaseRad: 0,
     inProximityRoom: false
   };
 }
@@ -1508,27 +1563,114 @@ function clearAllPlays(sessionId, state) {
   state.loopPollTimers.clear();
 }
 function currentOrbitPose(state) {
+  if (state.orbitManualPose) {
+    const elevation = state.orbit.elevation ?? 0;
+    return {
+      position: {
+        x: state.orbitManualPose.x,
+        y: elevation,
+        z: state.orbitManualPose.z
+      },
+      orientation: { x: 0, y: 0, z: 0, w: 1 }
+    };
+  }
   if (!state.orbitStartMs) {
     return orbitTtsPose(0, state.orbit);
   }
   const elapsedSec = (Date.now() - state.orbitStartMs) / 1e3;
   return orbitTtsPose(elapsedSec, state.orbit);
 }
+function orbitPoseFromXz(state, x, z) {
+  const elevation = state.orbit.elevation ?? 0;
+  return {
+    position: { x, y: elevation, z },
+    orientation: { x: 0, y: 0, z: 0, w: 1 }
+  };
+}
+function syncOrbitClockFromManualPose(state) {
+  const manual = state.orbitManualPose;
+  if (!manual) {
+    return;
+  }
+  const periodSec = state.orbit.periodSec ?? 2 * Math.PI;
+  const angleRad = Math.atan2(manual.z, manual.x);
+  const elapsedSec = angleRad * periodSec / (2 * Math.PI);
+  state.orbitStartMs = Date.now() - elapsedSec * 1e3;
+  state.orbitManualPose = void 0;
+}
 function clearOrbitSinePoll(state) {
   if (state.orbitSinePollTimer) {
     clearInterval(state.orbitSinePollTimer);
     state.orbitSinePollTimer = void 0;
   }
 }
+function clearOrbitSineRestartTimer(state) {
+  if (state.orbitSineRestartTimer) {
+    clearTimeout(state.orbitSineRestartTimer);
+    state.orbitSineRestartTimer = void 0;
+  }
+}
 async function stopOrbitSine(state) {
   clearOrbitSinePoll(state);
+  clearOrbitSineRestartTimer(state);
   const playId = state.orbitSinePlayId;
   state.orbitSinePlayId = void 0;
   if (playId) {
     await stopPlay(playId);
   }
 }
+function orbitSineClipBytes(state) {
+  return buildOrbitSineInlineClipBase64(
+    ORBIT_SINE_DURATION_MS,
+    state.orbitSineFrequencyHz,
+    void 0,
+    state.orbitSinePhaseRad
+  );
+}
+function orbitSineClipDuration(state) {
+  return orbitSineClipDurationMs(
+    ORBIT_SINE_DURATION_MS,
+    state.orbitSineFrequencyHz
+  );
+}
+function scheduleOrbitSineGaplessRestart(sessionId, state) {
+  clearOrbitSineRestartTimer(state);
+  const durationMs = orbitSineClipDuration(state);
+  const delayMs = Math.max(0, durationMs - ORBIT_SINE_GAPLESS_LEAD_MS);
+  state.orbitSineRestartTimer = setTimeout(() => {
+    state.orbitSineRestartTimer = void 0;
+    void restartOrbitSineGapless(sessionId, state);
+  }, delayMs);
+}
+async function restartOrbitSineGapless(sessionId, state) {
+  if (!state.orbitSineEnabled || !state.orbitSinePlayId) {
+    return;
+  }
+  const previousPlayId = state.orbitSinePlayId;
+  const result = await play({
+    url: ORBIT_SINE_INLINE_URL,
+    bytes: orbitSineClipBytes(state),
+    sessionIds: [sessionId],
+    volume: ORBIT_SINE_VOLUME,
+    pose: currentOrbitPose(state)
+  });
+  if (!result.ok || !result.playId) {
+    agentLog(
+      "warn",
+      `spatial-showcase orbit sine gapless restart failed: ${result.reason ?? "play_failed"}`,
+      sessionId
+    );
+    startOrbitSineLoopPoll(sessionId, state);
+    return;
+  }
+  state.orbitSinePlayId = result.playId;
+  void stopPlay(previousPlayId);
+  scheduleOrbitSineGaplessRestart(sessionId, state);
+}
 function startOrbitSineLoopPoll(sessionId, state) {
+  if (state.orbitSineRestartTimer) {
+    return;
+  }
   clearOrbitSinePoll(state);
   const playId = state.orbitSinePlayId;
   if (!playId) {
@@ -1536,7 +1678,7 @@ function startOrbitSineLoopPoll(sessionId, state) {
   }
   state.orbitSinePollTimer = setInterval(() => {
     void (async () => {
-      if (!state.orbitSinePlayId) {
+      if (!state.orbitSinePlayId || state.orbitSineRestartTimer) {
         clearOrbitSinePoll(state);
         return;
       }
@@ -1545,25 +1687,19 @@ function startOrbitSineLoopPoll(sessionId, state) {
         return;
       }
       if (status.status === "ended") {
-        const replay = await play({
-          url: ORBIT_SINE_INLINE_URL,
-          bytes: buildOrbitSineInlineClipBase64(),
-          sessionIds: [sessionId],
-          volume: ORBIT_SINE_VOLUME,
-          pose: currentOrbitPose(state)
-        });
-        if (replay.ok && replay.playId) {
-          state.orbitSinePlayId = replay.playId;
-        }
+        await restartOrbitSineGapless(sessionId, state);
       }
     })();
   }, ORBIT_SINE_POLL_MS);
 }
 async function startOrbitSinePlay(sessionId, state) {
+  if (!state.orbitSineEnabled) {
+    return;
+  }
   await stopOrbitSine(state);
   const result = await play({
     url: ORBIT_SINE_INLINE_URL,
-    bytes: buildOrbitSineInlineClipBase64(),
+    bytes: orbitSineClipBytes(state),
     sessionIds: [sessionId],
     volume: ORBIT_SINE_VOLUME,
     pose: currentOrbitPose(state)
@@ -1577,10 +1713,11 @@ async function startOrbitSinePlay(sessionId, state) {
     return;
   }
   state.orbitSinePlayId = result.playId;
+  scheduleOrbitSineGaplessRestart(sessionId, state);
   startOrbitSineLoopPoll(sessionId, state);
 }
 function emitOrbitPose(sessionId, state) {
-  if (!state.orbitStartMs) {
+  if (!state.orbitStartMs && !state.orbitManualPose) {
     return;
   }
   const now = Date.now();
@@ -1588,9 +1725,8 @@ function emitOrbitPose(sessionId, state) {
     return;
   }
   state.lastOrbitPoseEmitMs = now;
-  const elapsedSec = (now - state.orbitStartMs) / 1e3;
-  const pose = orbitTtsPose(elapsedSec, state.orbit);
-  const angleRad = 2 * Math.PI * elapsedSec / (state.orbit.periodSec ?? 2 * Math.PI);
+  const pose = currentOrbitPose(state);
+  const angleRad = state.orbitManualPose ? Math.atan2(state.orbitManualPose.z, state.orbitManualPose.x) : 2 * Math.PI * (now - state.orbitStartMs) / 1e3 / (state.orbit.periodSec ?? 2 * Math.PI);
   sendToClient(sessionId, {
     type: "orbit_pose",
     angleDeg: angleRad * 180 / Math.PI,
@@ -1598,12 +1734,22 @@ function emitOrbitPose(sessionId, state) {
     z: pose.position.z
   });
 }
+function emitOrbitPlacePose(sessionId, state, x, z) {
+  state.lastOrbitPoseEmitMs = Date.now();
+  const angleRad = Math.atan2(z, x);
+  sendToClient(sessionId, {
+    type: "orbit_pose",
+    angleDeg: angleRad * 180 / Math.PI,
+    x,
+    z
+  });
+}
 function startOrbitDemo(sessionId, state) {
   stopOrbitInterval(state);
   beginOrbitClock(state);
   void startOrbitSinePlay(sessionId, state);
   state.orbitTimer = setInterval(() => {
-    if (state.orbit.paused || !state.orbitStartMs) {
+    if (state.orbit.paused || !state.orbitStartMs && !state.orbitManualPose) {
       return;
     }
     const pose = currentOrbitPose(state);
@@ -1758,6 +1904,24 @@ async function handlePadPlay(sessionId, state, clipId, x, z, volume, placement)
     void startLoopPadPoll(sessionId, state, result.playId, pad);
   }
 }
+async function handlePadMove(sessionId, state, playId, x, z) {
+  if (!state.playIds.has(playId)) {
+    ackError(sessionId, "pad_move", "unknown_play");
+    return;
+  }
+  const poseResult = await setPlayPose(playId, poseAt(x, z));
+  if (!poseResult.ok) {
+    ackError(sessionId, "pad_move", poseResult.reason ?? "set_pose_failed");
+    return;
+  }
+  const loopPad = state.loopPads.get(playId);
+  if (loopPad) {
+    loopPad.x = x;
+    loopPad.z = z;
+    delete loopPad.placement;
+  }
+  ack(sessionId, "pad_move", { playId, x, z });
+}
 async function handleJoin(sessionId, demo, assetOrigin) {
   teardownSession(sessionId);
   const state = defaultSessionState(demo, assetOrigin);
@@ -1884,11 +2048,54 @@ async function dispatchMessage(sessionId, message) {
           state.orbit.elevation = message.elevation;
         }
         if (message.paused !== void 0) {
+          if (message.paused === false && state.orbitManualPose) {
+            syncOrbitClockFromManualPose(state);
+          }
           state.orbit.paused = message.paused;
         }
+        if (message.frequencyHz !== void 0) {
+          state.orbitSineFrequencyHz = message.frequencyHz;
+          if (state.orbitSineEnabled && state.orbitSinePlayId) {
+            void startOrbitSinePlay(sessionId, state);
+          }
+        }
+        if (message.sinePlaying !== void 0) {
+          state.orbitSineEnabled = message.sinePlaying;
+          if (message.sinePlaying) {
+            if (!state.orbitSinePlayId) {
+              void startOrbitSinePlay(sessionId, state);
+            }
+          } else {
+            void stopOrbitSine(state);
+          }
+        }
         ack(sessionId, "orbit_set");
         return;
       }
+      if (message.action === "place") {
+        state.orbit.paused = true;
+        state.orbitManualPose = { x: message.x, z: message.z };
+        const pose = orbitPoseFromXz(state, message.x, message.z);
+        if (state.orbitSinePlayId) {
+          void safeMixCall(
+            sessionId,
+            "setPlayPose",
+            () => setPlayPose(state.orbitSinePlayId, pose)
+          );
+        }
+        void safeMixCall(
+          sessionId,
+          "setTtsPose",
+          () => setTtsPose(sessionId, pose)
+        );
+        emitOrbitPlacePose(sessionId, state, message.x, message.z);
+        ack(sessionId, "orbit_place");
+        return;
+      }
+      sendToClient(sessionId, {
+        type: "orbit_say_status",
+        status: "playing"
+      });
       speak(sessionId, message.text);
       ack(sessionId, "orbit_say");
       return;
@@ -1945,6 +2152,20 @@ async function dispatchMessage(sessionId, message) {
       }
       return;
     }
+    case "pad_move": {
+      if (state.demo !== "soundboard") {
+        ackError(sessionId, "pad_move", "wrong_demo");
+        return;
+      }
+      await handlePadMove(
+        sessionId,
+        state,
+        message.playId,
+        message.x,
+        message.z
+      );
+      return;
+    }
     case "move": {
       if (state.demo !== "proximity") {
         ackError(sessionId, "move", "wrong_demo");
@@ -2027,6 +2248,23 @@ defineAgent({
     }
     void dispatchMessage(ctx.sessionId, message);
   },
+  onSpeechEvent(ctx, event) {
+    const state = sessions.get(ctx.sessionId);
+    if (!state || state.demo !== "orbit") {
+      return;
+    }
+    if (event.type === "agent_speaking_start") {
+      sendToClient(ctx.sessionId, {
+        type: "orbit_say_status",
+        status: "playing"
+      });
+    } else if (event.type === "agent_speaking_end") {
+      sendToClient(ctx.sessionId, {
+        type: "orbit_say_status",
+        status: "ended"
+      });
+    }
+  },
   onSessionEnd({ sessionId }) {
     teardownSession(sessionId);
     agentLog("info", `spatial-showcase session_end ${sessionId}`, sessionId);
@@ -2034,5 +2272,6 @@ defineAgent({
 });
 export {
   MAX_ACTIVE_PLAYS,
+  handlePadMove,
   handlePadPlay
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voicethere/agent",
-  "version": "0.7.12",
+  "version": "0.7.13",
   "description": "VoiceThere customer agent SDK — IPC types and runtime helpers for sandboxed child bundles",
   "type": "module",
   "exports": {

package/templates/spatial-showcase/agent.ts

@@ -51,7 +51,9 @@ import {
 } from "./sounds.js";
 import {
   buildOrbitSineInlineClipBase64,
+  ORBIT_SINE_DURATION_MS,
   ORBIT_SINE_INLINE_URL,
+  orbitSineClipDurationMs,
 } from "./sine.js";
 
 const ORBIT_TICK_MS = 50;
@@ -59,6 +61,7 @@ const ORBIT_POSE_EMIT_MS = 100;
 const ROOM_STATE_TICK_MS = 100;
 const LOOP_PAD_POLL_MS = 250;
 const ORBIT_SINE_POLL_MS = 250;
+const ORBIT_SINE_GAPLESS_LEAD_MS = 200;
 const ORBIT_SINE_VOLUME = 0.25;
 export const MAX_ACTIVE_PLAYS = 12;
 const SHOWCASE_ROOM_GROUP_ID = "showcase-room";
@@ -84,6 +87,11 @@ type SessionState = {
   loopPollTimers: Map<string, ReturnType<typeof setInterval>>;
   orbitSinePlayId?: string;
   orbitSinePollTimer?: ReturnType<typeof setInterval>;
+  orbitSineRestartTimer?: ReturnType<typeof setTimeout>;
+  orbitSineFrequencyHz: number;
+  orbitSineEnabled: boolean;
+  orbitSinePhaseRad: number;
+  orbitManualPose?: { x: number; z: number };
   inProximityRoom: boolean;
   lastOrbitPoseEmitMs?: number;
 };
@@ -175,6 +183,9 @@ function defaultSessionState(
     playIds: new Set(),
     loopPads: new Map(),
     loopPollTimers: new Map(),
+    orbitSineFrequencyHz: 440,
+    orbitSineEnabled: true,
+    orbitSinePhaseRad: 0,
     inProximityRoom: false,
   };
 }
@@ -229,6 +240,17 @@ function clearAllPlays(sessionId: string, state: SessionState): void {
 }
 
 function currentOrbitPose(state: SessionState) {
+  if (state.orbitManualPose) {
+    const elevation = state.orbit.elevation ?? 0;
+    return {
+      position: {
+        x: state.orbitManualPose.x,
+        y: elevation,
+        z: state.orbitManualPose.z,
+      },
+      orientation: { x: 0, y: 0, z: 0, w: 1 },
+    };
+  }
   if (!state.orbitStartMs) {
     return orbitTtsPose(0, state.orbit);
   }
@@ -236,6 +258,30 @@ function currentOrbitPose(state: SessionState) {
   return orbitTtsPose(elapsedSec, state.orbit);
 }
 
+function orbitPoseFromXz(
+  state: SessionState,
+  x: number,
+  z: number,
+): ReturnType<typeof orbitTtsPose> {
+  const elevation = state.orbit.elevation ?? 0;
+  return {
+    position: { x, y: elevation, z },
+    orientation: { x: 0, y: 0, z: 0, w: 1 },
+  };
+}
+
+function syncOrbitClockFromManualPose(state: SessionState): void {
+  const manual = state.orbitManualPose;
+  if (!manual) {
+    return;
+  }
+  const periodSec = state.orbit.periodSec ?? 2 * Math.PI;
+  const angleRad = Math.atan2(manual.z, manual.x);
+  const elapsedSec = (angleRad * periodSec) / (2 * Math.PI);
+  state.orbitStartMs = Date.now() - elapsedSec * 1000;
+  state.orbitManualPose = undefined;
+}
+
 function clearOrbitSinePoll(state: SessionState): void {
   if (state.orbitSinePollTimer) {
     clearInterval(state.orbitSinePollTimer);
@@ -243,8 +289,16 @@ function clearOrbitSinePoll(state: SessionState): void {
   }
 }
 
+function clearOrbitSineRestartTimer(state: SessionState): void {
+  if (state.orbitSineRestartTimer) {
+    clearTimeout(state.orbitSineRestartTimer);
+    state.orbitSineRestartTimer = undefined;
+  }
+}
+
 async function stopOrbitSine(state: SessionState): Promise<void> {
   clearOrbitSinePoll(state);
+  clearOrbitSineRestartTimer(state);
   const playId = state.orbitSinePlayId;
   state.orbitSinePlayId = undefined;
   if (playId) {
@@ -252,7 +306,68 @@ async function stopOrbitSine(state: SessionState): Promise<void> {
   }
 }
 
+function orbitSineClipBytes(state: SessionState): string {
+  return buildOrbitSineInlineClipBase64(
+    ORBIT_SINE_DURATION_MS,
+    state.orbitSineFrequencyHz,
+    undefined,
+    state.orbitSinePhaseRad,
+  );
+}
+
+function orbitSineClipDuration(state: SessionState): number {
+  return orbitSineClipDurationMs(
+    ORBIT_SINE_DURATION_MS,
+    state.orbitSineFrequencyHz,
+  );
+}
+
+function scheduleOrbitSineGaplessRestart(
+  sessionId: string,
+  state: SessionState,
+): void {
+  clearOrbitSineRestartTimer(state);
+  const durationMs = orbitSineClipDuration(state);
+  const delayMs = Math.max(0, durationMs - ORBIT_SINE_GAPLESS_LEAD_MS);
+  state.orbitSineRestartTimer = setTimeout(() => {
+    state.orbitSineRestartTimer = undefined;
+    void restartOrbitSineGapless(sessionId, state);
+  }, delayMs);
+}
+
+async function restartOrbitSineGapless(
+  sessionId: string,
+  state: SessionState,
+): Promise<void> {
+  if (!state.orbitSineEnabled || !state.orbitSinePlayId) {
+    return;
+  }
+  const previousPlayId = state.orbitSinePlayId;
+  const result = await play({
+    url: ORBIT_SINE_INLINE_URL,
+    bytes: orbitSineClipBytes(state),
+    sessionIds: [sessionId],
+    volume: ORBIT_SINE_VOLUME,
+    pose: currentOrbitPose(state),
+  });
+  if (!result.ok || !result.playId) {
+    agentLog(
+      "warn",
+      `spatial-showcase orbit sine gapless restart failed: ${result.reason ?? "play_failed"}`,
+      sessionId,
+    );
+    startOrbitSineLoopPoll(sessionId, state);
+    return;
+  }
+  state.orbitSinePlayId = result.playId;
+  void stopPlay(previousPlayId);
+  scheduleOrbitSineGaplessRestart(sessionId, state);
+}
+
 function startOrbitSineLoopPoll(sessionId: string, state: SessionState): void {
+  if (state.orbitSineRestartTimer) {
+    return;
+  }
   clearOrbitSinePoll(state);
   const playId = state.orbitSinePlayId;
   if (!playId) {
@@ -261,7 +376,7 @@ function startOrbitSineLoopPoll(sessionId: string, state: SessionState): void {
 
   state.orbitSinePollTimer = setInterval(() => {
     void (async () => {
-      if (!state.orbitSinePlayId) {
+      if (!state.orbitSinePlayId || state.orbitSineRestartTimer) {
         clearOrbitSinePoll(state);
         return;
       }
@@ -270,16 +385,7 @@ function startOrbitSineLoopPoll(sessionId: string, state: SessionState): void {
         return;
       }
       if (status.status === "ended") {
-        const replay = await play({
-          url: ORBIT_SINE_INLINE_URL,
-          bytes: buildOrbitSineInlineClipBase64(),
-          sessionIds: [sessionId],
-          volume: ORBIT_SINE_VOLUME,
-          pose: currentOrbitPose(state),
-        });
-        if (replay.ok && replay.playId) {
-          state.orbitSinePlayId = replay.playId;
-        }
+        await restartOrbitSineGapless(sessionId, state);
       }
     })();
   }, ORBIT_SINE_POLL_MS);
@@ -289,10 +395,13 @@ async function startOrbitSinePlay(
   sessionId: string,
   state: SessionState,
 ): Promise<void> {
+  if (!state.orbitSineEnabled) {
+    return;
+  }
   await stopOrbitSine(state);
   const result = await play({
     url: ORBIT_SINE_INLINE_URL,
-    bytes: buildOrbitSineInlineClipBase64(),
+    bytes: orbitSineClipBytes(state),
     sessionIds: [sessionId],
     volume: ORBIT_SINE_VOLUME,
     pose: currentOrbitPose(state),
@@ -306,11 +415,12 @@ async function startOrbitSinePlay(
     return;
   }
   state.orbitSinePlayId = result.playId;
+  scheduleOrbitSineGaplessRestart(sessionId, state);
   startOrbitSineLoopPoll(sessionId, state);
 }
 
 function emitOrbitPose(sessionId: string, state: SessionState): void {
-  if (!state.orbitStartMs) {
+  if (!state.orbitStartMs && !state.orbitManualPose) {
     return;
   }
   const now = Date.now();
@@ -321,10 +431,12 @@ function emitOrbitPose(sessionId: string, state: SessionState): void {
     return;
   }
   state.lastOrbitPoseEmitMs = now;
-  const elapsedSec = (now - state.orbitStartMs) / 1000;
-  const pose = orbitTtsPose(elapsedSec, state.orbit);
-  const angleRad =
-    (2 * Math.PI * elapsedSec) / (state.orbit.periodSec ?? 2 * Math.PI);
+  const pose = currentOrbitPose(state);
+  const angleRad = state.orbitManualPose
+    ? Math.atan2(state.orbitManualPose.z, state.orbitManualPose.x)
+    : (2 * Math.PI * (now - state.orbitStartMs!)) /
+      1000 /
+      (state.orbit.periodSec ?? 2 * Math.PI);
   sendToClient(sessionId, {
     type: "orbit_pose",
     angleDeg: (angleRad * 180) / Math.PI,
@@ -333,12 +445,28 @@ function emitOrbitPose(sessionId: string, state: SessionState): void {
   });
 }
 
+function emitOrbitPlacePose(
+  sessionId: string,
+  state: SessionState,
+  x: number,
+  z: number,
+): void {
+  state.lastOrbitPoseEmitMs = Date.now();
+  const angleRad = Math.atan2(z, x);
+  sendToClient(sessionId, {
+    type: "orbit_pose",
+    angleDeg: (angleRad * 180) / Math.PI,
+    x,
+    z,
+  });
+}
+
 function startOrbitDemo(sessionId: string, state: SessionState): void {
   stopOrbitInterval(state);
   beginOrbitClock(state);
   void startOrbitSinePlay(sessionId, state);
   state.orbitTimer = setInterval(() => {
-    if (state.orbit.paused || !state.orbitStartMs) {
+    if (state.orbit.paused || (!state.orbitStartMs && !state.orbitManualPose)) {
       return;
     }
     const pose = currentOrbitPose(state);
@@ -524,6 +652,34 @@ export async function handlePadPlay(
   }
 }
 
+export async function handlePadMove(
+  sessionId: string,
+  state: SessionState,
+  playId: string,
+  x: number,
+  z: number,
+): Promise<void> {
+  if (!state.playIds.has(playId)) {
+    ackError(sessionId, "pad_move", "unknown_play");
+    return;
+  }
+
+  const poseResult = await setPlayPose(playId, poseAt(x, z));
+  if (!poseResult.ok) {
+    ackError(sessionId, "pad_move", poseResult.reason ?? "set_pose_failed");
+    return;
+  }
+
+  const loopPad = state.loopPads.get(playId);
+  if (loopPad) {
+    loopPad.x = x;
+    loopPad.z = z;
+    delete loopPad.placement;
+  }
+
+  ack(sessionId, "pad_move", { playId, x, z });
+}
+
 async function handleJoin(
   sessionId: string,
   demo: ShowcaseDemo,
@@ -657,11 +813,50 @@ async function dispatchMessage(
           state.orbit.elevation = message.elevation;
         }
         if (message.paused !== undefined) {
+          if (message.paused === false && state.orbitManualPose) {
+            syncOrbitClockFromManualPose(state);
+          }
           state.orbit.paused = message.paused;
         }
+        if (message.frequencyHz !== undefined) {
+          state.orbitSineFrequencyHz = message.frequencyHz;
+          if (state.orbitSineEnabled && state.orbitSinePlayId) {
+            void startOrbitSinePlay(sessionId, state);
+          }
+        }
+        if (message.sinePlaying !== undefined) {
+          state.orbitSineEnabled = message.sinePlaying;
+          if (message.sinePlaying) {
+            if (!state.orbitSinePlayId) {
+              void startOrbitSinePlay(sessionId, state);
+            }
+          } else {
+            void stopOrbitSine(state);
+          }
+        }
         ack(sessionId, "orbit_set");
         return;
       }
+      if (message.action === "place") {
+        state.orbit.paused = true;
+        state.orbitManualPose = { x: message.x, z: message.z };
+        const pose = orbitPoseFromXz(state, message.x, message.z);
+        if (state.orbitSinePlayId) {
+          void safeMixCall(sessionId, "setPlayPose", () =>
+            setPlayPose(state.orbitSinePlayId!, pose),
+          );
+        }
+        void safeMixCall(sessionId, "setTtsPose", () =>
+          setTtsPose(sessionId, pose),
+        );
+        emitOrbitPlacePose(sessionId, state, message.x, message.z);
+        ack(sessionId, "orbit_place");
+        return;
+      }
+      sendToClient(sessionId, {
+        type: "orbit_say_status",
+        status: "playing",
+      });
       speak(sessionId, message.text);
       ack(sessionId, "orbit_say");
       return;
@@ -718,6 +913,20 @@ async function dispatchMessage(
       }
       return;
     }
+    case "pad_move": {
+      if (state.demo !== "soundboard") {
+        ackError(sessionId, "pad_move", "wrong_demo");
+        return;
+      }
+      await handlePadMove(
+        sessionId,
+        state,
+        message.playId,
+        message.x,
+        message.z,
+      );
+      return;
+    }
     case "move": {
       if (state.demo !== "proximity") {
         ackError(sessionId, "move", "wrong_demo");
@@ -800,6 +1009,24 @@ defineAgent({
     void dispatchMessage(ctx.sessionId, message);
   },
 
+  onSpeechEvent(ctx, event) {
+    const state = sessions.get(ctx.sessionId);
+    if (!state || state.demo !== "orbit") {
+      return;
+    }
+    if (event.type === "agent_speaking_start") {
+      sendToClient(ctx.sessionId, {
+        type: "orbit_say_status",
+        status: "playing",
+      });
+    } else if (event.type === "agent_speaking_end") {
+      sendToClient(ctx.sessionId, {
+        type: "orbit_say_status",
+        status: "ended",
+      });
+    }
+  },
+
   onSessionEnd({ sessionId }) {
     teardownSession(sessionId);
     agentLog("info", `spatial-showcase session_end ${sessionId}`, sessionId);

package/templates/spatial-showcase/protocol.ts

@@ -8,6 +8,8 @@ const SHOWCASE_DEMOS = new Set<string>(["orbit", "soundboard", "proximity"]);
 
 export const MAX_SAY_TEXT_LENGTH = 200;
 export const MAX_XZ = 5;
+export const ORBIT_SINE_MIN_FREQUENCY_HZ = 110;
+export const ORBIT_SINE_MAX_FREQUENCY_HZ = 1760;
 
 export type ShowcaseJoinMessage = {
   type: "join";
@@ -22,6 +24,8 @@ export type ShowcaseOrbitSetMessage = {
   periodSec?: number;
   elevation?: number;
   paused?: boolean;
+  frequencyHz?: number;
+  sinePlaying?: boolean;
 };
 
 export type ShowcaseOrbitSayMessage = {
@@ -30,6 +34,13 @@ export type ShowcaseOrbitSayMessage = {
   text: string;
 };
 
+export type ShowcaseOrbitPlaceMessage = {
+  type: "orbit";
+  action: "place";
+  x: number;
+  z: number;
+};
+
 export type ShowcasePadMessage = {
   type: "pad";
   clipId: string;
@@ -49,6 +60,13 @@ export type ShowcasePadStatusMessage = {
   playId: string;
 };
 
+export type ShowcasePadMoveMessage = {
+  type: "pad_move";
+  playId: string;
+  x: number;
+  z: number;
+};
+
 export type ShowcaseMoveMessage = {
   type: "move";
   x: number;
@@ -74,9 +92,11 @@ export type ShowcaseInbound =
   | ShowcaseJoinMessage
   | ShowcaseOrbitSetMessage
   | ShowcaseOrbitSayMessage
+  | ShowcaseOrbitPlaceMessage
   | ShowcasePadMessage
   | ShowcasePadStopMessage
   | ShowcasePadStatusMessage
+  | ShowcasePadMoveMessage
   | ShowcaseMoveMessage
   | ShowcaseMutePeerMessage
   | ShowcaseLeaveMessage
@@ -98,6 +118,11 @@ export type ShowcaseOrbitPose = {
   z: number;
 };
 
+export type ShowcaseOrbitSayStatus = {
+  type: "orbit_say_status";
+  status: "playing" | "ended";
+};
+
 export type ShowcasePadProgress = {
   type: "pad_progress";
   playId: string;
@@ -127,6 +152,7 @@ export type ShowcaseError = {
 export type ShowcaseOutbound =
   | ShowcaseAck
   | ShowcaseOrbitPose
+  | ShowcaseOrbitSayStatus
   | ShowcasePadProgress
   | ShowcaseRoomState
   | ShowcaseRoomFull
@@ -144,6 +170,12 @@ function isInXzRange(value: number): boolean {
   return value >= -MAX_XZ && value <= MAX_XZ;
 }
 
+function isOrbitSineFrequencyHz(value: number): boolean {
+  return (
+    value >= ORBIT_SINE_MIN_FREQUENCY_HZ && value <= ORBIT_SINE_MAX_FREQUENCY_HZ
+  );
+}
+
 function isMixPlacement(value: unknown): value is MixPlacement {
   return (
     value === "center" ||
@@ -221,6 +253,19 @@ export function parseShowcaseMessage(message: unknown): ShowcaseInbound | null {
         if (set.paused !== undefined && typeof set.paused !== "boolean") {
           return null;
         }
+        if (
+          set.frequencyHz !== undefined &&
+          (!isFiniteNumber(set.frequencyHz) ||
+            !isOrbitSineFrequencyHz(set.frequencyHz))
+        ) {
+          return null;
+        }
+        if (
+          set.sinePlaying !== undefined &&
+          typeof set.sinePlaying !== "boolean"
+        ) {
+          return null;
+        }
         return {
           type: "orbit",
           action: "set",
@@ -228,8 +273,24 @@ export function parseShowcaseMessage(message: unknown): ShowcaseInbound | null {
           ...(set.periodSec !== undefined ? { periodSec: set.periodSec } : {}),
           ...(set.elevation !== undefined ? { elevation: set.elevation } : {}),
           ...(set.paused !== undefined ? { paused: set.paused } : {}),
+          ...(set.frequencyHz !== undefined
+            ? { frequencyHz: set.frequencyHz }
+            : {}),
+          ...(set.sinePlaying !== undefined
+            ? { sinePlaying: set.sinePlaying }
+            : {}),
         };
       }
+      if (orbit.action === "place") {
+        const place = message as ShowcaseOrbitPlaceMessage;
+        if (!isFiniteNumber(place.x) || !isInXzRange(place.x)) {
+          return null;
+        }
+        if (!isFiniteNumber(place.z) || !isInXzRange(place.z)) {
+          return null;
+        }
+        return { type: "orbit", action: "place", x: place.x, z: place.z };
+      }
       if (orbit.action === "say") {
         const say = message as ShowcaseOrbitSayMessage;
         if (
@@ -287,6 +348,24 @@ export function parseShowcaseMessage(message: unknown): ShowcaseInbound | null {
       }
       return { type: "pad_status", playId: status.playId.trim() };
     }
+    case "pad_move": {
+      const padMove = message as ShowcasePadMoveMessage;
+      if (!isNonEmptyString(padMove.playId)) {
+        return null;
+      }
+      if (!isFiniteNumber(padMove.x) || !isInXzRange(padMove.x)) {
+        return null;
+      }
+      if (!isFiniteNumber(padMove.z) || !isInXzRange(padMove.z)) {
+        return null;
+      }
+      return {
+        type: "pad_move",
+        playId: padMove.playId.trim(),
+        x: padMove.x,
+        z: padMove.z,
+      };
+    }
     case "move": {
       const move = message as ShowcaseMoveMessage;
       if (!isFiniteNumber(move.x) || !isInXzRange(move.x)) {

package/templates/spatial-showcase/sine.ts

@@ -1,22 +1,45 @@
 /** Inline orbit sine clip — 16 kHz mono s16le, decoded size under 64 KiB play cap. */
 
-/** 2 s keeps loop-restart gaps (250 ms poll) infrequent; 16 kHz mono still fits under 64 KiB. */
+/** 2 s keeps loop-restart gaps infrequent; 16 kHz mono still fits under 64 KiB. */
 export const ORBIT_SINE_DURATION_MS = 2000;
 export const ORBIT_SINE_FREQUENCY_HZ = 440;
 export const ORBIT_SINE_AMPLITUDE = 8000;
+export const ORBIT_SINE_SAMPLE_RATE = 16_000;
 export const ORBIT_SINE_INLINE_URL =
   "https://example.com/inline-orbit-sine.wav";
 
-/** Looping ~440 Hz sine WAV as base64 for {@link play} inline bytes. */
+/** Snap duration to an integer number of cycles so the clip loops at a zero crossing. */
+export function orbitSineSampleCount(
+  durationMs = ORBIT_SINE_DURATION_MS,
+  frequencyHz = ORBIT_SINE_FREQUENCY_HZ,
+  sampleRate = ORBIT_SINE_SAMPLE_RATE,
+): number {
+  const targetCycles = (durationMs / 1000) * frequencyHz;
+  const cycles = Math.max(1, Math.floor(targetCycles));
+  return Math.round((cycles * sampleRate) / frequencyHz);
+}
+
+/** Duration in ms for a clip built with {@link orbitSineSampleCount}. */
+export function orbitSineClipDurationMs(
+  durationMs = ORBIT_SINE_DURATION_MS,
+  frequencyHz = ORBIT_SINE_FREQUENCY_HZ,
+  sampleRate = ORBIT_SINE_SAMPLE_RATE,
+): number {
+  const numSamples = orbitSineSampleCount(durationMs, frequencyHz, sampleRate);
+  return (numSamples / sampleRate) * 1000;
+}
+
+/** Looping sine WAV as base64 for {@link play} inline bytes. */
 export function buildOrbitSineInlineClipBase64(
   durationMs = ORBIT_SINE_DURATION_MS,
   frequencyHz = ORBIT_SINE_FREQUENCY_HZ,
   amplitude = ORBIT_SINE_AMPLITUDE,
+  phaseRad = 0,
 ): string {
-  const sampleRate = 16_000;
+  const sampleRate = ORBIT_SINE_SAMPLE_RATE;
   const channels = 1;
   const bytesPerSample = 2;
-  const numSamples = Math.floor((sampleRate * durationMs) / 1000);
+  const numSamples = orbitSineSampleCount(durationMs, frequencyHz, sampleRate);
   const dataSize = numSamples * channels * bytesPerSample;
   const buffer = Buffer.alloc(44 + dataSize);
   buffer.write("RIFF", 0);
@@ -35,7 +58,7 @@ export function buildOrbitSineInlineClipBase64(
   for (let i = 0; i < numSamples; i++) {
     const t = i / sampleRate;
     const sample = Math.round(
-      amplitude * Math.sin(2 * Math.PI * frequencyHz * t),
+      amplitude * Math.sin(2 * Math.PI * frequencyHz * t + phaseRad),
     );
     buffer.writeInt16LE(sample, 44 + i * 2);
   }