create-spatius-app 0.1.0-beta.0

package/templates/cloudflare-livekit/tests/e2e/fake-components.tsx

@@ -0,0 +1,173 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import type {
+  ReceivedMessage,
+  UseSessionReturn,
+} from '@livekit/components-react';
+import { Room, ConnectionState } from './fake-livekit.js';
+
+function useUpdates() {
+  const [revision, setRevision] = useState(0);
+  useEffect(() => {
+    const update = () => setRevision((value) => value + 1);
+    window.addEventListener('fixture:update', update);
+    return () => window.removeEventListener('fixture:update', update);
+  }, []);
+  return revision;
+}
+type FixtureSession = {
+  room: Room;
+  start: () => Promise<void>;
+  end: () => Promise<void>;
+  isConnected: boolean;
+  connectionState: string;
+};
+const Context = createContext<FixtureSession | null>(null);
+export function useSession(
+  tokenSource: { fetch: () => Promise<unknown> },
+  options: { room: Room },
+) {
+  useUpdates();
+  const { room } = options;
+  useEffect(() => {
+    void tokenSource.fetch();
+  }, [tokenSource]);
+  const actions = useMemo(
+    () => ({
+      start: async () => {
+        await tokenSource.fetch();
+        await room.connect();
+      },
+      end: async () => {
+        await tokenSource.fetch();
+        await room.disconnect();
+      },
+    }),
+    [room, tokenSource],
+  );
+  return {
+    ...actions,
+    room,
+    connectionState: room.state,
+    isConnected: room.state === ConnectionState.Connected,
+  } as unknown as UseSessionReturn;
+}
+export function SessionProvider({
+  session,
+  children,
+}: {
+  session: FixtureSession;
+  children: ReactNode;
+}) {
+  return <Context value={session}>{children}</Context>;
+}
+export function useSessionContext() {
+  const session = useContext(Context);
+  if (!session) throw new Error('missing context');
+  return session;
+}
+export function RoomAudioRenderer() {
+  return <audio data-testid="remote-audio-renderer" />;
+}
+export function useAgent() {
+  const session = useSessionContext();
+  return {
+    name: 'Test agent',
+    internal: { agentParticipant: null, workerParticipant: null },
+    state:
+      session.connectionState === ConnectionState.Reconnecting
+        ? 'disconnected'
+        : session.isConnected
+          ? window.__fixture.pendingAgent
+            ? 'initializing'
+            : 'listening'
+          : 'connecting',
+  };
+}
+export function useLocalParticipant({ room }: { room: Room }) {
+  useUpdates();
+  return {
+    isMicrophoneEnabled: room.localParticipant.isMicrophoneEnabled,
+    microphoneTrack: undefined,
+  };
+}
+export function useMultibandTrackVolume() {
+  useUpdates();
+  const session = useSessionContext();
+  return session.room.localParticipant.isMicrophoneEnabled
+    ? [0.2, 0.6, 0.9, 0.5, 0.3]
+    : [0, 0, 0, 0, 0];
+}
+export function useMediaDeviceSelect({ room }: { room: Room }) {
+  useUpdates();
+  return {
+    devices: [
+      { deviceId: 'default', label: 'Default microphone' },
+      { deviceId: 'headset', label: 'Headset microphone' },
+    ],
+    activeDeviceId: room.activeDeviceId,
+    setActiveMediaDevice: async (id: string) => {
+      room.activeDeviceId = id;
+      window.__fixture.events.push(`device:${id}`);
+      room.update();
+      await Promise.resolve();
+    },
+  };
+}
+export function useStartAudio({ room }: { room: Room }) {
+  useUpdates();
+  return {
+    mergedProps: {
+      style: { display: room.audioUnlocked ? 'none' : 'inline-flex' },
+      onClick: () => {
+        window.__fixture.blockedAudio = false;
+        void room.startAudio();
+      },
+    },
+  };
+}
+export function useSessionMessages() {
+  useUpdates();
+  const session = useSessionContext();
+  const [sending, setSending] = useState(false);
+  const messages = useMemo(
+    () =>
+      window.__fixture.messages.map(({ isUser, ...message }) => ({
+        ...message,
+        type: isUser ? 'userTranscript' : 'agentTranscript',
+        from: isUser ? session.room.localParticipant : undefined,
+      })) as ReceivedMessage[],
+    [window.__fixture.messages, session.room],
+  );
+  return {
+    messages,
+    isSending: sending,
+    send: async (message: string) => {
+      setSending(true);
+      try {
+        if (window.__fixture.failSend) throw new Error('send failed');
+        const id = String(window.__fixture.messages.length);
+        window.__fixture.messages = [
+          ...window.__fixture.messages,
+          { id: `user-${id}`, timestamp: Date.now(), message, isUser: true },
+          {
+            id: `agent-${id}`,
+            timestamp: Date.now(),
+            message: 'I hear you.',
+            isUser: false,
+          },
+        ];
+        window.dispatchEvent(new Event('fixture:update'));
+        await Promise.resolve();
+      } finally {
+        setSending(false);
+      }
+    },
+  };
+}

