@pheem49/mint 1.15.0 → 1.17.0

package/src/renderer/shared/platform.test.ts

@@ -1,8 +1,30 @@
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { authPlatform, installRendererPlatform, installWorkspacePlatform, workspacePlatform, type WorkspacePlatform } from './platform'
 import * as desktopAdapter from '../src/tauri'
 import * as webAdapter from '../src-web/tauri'
 
+afterEach(() => vi.unstubAllGlobals())
+
+describe.each([['Desktop fallback', desktopAdapter], ['Web', webAdapter]] as const)('%s skill inventory', (_name, adapter) => {
+  it('forwards the selected workspace and returns skill location metadata', async () => {
+    vi.stubGlobal('window', {
+      location: { hostname: 'localhost', port: '9000', protocol: 'http:' },
+      localStorage: { getItem: () => null },
+    })
+    let requestUrl: URL | undefined
+    const skills = [{ id: 0, name: 'example', sourcePath: '/selected project/skills/example.md',
+      content: 'selected workspace', updatedAt: '', createdAt: '', location: 'workspace',
+      description: null, is_workspace: true }]
+    vi.stubGlobal('fetch', async (input: string) => {
+      requestUrl = new URL(input, 'http://localhost:9000')
+      return new Response(JSON.stringify(skills), { headers: { 'Content-Type': 'application/json' } })
+    })
+    await expect(adapter.listLearnedSkills('/selected project')).resolves.toEqual(skills)
+    expect(requestUrl?.pathname).toBe('/api/learned-skills')
+    expect(requestUrl?.searchParams.get('workspacePath')).toBe('/selected project')
+  })
+})
+
 describe('renderer platform interfaces', () => {
   it('accepts both complete runtime adapters', () => {
     expect(() => installRendererPlatform(desktopAdapter)).not.toThrow()
@@ -26,9 +48,186 @@ describe('renderer platform interfaces', () => {
       getWorkspaceSnapshot: vi.fn(), getWorkspaceGitDiff: vi.fn(), getGitBranchInfo: vi.fn(), switchGitBranch: vi.fn(),
       createGitBranch: vi.fn(), checkoutRemoteGitBranch: vi.fn(), getGitGraph: vi.fn(),
       createWorkspaceFile, createWorkspaceFolder: vi.fn(), deleteWorkspaceItem: vi.fn(),
+      moveWorkspaceItem: vi.fn(), listWorkspaceHistory: vi.fn(), undoWorkspaceAction: vi.fn(),
     } satisfies WorkspacePlatform
     installWorkspacePlatform(adapter)
     await expect(workspacePlatform.createWorkspaceFile(operation)).resolves.toEqual(snapshot)
     expect(createWorkspaceFile).toHaveBeenCalledWith(operation)
   })
 })
+
+it('routes background terminal controls through both platform adapters', async () => {
+  const { backgroundPlatform } = await import('./platform')
+  for (const adapter of [desktopAdapter, webAdapter]) {
+    expect(adapter.listBackgroundJobs).toBeTypeOf('function')
+    expect(adapter.getBackgroundJob).toBeTypeOf('function')
+    expect(adapter.stopBackgroundJob).toBeTypeOf('function')
+  }
+  const job = { id: 'bg-backend-1', status: 'running' }
+  const listBackgroundJobs = vi.fn(async () => [job])
+  const getBackgroundJob = vi.fn(async () => ({ ...job, stdout: 'hello', stderr: '' }))
+  const stopBackgroundJob = vi.fn(async () => ({ ...job, status: 'stopping' }))
+  installRendererPlatform(new Proxy({ listBackgroundJobs, getBackgroundJob, stopBackgroundJob }, { get: (target, name) => target[name as keyof typeof target] || vi.fn() }) as any)
+  await expect(backgroundPlatform.list('/Demo')).resolves.toEqual([job])
+  await expect(backgroundPlatform.output(job.id)).resolves.toMatchObject({ stdout: 'hello' })
+  await expect(backgroundPlatform.stop(job.id)).resolves.toMatchObject({ status: 'stopping' })
+  expect(listBackgroundJobs).toHaveBeenCalledWith('/Demo')
+  expect(getBackgroundJob).toHaveBeenCalledWith(job.id)
+  expect(stopBackgroundJob).toHaveBeenCalledWith(job.id)
+})
+
+describe.each([['Desktop fallback', desktopAdapter], ['Web', webAdapter]] as const)('%s workspace mods', (_name, adapter) => {
+  it('forwards explicit workspace, chat, instance and action identity', async () => {
+    vi.stubGlobal('window', { location: { hostname: 'localhost', port: '9000', protocol: 'http:' }, localStorage: { getItem: () => null } })
+    let body: unknown
+    vi.stubGlobal('fetch', async (_url: unknown, init: RequestInit) => {
+      body = JSON.parse(String(init.body))
+      return new Response(JSON.stringify({ mods: [] }), { headers: { 'Content-Type': 'application/json' } })
+    })
+    await adapter.modsOperation({ workspacePath: '/project', chatId: 'chat-a', action: 'action', id: 'checklist', instanceId: 'revision-instance', command: 'add', value: 'Test' })
+    expect(body).toEqual({ workspacePath: '/project', chatId: 'chat-a', action: 'action', id: 'checklist', instanceId: 'revision-instance', command: 'add', value: 'Test' })
+  })
+})
+
+describe.each([['Desktop fallback', desktopAdapter], ['Web', webAdapter]] as const)('%s openExternal', (_name, adapter) => {
+  it('exports openExternal function and invokes window.open in browser fallback', async () => {
+    const openMock = vi.fn()
+    vi.stubGlobal('window', { open: openMock })
+    expect(adapter.openExternal).toBeTypeOf('function')
+    await adapter.openExternal('https://example.com/test')
+    expect(openMock).toHaveBeenCalledWith('https://example.com/test', '_blank', 'noopener,noreferrer')
+  })
+})
+
+describe('desktop external link interceptor', () => {
+  it('identifies external and internal URLs correctly', async () => {
+    const { isExternalHref } = await import('./utils/externalLinks')
+    expect(isExternalHref('https://example.com')).toBe(true)
+    expect(isExternalHref('http://example.com/page')).toBe(true)
+    expect(isExternalHref('//cdn.example.com/asset.js')).toBe(true)
+    expect(isExternalHref('#/settings')).toBe(false)
+    expect(isExternalHref('/library?item=123')).toBe(false)
+    expect(isExternalHref('./relative')).toBe(false)
+    expect(isExternalHref('../parent')).toBe(false)
+    expect(isExternalHref('javascript:void(0)')).toBe(false)
+    expect(isExternalHref('data:image/png;base64,...')).toBe(false)
+    expect(isExternalHref('blob:http://localhost/123')).toBe(false)
+  })
+
+  it('intercepts clicks on external http/https links and prevents default', async () => {
+    const openMock = vi.fn()
+    vi.stubGlobal('window', { open: openMock })
+
+    let clickHandler: ((e: any) => void) | null = null
+    const mockDocument: any = {
+      addEventListener: vi.fn((event: string, handler: any) => {
+        if (event === 'click') clickHandler = handler
+      }),
+      removeEventListener: vi.fn((event: string, handler: any) => {
+        if (event === 'click' && clickHandler === handler) clickHandler = null
+      }),
+    }
+
+    const cleanup = desktopAdapter.installExternalLinkInterceptor(mockDocument)
+    expect(mockDocument.addEventListener).toHaveBeenCalledWith('click', expect.any(Function), true)
+    expect(clickHandler).toBeTypeOf('function')
+
+    const externalAnchor: any = {
+      getAttribute: (attr: string) => (attr === 'href' ? 'https://example.com/search-result' : null),
+      hasAttribute: (attr: string) => false,
+      href: 'https://example.com/search-result',
+      target: '_blank',
+    }
+    const imgInsideAnchor: any = {
+      closest: (selector: string) => (selector === 'a' ? externalAnchor : null),
+    }
+
+    const clickEvent: any = {
+      defaultPrevented: false,
+      button: 0,
+      target: imgInsideAnchor,
+      preventDefault: vi.fn(() => { clickEvent.defaultPrevented = true }),
+      stopPropagation: vi.fn(),
+    }
+
+    clickHandler!(clickEvent)
+
+    expect(clickEvent.preventDefault).toHaveBeenCalledOnce()
+    // Does NOT suppress propagation so React/child event listeners can still run
+    expect(clickEvent.stopPropagation).not.toHaveBeenCalled()
+    expect(openMock).toHaveBeenCalledWith('https://example.com/search-result', '_blank', 'noopener,noreferrer')
+
+    // Internal relative route (/library?item=lib-123) should NOT be intercepted even if anchor.href resolves to document origin
+    openMock.mockClear()
+    const relativeAnchor: any = {
+      getAttribute: (attr: string) => (attr === 'href' ? '/library?item=lib-123' : null),
+      hasAttribute: (attr: string) => false,
+      href: 'http://localhost:9000/library?item=lib-123',
+      target: '',
+    }
+    const relativeClickEvent: any = {
+      defaultPrevented: false,
+      button: 0,
+      target: {
+        closest: (selector: string) => (selector === 'a' ? relativeAnchor : null),
+      },
+      preventDefault: vi.fn(),
+      stopPropagation: vi.fn(),
+    }
+
+    clickHandler!(relativeClickEvent)
+
+    expect(relativeClickEvent.preventDefault).not.toHaveBeenCalled()
+    expect(openMock).not.toHaveBeenCalled()
+
+    // Download link should not be intercepted
+    openMock.mockClear()
+    const downloadAnchor: any = {
+      getAttribute: (attr: string) => (attr === 'href' ? 'https://example.com/file.png' : null),
+      hasAttribute: (attr: string) => attr === 'download',
+      href: 'https://example.com/file.png',
+      target: '',
+    }
+    const downloadClickEvent: any = {
+      defaultPrevented: false,
+      button: 0,
+      target: {
+        closest: (selector: string) => (selector === 'a' ? downloadAnchor : null),
+      },
+      preventDefault: vi.fn(),
+      stopPropagation: vi.fn(),
+    }
+
+    clickHandler!(downloadClickEvent)
+
+    expect(downloadClickEvent.preventDefault).not.toHaveBeenCalled()
+    expect(openMock).not.toHaveBeenCalled()
+
+    // Internal hash link should not be intercepted
+    openMock.mockClear()
+    const internalAnchor: any = {
+      getAttribute: (attr: string) => (attr === 'href' ? '#/settings' : null),
+      hasAttribute: (attr: string) => false,
+      href: '#/settings',
+      target: '',
+    }
+    const internalClickEvent: any = {
+      defaultPrevented: false,
+      button: 0,
+      target: {
+        closest: (selector: string) => (selector === 'a' ? internalAnchor : null),
+      },
+      preventDefault: vi.fn(),
+      stopPropagation: vi.fn(),
+    }
+
+    clickHandler!(internalClickEvent)
+
+    expect(internalClickEvent.preventDefault).not.toHaveBeenCalled()
+    expect(internalClickEvent.stopPropagation).not.toHaveBeenCalled()
+    expect(openMock).not.toHaveBeenCalled()
+
+    cleanup()
+    expect(mockDocument.removeEventListener).toHaveBeenCalledWith('click', expect.any(Function), true)
+  })
+})

package/src/renderer/shared/platform.ts

@@ -51,6 +51,7 @@ export type SlashEffect =
   | { kind: 'config_changed' }
   | { kind: 'provider_changed'; display: string }
   | { kind: 'workspace_changed'; path: string }
+  | { kind: 'workspace_files_changed' }
   | { kind: 'history_cleared' }
   | { kind: 'fast_mode_changed'; enabled: boolean }
   | { kind: 'multi_agent_changed'; enabled: boolean }
@@ -66,8 +67,14 @@ export type SlashResponse =
   | { kind: 'not_handled' }
 
 export interface MintPlatformApi {
+  modsOperation(operation: import("./mods").ModOperation): Promise<import("./mods").ModResponse>
+  readMcpArtifact(id: string, chatId?: string): Promise<string>
+  listBackgroundJobs(workspace?: string): Promise<import("./types").BackgroundJob[]>
+  getBackgroundJob(id: string): Promise<import("./types").BackgroundJobOutput>
+  stopBackgroundJob(id: string): Promise<import("./types").BackgroundJob>
+  deleteBackgroundJob(id: string): Promise<void>
   authRegister(name: string | undefined, email: string, password: string): Promise<AuthUser>
-  runSlashCommand(input: string, cwd?: string | null): Promise<SlashResponse>
+  runSlashCommand(input: string, cwd?: string | null, chatId?: string | null): Promise<SlashResponse>
   authLogin(email: string, password: string): Promise<AuthUser>
   authLogout(): Promise<void>
   authGetCurrentUser(): Promise<AuthUser | null>
@@ -84,6 +91,8 @@ export interface MintPlatformApi {
     workspacePath?: string | null,
     chatId?: string | null,
     agentId?: string | null,
+    planMode?: boolean,
+    attachmentMetadata?: import('./types').AttachmentMetadata,
   ): Promise<ChatResponse>
   streamChatMessage(
     message: string,
@@ -101,11 +110,15 @@ export interface MintPlatformApi {
     pinnedMcpServer?: string | null,
     onApprovalRequested?: (payload: { token: string; approval: any }) => void,
     onTurnStarted?: (interactionId: number) => void,
+    attachmentMetadata?: import('./types').AttachmentMetadata,
   ): Promise<ChatResponse>
+  speechRequest(request: import('./speech/types').SpeechRequest): Promise<import('./speech/types').SpeechReply>
   getTtsUrls(text: string): Promise<TtsUrl[]>
   cancelChatMessage(chatId: string): Promise<void>
   getRecentInteractions(limit?: number, chatId?: string | null, workspacePath?: string | null): Promise<InteractionMemory[]>
   getConversationSnapshot(chatId: string, beforeId?: number | null, limit?: number): Promise<ConversationSnapshot>
+  getConversationSources(chatId: string): Promise<import('./types').ConversationSources>
+  saveSourceAttachments(chatId: string, interactionId: number, attachments: import('./types').SourceAttachment[]): Promise<void>
   getConversationChanges(chatId: string, after: number, limit?: number): Promise<ConversationChanges>
   saveSystemInteraction(
     chatId: string,
@@ -116,6 +129,7 @@ export interface MintPlatformApi {
   ): Promise<any>
 
   saveInteractionAgentActivity(interactionId: number, progress: any[]): Promise<void>
+  pendingCompanionChat(acknowledgedId?: string): Promise<string | null>
   listChatSessions(): Promise<ChatSession[]>
   updateChatSessionWorkspace(chatId: string, workspacePath: string | null): Promise<void>
   deleteChatSession(chatId: string): Promise<number>
@@ -129,6 +143,11 @@ export interface MintPlatformApi {
   saveSubagent(draft: SubagentDraft, workspacePath?: string): Promise<SubagentDefinition>
   deleteSubagent(sourcePath: string): Promise<void>
   clearChatHistory(chatId?: string | null): Promise<number>
+  listLibrary(query: import('./types').LibraryQuery): Promise<import('./types').LibraryPage>
+  getLibraryItem(id: string): Promise<import('./types').LibraryItem>
+  removeLibraryItem(id: string): Promise<void>
+  setLibraryTrashed(id: string, trashed: boolean): Promise<void>
+  readLibraryFile(id: string, thumbnail?: boolean): Promise<Blob>
   listSavedPictures(): Promise<PictureEntry[]>
   deleteSavedPicture(id: string): Promise<void>
   generateImages(req: ImageGenRequest): Promise<ImageGenResponse>
@@ -144,6 +163,10 @@ export interface MintPlatformApi {
   createWorkspaceFile(operation: WorkspaceOperation): Promise<import('./types').WorkspaceSnapshot>
   createWorkspaceFolder(operation: WorkspaceOperation): Promise<import('./types').WorkspaceSnapshot>
   deleteWorkspaceItem(operation: WorkspaceOperation): Promise<import('./types').WorkspaceSnapshot>
+  moveWorkspaceItem(operation: WorkspaceOperation, destination: string): Promise<import('./types').WorkspaceSnapshot>
+  startHtmlPreview(root: string, relativePath: string, mintBrowser?: boolean): Promise<{ url: string; jobId: string }>
+  listWorkspaceHistory(root: string): Promise<import('./types').WorkspaceHistoryEntry[]>
+  undoWorkspaceAction(root: string, revision: number, expectedId?: string): Promise<import('./types').WorkspaceSnapshot>
   selectWorkspaceDirectory(): Promise<string | null>
   selectLinkedFolderPath(): Promise<string | null>
   submitToolApproval(token: string, approved: boolean, answer?: string): Promise<void>
@@ -155,6 +178,9 @@ export interface MintPlatformApi {
   rollbackGitCheckpoint(chatId: string, step: number, workspacePath?: string): Promise<{ status: string; message: string }>
   undoGitCheckpoint(workspacePath?: string): Promise<{ status: string; message: string }>
   readWorkspaceFile(path: string, workspacePath?: string): Promise<string>
+  readWorkspaceImage(path: string, workspacePath: string): Promise<string>
+  readWorkspaceMedia(path: string, workspacePath: string): Promise<import('./types').WorkspaceMediaSource>
+  openExternal(url: string): Promise<any>
   testMcpConnection(
     url: string,
     headers?: Record<string, string>,
@@ -174,6 +200,10 @@ export type WorkspacePlatform = Pick<
   | 'createWorkspaceFile'
   | 'createWorkspaceFolder'
   | 'deleteWorkspaceItem'
+  | 'moveWorkspaceItem'
+  | 'startHtmlPreview'
+  | 'listWorkspaceHistory'
+  | 'undoWorkspaceAction'
 >
 
 let workspaceAdapter: WorkspacePlatform | undefined
@@ -238,14 +268,15 @@ export const authPlatform = {
 
 /** Conversation transport, persistence, live voice, and checkpoint seam. */
 export const conversationPlatform = {
+  getConversationSources: operation('getConversationSources'), saveSourceAttachments: operation('saveSourceAttachments'),
   clearChatHistory: operation('clearChatHistory'), deleteChatSession: operation('deleteChatSession'),
   renameChatSession: operation('renameChatSession'), getRecentInteractions: operation('getRecentInteractions'),
   getConversationSnapshot: operation('getConversationSnapshot'), getConversationChanges: operation('getConversationChanges'),
-  saveSystemInteraction: operation('saveSystemInteraction'), listChatSessions: operation('listChatSessions'),
+  saveSystemInteraction: operation('saveSystemInteraction'), listChatSessions: operation('listChatSessions'), pendingCompanionChat: operation('pendingCompanionChat'),
   updateChatSessionWorkspace: operation('updateChatSessionWorkspace'),
   saveInteractionAgentActivity: operation('saveInteractionAgentActivity'), streamChatMessage: operation('streamChatMessage'),
   cancelChatMessage: operation('cancelChatMessage'), submitToolApproval: operation('submitToolApproval'),
-  listen: operation('listen'), readClipboardImage: operation('readClipboardImage'), getTtsUrls: operation('getTtsUrls'),
+  listen: operation('listen'), readClipboardImage: operation('readClipboardImage'), getTtsUrls: operation('getTtsUrls'), speechRequest: operation('speechRequest'),
   startGeminiLiveSession: operation('startGeminiLiveSession'), sendGeminiLiveAudioChunk: operation('sendGeminiLiveAudioChunk'),
   stopGeminiLiveSession: operation('stopGeminiLiveSession'), listGitCheckpoints: operation('listGitCheckpoints'),
   rollbackGitCheckpoint: operation('rollbackGitCheckpoint'), undoGitCheckpoint: operation('undoGitCheckpoint'),
@@ -271,6 +302,7 @@ export const catalogPlatform = {
 
 /** Image and video generation and saved media seam. */
 export const mediaPlatform = {
+  readMcpArtifact: operation('readMcpArtifact'),
   generateImages: operation('generateImages'), getImageGenProviders: operation('getImageGenProviders'),
   fetchImageProviderModels: operation('fetchImageProviderModels'), listSavedPictures: operation('listSavedPictures'),
   generateVideo: operation('generateVideo'), getVideoGenProviders: operation('getVideoGenProviders'),
@@ -278,11 +310,19 @@ export const mediaPlatform = {
 }
 
 /** Runtime capabilities and native picker seam. */
+export const backgroundPlatform = {
+  list: operation("listBackgroundJobs"),
+  output: operation("getBackgroundJob"),
+  stop: operation("stopBackgroundJob"),
+  delete: operation("deleteBackgroundJob"),
+}
+
 export const runtimePlatform = {
   appIconPath: () => String(requireRendererPlatform().APP_ICON_PATH ?? './assets/icon.png'),
   getRuntimeStatus: operation('getRuntimeStatus'), setActiveModel: operation('setActiveModel'),
   selectWorkspaceDirectory: operation('selectWorkspaceDirectory'), selectLinkedFolderPath: operation('selectLinkedFolderPath'),
-  isTauriRuntime: operation('isTauriRuntime'), readWorkspaceFile: operation('readWorkspaceFile'),
+  isTauriRuntime: operation('isTauriRuntime'), readWorkspaceFile: operation('readWorkspaceFile'), readWorkspaceImage: operation('readWorkspaceImage'), readWorkspaceMedia: operation('readWorkspaceMedia'),
+  openExternal: operation('openExternal'),
 }
 
 /** Install the Desktop or Web adapter before rendering the application. */
@@ -309,4 +349,15 @@ export const workspacePlatform: WorkspacePlatform = {
   createWorkspaceFile: (...args) => requireWorkspacePlatform().createWorkspaceFile(...args),
   createWorkspaceFolder: (...args) => requireWorkspacePlatform().createWorkspaceFolder(...args),
   deleteWorkspaceItem: (...args) => requireWorkspacePlatform().deleteWorkspaceItem(...args),
+  moveWorkspaceItem: (...args) => requireWorkspacePlatform().moveWorkspaceItem(...args),
+  startHtmlPreview: (...args) => requireWorkspacePlatform().startHtmlPreview(...args),
+  listWorkspaceHistory: (...args) => requireWorkspacePlatform().listWorkspaceHistory(...args),
+  undoWorkspaceAction: (...args) => requireWorkspacePlatform().undoWorkspaceAction(...args),
+}
+
+export const modsPlatform = { operation: operation("modsOperation") }
+
+export const libraryPlatform: Pick<MintPlatformApi, 'listLibrary' | 'getLibraryItem' | 'setLibraryTrashed' | 'removeLibraryItem' | 'readLibraryFile'> = {
+ listLibrary: operation('listLibrary'), getLibraryItem: operation('getLibraryItem'),
+ removeLibraryItem: operation('removeLibraryItem'), setLibraryTrashed: operation('setLibraryTrashed'), readLibraryFile: operation('readLibraryFile'),
 }

package/src/renderer/shared/speech/player.ts

@@ -0,0 +1,160 @@
+import type { SpeechReply, SpeechTransport } from './types'
+
+type Prepared = Extract<SpeechReply, { kind: 'prepared' }>
+type Input = { chatId: string; turnId?: number; text?: string; automatic?: boolean; audioOnly?: boolean }
+export type SpeechState = 'idle' | 'preparing' | 'speaking'
+
+/** One cancellable playback run, shared by Desktop, Web and Companion. */
+export class SpeechPlayer {
+  private generation = 0
+  private owner: string | null = null
+  private context: AudioContext | null = null
+  private source: AudioBufferSourceNode | null = null
+  private gain: GainNode | null = null
+  private timer: ReturnType<typeof setInterval> | undefined
+  private frame = 0
+  private settle: (() => void) | null = null
+  private renewing = false
+  private localVolume = 1
+  private hostVolume = 1
+  private speaking = false
+  constructor(private transport: SpeechTransport, private changed: (state: SpeechState) => void, private failed: (message: string) => void, private samples?: (samples: Float32Array | null) => void) {}
+
+  unlock(): Promise<void> {
+    try {
+      this.context ??= new AudioContext()
+      const context = this.context
+      return new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('Use the Read button to allow audio playback.')), 1500)
+        context.resume().then(() => { clearTimeout(timer); resolve() }, error => { clearTimeout(timer); reject(error) })
+      })
+    }
+    catch (error) { return Promise.reject(error) }
+  }
+  volume(value: number) {
+    this.localVolume = Math.min(1, Math.max(0, value))
+    if (this.gain) this.gain.gain.value = this.localVolume * this.hostVolume
+  }
+  stop(): Promise<void> {
+    this.generation += 1
+    const owner = this.owner
+    this.owner = null
+    clearInterval(this.timer); this.timer = undefined
+    cancelAnimationFrame(this.frame)
+    const wasSpeaking = this.speaking; this.speaking = false
+    try { this.source?.stop() } catch {}
+    this.source?.disconnect(); this.source = null
+    this.gain?.disconnect(); this.gain = null
+    this.settle?.(); this.settle = null
+    if (wasSpeaking && typeof speechSynthesis !== 'undefined') speechSynthesis.cancel()
+    this.samples?.(null); this.changed('idle')
+    return owner ? this.transport({ operation: 'release', owner }).then(() => {}, () => {}) : Promise.resolve()
+  }
+  async dispose() { const context = this.context; this.context = null; await this.stop(); await context?.close() }
+  private async renew(owner: string): Promise<boolean> {
+    const reply = await this.transport({ operation: 'renew', owner })
+    return reply.kind === 'lease' && reply.active
+  }
+  async play(input: Input): Promise<void> {
+    const previous = this.stop()
+    const generation = this.generation
+    const owner = crypto.randomUUID()
+    this.owner = owner
+    this.changed('preparing')
+    // Resume synchronously from the Read/Enable button's user gesture.
+    const unlocked = this.unlock().then(() => null, error => error)
+    try {
+      await previous; const unlockError = await unlocked; if (unlockError) throw unlockError
+      if (generation !== this.generation) return
+      let prepared: SpeechReply | undefined
+      for (let attempt = 0; attempt < 40; attempt++) {
+        if (generation !== this.generation) return
+        try { prepared = await this.transport({ operation: 'prepare', owner, ...input }); break }
+        catch (error) {
+          if (!input.automatic || !/Another Mint surface/.test(String(error)) || attempt === 39) throw error
+          // Wait for the revoked player to acknowledge stopping; never overlap its final audio segment.
+          await new Promise(resolve => setTimeout(resolve, 300))
+        }
+      }
+      if (generation !== this.generation) return
+      if (!prepared || prepared.kind !== 'prepared') throw new Error('Mint returned no speech plan')
+      this.hostVolume = prepared.volume
+      this.timer = setInterval(() => {
+        if (this.renewing) return
+        this.renewing = true
+        this.renew(owner).then(active => { if (!active && this.owner === owner) void this.stop() })
+          .catch(() => { if (this.owner === owner) void this.stop() }).finally(() => { this.renewing = false })
+      }, 1000)
+      if (prepared.provider === 'native') {
+        if (input.audioOnly) throw new Error('This voice cannot stream audio to Companion')
+        await this.playNative(prepared, generation)
+      } else {
+        for (let index = 0; index < prepared.chunks && generation === this.generation; index++) {
+          const audio = await this.transport({ operation: 'audio', owner, index })
+          if (generation !== this.generation) return
+          if (audio.kind !== 'audio') throw new Error('Mint returned no speech audio')
+          const bytes = Uint8Array.from(atob(audio.data), character => character.charCodeAt(0))
+          const buffer = await this.context!.decodeAudioData(bytes.buffer)
+          if (generation !== this.generation) return
+          await this.playBuffer(buffer, prepared, owner, generation)
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      if (generation === this.generation && !(input.automatic && /already been read automatically|Another Mint surface|A newer message|Automatic replies are routed/.test(message))) this.failed(message)
+    } finally {
+      if (generation === this.generation) await this.stop()
+      // Covers cancellation racing with preparation on another socket/process.
+      else await this.transport({ operation: 'release', owner }).catch(() => {})
+    }
+  }
+  private async playBuffer(buffer: AudioBuffer, plan: Prepared, owner: string, generation: number) {
+    const context = this.context!
+    const gain = context.createGain(); this.gain = gain
+    gain.gain.value = plan.volume * this.localVolume
+    const analyser = context.createAnalyser(); analyser.fftSize = 256
+    gain.connect(analyser); analyser.connect(context.destination)
+    const samples = new Float32Array(analyser.fftSize)
+    let frame = 0
+    const sample = () => {
+      if (generation !== this.generation) return
+      analyser.getFloatTimeDomainData(samples); this.samples?.(samples)
+      frame = requestAnimationFrame(sample); this.frame = frame
+    }
+    this.changed('speaking'); this.speaking = true; sample()
+    try {
+      // Short independently leased segments cannot continue for minutes after a frozen tab loses ownership.
+      let offset = 0
+      while (offset < buffer.duration && generation === this.generation) {
+        if (!await this.renew(owner) || generation !== this.generation) return
+        const length = Math.min(4 * plan.speed, buffer.duration - offset)
+        await new Promise<void>(resolve => {
+          const source = context.createBufferSource(); this.source = source
+          source.buffer = buffer; source.playbackRate.value = plan.speed
+          source.connect(gain); this.settle = resolve
+          source.onended = () => { source.disconnect(); if (this.source === source) { this.source = null; this.settle = null } resolve() }
+          source.start(0, offset, length)
+        })
+        offset += length
+      }
+    } finally {
+      cancelAnimationFrame(frame); if (generation === this.generation) this.samples?.(null)
+      analyser.disconnect(); gain.disconnect(); if (this.gain === gain) this.gain = null
+    }
+  }
+  private async playNative(plan: Prepared, generation: number) {
+    if (typeof speechSynthesis === 'undefined') throw new Error('System speech is unavailable')
+    this.changed('speaking'); this.speaking = true
+    await new Promise<void>((resolve, reject) => {
+      const utterance = new SpeechSynthesisUtterance(plan.text)
+      utterance.lang = /[\u0e00-\u0e7f]/.test(plan.text) ? 'th-TH' : 'en-US'
+      utterance.volume = plan.volume * this.localVolume; utterance.rate = plan.speed; utterance.pitch = plan.pitch
+      const voice = speechSynthesis.getVoices().find(voice => voice.lang.toLowerCase().startsWith(utterance.lang.slice(0, 2)))
+      if (voice) utterance.voice = voice
+      this.settle = resolve
+      utterance.onend = () => { if (this.settle === resolve) this.settle = null; resolve() }
+      utterance.onerror = event => { if (this.settle === resolve) this.settle = null; if (generation !== this.generation) resolve(); else reject(new Error(event.error)) }
+      speechSynthesis.speak(utterance)
+    })
+  }
+}

package/src/renderer/shared/speech/types.ts

@@ -0,0 +1,11 @@
+export type SpeechRequest =
+  | { operation: 'prefer'; owner: string; chatId: string; enabled: boolean }
+  | { operation: 'prepare'; owner: string; chatId: string; turnId?: number; text?: string; automatic?: boolean; audioOnly?: boolean; routeOwner?: string }
+  | { operation: 'audio'; owner: string; index: number }
+  | { operation: 'renew' | 'release'; owner: string }
+export type SpeechReply =
+  | { kind: 'prepared'; text: string; provider: string; volume: number; speed: number; pitch: number; chunks: number }
+  | { kind: 'audio'; data: string }
+  | { kind: 'lease'; active: boolean }
+  | { kind: 'released' }
+export type SpeechTransport = (request: SpeechRequest) => Promise<SpeechReply>

package/src/renderer/shared/theme/themeManager.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { applyTheme } from './themeManager'
+
+describe('theme surface settings', () => {
+  let attributes: Map<string, string>
+  let properties: Map<string, string>
+
+  beforeEach(() => {
+    attributes = new Map()
+    properties = new Map()
+    // The Node test environment supplies only the DOM boundary used by applyTheme.
+    vi.stubGlobal('document', {
+      documentElement: {
+        setAttribute: (name: string, value: string) => attributes.set(name, value),
+        style: {
+          setProperty: (name: string, value: string) => properties.set(name, value),
+          removeProperty: (name: string) => properties.delete(name),
+        },
+      },
+      body: { style: {} },
+    })
+  })
+
+  afterEach(() => vi.unstubAllGlobals())
+
+  it.each([undefined, 'glass', 'opaque'])('uses opaque surfaces when blur is disabled and surfaceStyle is %s', (surfaceStyle) => {
+    applyTheme({ theme: 'dark', surfaceStyle, glassBlur: 'none' })
+    expect(attributes.get('data-surface')).toBe('opaque')
+    expect(properties.get('--glass-blur')).toBe('none')
+  })
+
+  it('preserves enabled glass surfaces and the selected blur', () => {
+    applyTheme({ theme: 'dark', surfaceStyle: 'glass', glassBlur: 'blur(24px)' })
+    expect(attributes.get('data-surface')).toBe('glass')
+    expect(properties.get('--glass-blur')).toBe('blur(24px)')
+  })
+
+  it('keeps explicit opaque surfaces solid despite a saved blur value', () => {
+    applyTheme({ theme: 'light', surfaceStyle: 'opaque', glassBlur: 'blur(16px)' })
+    expect(attributes.get('data-surface')).toBe('opaque')
+    expect(properties.get('--glass-blur')).toBe('none')
+  })
+
+  it('sets data-accent-mode to monochrome for pure white accent', () => {
+    applyTheme({ theme: 'dark', accentColor: '#ffffff' })
+    expect(attributes.get('data-accent-mode')).toBe('monochrome')
+  })
+
+  it('sets data-accent-mode to gray for neutral gray accents', () => {
+    applyTheme({ theme: 'dark', accentColor: '#52525b' })
+    expect(attributes.get('data-accent-mode')).toBe('gray')
+  })
+
+  it('sets data-accent-mode to color for standard color accents', () => {
+    applyTheme({ theme: 'dark', accentColor: '#10b981' })
+    expect(attributes.get('data-accent-mode')).toBe('color')
+  })
+
+  it('correctly sets data-theme to studio when studio theme is selected', () => {
+    applyTheme({ theme: 'studio' })
+    expect(attributes.get('data-theme')).toBe('studio')
+  })
+})