package/templates/cloudflare-livekit/tests/e2e/fake-livekit.ts

@@ -0,0 +1,123 @@
+import type { TranscriptMessage } from '../../web/components/agents-ui/agent-chat-transcript.js';
+
+declare global {
+  interface Window {
+    __fixture: {
+      events: string[];
+      failMicrophone: boolean;
+      failSend: boolean;
+      stallConnect: boolean;
+      pendingAgent: boolean;
+      blockedAudio: boolean;
+      messages: TranscriptMessage[];
+    };
+  }
+}
+window.__fixture = {
+  events: [],
+  failMicrophone: false,
+  failSend: false,
+  stallConnect: false,
+  pendingAgent: false,
+  blockedAudio: false,
+  messages: [],
+};
+export const ConnectionState = {
+  Disconnected: 'disconnected',
+  Connected: 'connected',
+  Reconnecting: 'reconnecting',
+  SignalReconnecting: 'signalReconnecting',
+  Connecting: 'connecting',
+} as const;
+export const RoomEvent = { Disconnected: 'disconnected' } as const;
+export const Track = { Source: { Microphone: 'microphone' } } as const;
+export class Room {
+  private listeners = new Map<string, Set<() => void>>();
+  state: string = ConnectionState.Disconnected;
+  audioUnlocked = false;
+  activeDeviceId = 'default';
+  localParticipant = {
+    identity: 'local',
+    isLocal: true,
+    isMicrophoneEnabled: false,
+    getTrackPublication: () => ({
+      track: {
+        stop: () => {
+          this.localParticipant.isMicrophoneEnabled = false;
+        },
+      },
+    }),
+    setMicrophoneEnabled: async (enabled: boolean) => {
+      window.__fixture.events.push(`microphone:${enabled}`);
+      if (enabled && window.__fixture.failMicrophone)
+        throw new DOMException('denied', 'NotAllowedError');
+      this.localParticipant.isMicrophoneEnabled = enabled;
+      this.update();
+      await Promise.resolve();
+      return {
+        track: {
+          stop: () => {
+            this.localParticipant.isMicrophoneEnabled = false;
+            window.__fixture.events.push('track:stop');
+            this.update();
+          },
+        },
+      };
+    },
+  };
+  constructor(options: { singlePeerConnection: boolean }) {
+    window.__fixture.events.push(`room:${options.singlePeerConnection}`);
+    window.addEventListener('fixture:disconnect', () => {
+      void this.disconnect();
+    });
+    window.addEventListener('fixture:reconnecting', () => {
+      this.state = ConnectionState.Reconnecting;
+      this.update();
+    });
+    window.addEventListener('fixture:reconnected', () => {
+      this.state = ConnectionState.Connected;
+      this.update();
+    });
+  }
+  update() {
+    window.dispatchEvent(new Event('fixture:update'));
+  }
+  on(event: string, callback: () => void) {
+    const listeners = this.listeners.get(event) ?? new Set();
+    listeners.add(callback);
+    this.listeners.set(event, listeners);
+    return this;
+  }
+  off(event: string, callback: () => void) {
+    this.listeners.get(event)?.delete(callback);
+    return this;
+  }
+  prepareConnection() {
+    window.__fixture.events.push('prepare-connection');
+    return Promise.resolve();
+  }
+  async connect() {
+    window.__fixture.events.push('room:connect');
+    if (window.__fixture.stallConnect) await new Promise<void>(() => undefined);
+    this.state = ConnectionState.Connected;
+    this.update();
+  }
+  async disconnect() {
+    window.__fixture.events.push('room:disconnect');
+    this.localParticipant.isMicrophoneEnabled = false;
+    this.state = ConnectionState.Disconnected;
+    this.listeners.get('disconnected')?.forEach((callback) => callback());
+    this.update();
+    await Promise.resolve();
+  }
+  async startAudio() {
+    if (!window.__fixture.blockedAudio) this.audioUnlocked = true;
+    this.update();
+    await Promise.resolve();
+  }
+}
+export const TokenSource = {
+  literal: (credentials: { serverUrl: string; participantToken: string }) => ({
+    fetch: () => Promise.resolve(credentials),
+  }),
+};

package/templates/cloudflare-livekit/tests/e2e/harness.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Avatar conversation fixture</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/tests/e2e/harness.tsx"></script>
+  </body>
+</html>

package/templates/cloudflare-livekit/tests/e2e/harness.tsx

@@ -0,0 +1 @@
+import '../../web/main.js';

package/templates/cloudflare-livekit/tests/e2e/vite.config.ts

@@ -0,0 +1,48 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+// This configuration is used only by Playwright. Production has no fixture mode.
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+    {
+      name: 'test-only-avatar',
+      enforce: 'pre',
+      configureServer(server) {
+        server.middlewares.use('/api/session', (request, response, next) => {
+          if (request.method !== 'POST') return next();
+          response.setHeader('Content-Type', 'application/json');
+          response.end(
+            JSON.stringify({
+              server_url: 'wss://example.invalid',
+              participant_token: 'fixture-token',
+              room_name: 'fixture-room',
+              spatius_app_id: 'fixture-app',
+              spatius_avatar_id: 'fixture-avatar',
+            }),
+          );
+        });
+      },
+      resolveId(source, importer) {
+        if (
+          source === './avatar-session.js' &&
+          importer?.endsWith('/web/session-attempt.ts')
+        )
+          return resolve(import.meta.dirname, 'fake-avatar.ts');
+      },
+    },
+  ],
+  resolve: {
+    alias: {
+      '@': resolve(import.meta.dirname, '../../web'),
+      'livekit-client': resolve(import.meta.dirname, 'fake-livekit.ts'),
+      '@livekit/components-react': resolve(
+        import.meta.dirname,
+        'fake-components.tsx',
+      ),
+    },
+  },
+});

package/templates/cloudflare-livekit/tests/web/api.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { requestVoiceSession } from '../../web/api.js';
+afterEach(() => vi.unstubAllGlobals());
+describe('session bootstrap', () => {
+  it.each([
+    'https://cdn.example.com/room.jpg',
+    'javascript:alert(1)',
+    'https://user:password@example.com/image',
+    42,
+    null,
+  ])(
+    'accepts only safe optional public backgrounds: %s',
+    async (background) => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue(
+          Response.json({
+            server_url: 'wss://example.invalid',
+            participant_token: 'token',
+            room_name: 'room',
+            spatius_app_id: 'app',
+            spatius_avatar_id: 'avatar',
+            spatius_avatar_background_url: background,
+          }),
+        ),
+      );
+      const result = await requestVoiceSession();
+      expect(result.spatius_avatar_background_url).toBe(
+        background === 'https://cdn.example.com/room.jpg'
+          ? background
+          : undefined,
+      );
+    },
+  );
+
+  it('POSTs with cancellation and no cache, validating the response', async () => {
+    const payload = {
+      server_url: 'wss://example.invalid',
+      participant_token: 'token',
+      room_name: 'room',
+      spatius_app_id: 'app',
+      spatius_avatar_id: 'avatar',
+    };
+    const fetch = vi.fn().mockResolvedValue(Response.json(payload));
+    vi.stubGlobal('fetch', fetch);
+    const signal = new AbortController().signal;
+    expect(await requestVoiceSession(signal)).toEqual(payload);
+    expect(fetch).toHaveBeenCalledExactlyOnceWith(
+      '/api/session',
+      expect.objectContaining({ method: 'POST', cache: 'no-store', signal }),
+    );
+  });
+  it('rejects malformed success and non-JSON failures', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi
+        .fn()
+        .mockResolvedValueOnce(Response.json({}))
+        .mockResolvedValueOnce(new Response('offline', { status: 503 })),
+    );
+    await expect(requestVoiceSession()).rejects.toThrow('invalid response');
+    await expect(requestVoiceSession()).rejects.toThrow('Could not start');
+  });
+});

package/templates/cloudflare-livekit/tests/web/app.test.tsx

@@ -0,0 +1,125 @@
+// @vitest-environment jsdom
+import { StrictMode } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/react';
+const mocks = vi.hoisted(() => ({ create: vi.fn() }));
+vi.mock('../../web/session-attempt.js', () => ({
+  SessionAttempt: class {
+    constructor() {
+      return mocks.create() as object;
+    }
+  },
+}));
+vi.mock('../../web/components/conversation.js', () => ({
+  Conversation: () => <p>Live test conversation</p>,
+}));
+import App from '../../web/App.js';
+function createAttempt() {
+  let resolve!: (value: object) => void;
+  let reject!: (error: Error) => void;
+  let progress!: (status: string) => void;
+  const abort = new AbortController();
+  return {
+    stage: 'bootstrap',
+    abort,
+    room: { startAudio: vi.fn().mockResolvedValue(undefined) },
+    prepare: vi.fn(
+      (_container: HTMLElement, report: (status: string) => void) => {
+        progress = report;
+        return new Promise<object>((done, fail) => {
+          resolve = done;
+          reject = fail;
+        });
+      },
+    ),
+    dispose: vi.fn(() => {
+      abort.abort();
+      return Promise.resolve();
+    }),
+    resolve: (value: object) => resolve(value),
+    reject: (error: Error) => reject(error),
+    progress: (status: string) => progress(status),
+  };
+}
+beforeEach(() => {
+  mocks.create.mockImplementation(createAttempt);
+  vi.stubGlobal('matchMedia', () => ({
+    matches: false,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  }));
+});
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+  vi.unstubAllGlobals();
+});
+describe('explicit app lifecycle', () => {
+  it('StrictMode mount does not create a room, fetch credentials or request microphone', () => {
+    render(
+      <StrictMode>
+        <App />
+      </StrictMode>,
+    );
+    expect(mocks.create).not.toHaveBeenCalled();
+  });
+  it('synchronously rejects double Start and ignores a stale progress/completion after cancel', async () => {
+    const attempt = createAttempt();
+    mocks.create.mockReturnValueOnce(attempt);
+    render(
+      <StrictMode>
+        <App />
+      </StrictMode>,
+    );
+    const start = screen.getByRole('button', { name: 'Start conversation' });
+    fireEvent.click(start);
+    fireEvent.click(start);
+    expect(mocks.create).toHaveBeenCalledOnce();
+    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
+    await act(async () => {
+      await Promise.resolve();
+      attempt.progress('STALE UPDATE');
+      attempt.resolve({ attempt, tokenSource: {} });
+      await Promise.resolve();
+    });
+    expect(screen.queryByText('STALE UPDATE')).toBeNull();
+    expect(screen.queryByText('Live test conversation')).toBeNull();
+    expect(
+      screen.getByRole('button', { name: 'Start conversation' }),
+    ).toBeTruthy();
+    expect(attempt.abort.signal.aborted).toBe(true);
+  });
+  it('disposes on unmount and never renders a late bootstrap result', async () => {
+    const attempt = createAttempt();
+    mocks.create.mockReturnValueOnce(attempt);
+    const { unmount } = render(<App />);
+    fireEvent.click(screen.getByRole('button', { name: 'Start conversation' }));
+    unmount();
+    await act(async () => {
+      attempt.resolve({ attempt, tokenSource: {} });
+      await Promise.resolve();
+    });
+    expect(attempt.dispose).toHaveBeenCalled();
+    expect(attempt.abort.signal.aborted).toBe(true);
+  });
+  it('uses actionable bootstrap guidance without exposing raw error payloads', async () => {
+    const attempt = createAttempt();
+    mocks.create.mockReturnValueOnce(attempt);
+    render(<App />);
+    fireEvent.click(screen.getByRole('button', { name: 'Start conversation' }));
+    await act(async () => {
+      attempt.reject(new Error('secret-token=not-for-ui'));
+      await Promise.resolve();
+    });
+    expect(screen.getByRole('alert').textContent).toContain(
+      'Worker credentials',
+    );
+    expect(document.body.textContent).not.toContain('secret-token');
+  });
+});

package/templates/cloudflare-livekit/tests/web/audio-visualizer.test.tsx

@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import type { LocalAudioTrack } from 'livekit-client';
+import { useMultibandTrackVolume } from '@livekit/components-react';
+import { AgentAudioVisualizerBar } from '../../web/components/agents-ui/agent-audio-visualizer-bar.js';
+
+vi.mock('@livekit/components-react', () => ({
+  useMultibandTrackVolume: vi.fn(),
+}));
+afterEach(() => {
+  cleanup();
+  vi.resetAllMocks();
+});
+
+it('uses the local track and reacts to real bands, silence, mute and replacement tracks', () => {
+  const track = {} as LocalAudioTrack;
+  const volume = vi.mocked(useMultibandTrackVolume);
+  volume.mockReturnValue([0, 0.25, 0.5, 0.75, 1]);
+  const { container, rerender } = render(
+    <AgentAudioVisualizerBar audioTrack={track} enabled />,
+  );
+  const heights = () =>
+    [...container.querySelectorAll<HTMLElement>('.audio-bars span')].map(
+      (bar) => bar.style.height,
+    );
+  expect(
+    screen.getByRole('group', { name: 'Your microphone activity' }),
+  ).toBeTruthy();
+  expect(volume).toHaveBeenLastCalledWith(track, {
+    bands: 5,
+    loPass: 100,
+    hiPass: 200,
+  });
+  expect(heights()).toEqual(['4px', '6px', '12px', '18px', '24px']);
+  volume.mockReturnValue([0, 0, 0, 0, 0]);
+  rerender(<AgentAudioVisualizerBar audioTrack={track} enabled />);
+  expect(heights()).toEqual(Array(5).fill('4px'));
+  volume.mockReturnValue([1, 1, 1, 1, 1]);
+  rerender(<AgentAudioVisualizerBar audioTrack={track} enabled={false} />);
+  expect(volume).toHaveBeenLastCalledWith(undefined, expect.anything());
+  expect(heights()).toEqual(Array(5).fill('4px'));
+  expect(screen.getByText('Microphone off')).toBeTruthy();
+  const replacement = {} as LocalAudioTrack;
+  rerender(<AgentAudioVisualizerBar audioTrack={replacement} enabled />);
+  expect(volume).toHaveBeenLastCalledWith(replacement, expect.anything());
+});
+
+it('renders five silent bars without a published microphone', () => {
+  vi.mocked(useMultibandTrackVolume).mockReturnValue([]);
+  const { container } = render(<AgentAudioVisualizerBar enabled={false} />);
+  expect(container.querySelectorAll('.audio-bars span')).toHaveLength(5);
+});