Add a Dashboard Polyfill

Adds a browser API polyfill that is automatically injected into all dashboard iframes. The polyfill runs inside the iframe's JS context and provides APIs that are unavailable or broken in Electron's Chromium (e.g. SpeechRecognition, which requires Google's cloud service).

Architecture

Dashboard HTML (from container)
        │
        ▼
proxyArtifactRequest() intercepts text/html responses
        │
        ▼
Injects <script>polyfill code</script> after <head>
        │
        ▼
Browser renders HTML with polyfill already defined
        │
        ▼
Dashboard JS uses the standard API (e.g. new SpeechRecognition())

The polyfill is inlined into the HTML response (not loaded via a separate <script src>). This avoids routing/auth issues and guarantees the polyfill is available before any dashboard code runs.

Important considerations

Iframe permissions

If the polyfill needs browser-gated capabilities (microphone, camera, geolocation, etc.), two layers must grant access:

1. Iframe allow attribute — The iframe in src/renderer/components/dashboards/dashboard-view.tsx and the standalone /view route in src/api/routes/agents.ts both set allow="...". Add your permission here (e.g. allow="microphone; camera; geolocation").

2. Electron permission handler — In src/main/index.ts, setPermissionRequestHandler and setPermissionCheckHandler whitelist specific permission strings. If your polyfill needs a permission not already listed, add it to the allowed array there.

Without BOTH, the browser silently denies the permission before your polyfill code ever runs.

Chromium broken stubs

Chromium (and therefore Electron) often defines Web API constructors that don't actually work — they exist on window but throw or fail at runtime because the backing service isn't available. Examples:

• webkitSpeechRecognition — defined but requires Google's cloud service (network error)
• Payment Request API — defined but may lack a payment handler

Never guard with if (window.SomeAPI) return; — always override. The polyfill is only injected into Superagent dashboard iframes, so overriding is safe and expected.

Size budget

Every polyfill is inlined into every HTML response from the artifact proxy. Keep polyfills compact:

• Target under 10KB per polyfill (the SpeechRecognition polyfill is ~6KB)
• No comments in the JS string (they're stripped by not including them)
• Use var declarations and terse patterns in the JS — it's not going through a minifier
• The getPolyfillJs() caching ensures the string is only built once per process lifetime

If a polyfill grows beyond ~15KB, consider splitting it: inline a minimal shim that lazy-loads the full implementation from a standalone route on first use.

Files to create/modify

1. Polyfill implementation: src/api/<name>-polyfill.ts

Export a getPolyfillJs(): string function that returns self-contained vanilla JS as a string. The JS must:

• Be an IIFE: (function() { "use strict"; ... })()
• Use class extends EventTarget (not prototype-based inheritance — DOM constructors require new)
• Always override native stubs (Chromium often defines broken constructors)
• Register on window (e.g. window.SpeechRecognition = ...)
• Use absolute paths for fetch calls to the Superagent API (e.g. fetch("/api/voice/token")) since the iframe serves from a subpath — add a comment explaining this

Cache the string to avoid re-generating on every request:

let cached: string | null = null
export function getPolyfillJs(): string {
  if (cached) return cached
  cached = POLYFILL_SOURCE
  return cached
}
const POLYFILL_SOURCE = `(function() { ... })();`

2. Injection: src/api/routes/agents.ts — proxyArtifactRequest()

Import the polyfill getter and add it to the HTML injection block. All polyfills are injected together:

import { getPolyfillJs } from '../speech-recognition-polyfill'
import { getNewPolyfillJs } from '../new-polyfill'  // your new one

// Inside proxyArtifactRequest(), in the text/html branch:
const tag = `<script>${getPolyfillJs()}${getNewPolyfillJs()}</script>`

The injection logic (already exists — you just add your polyfill string to the tag):

const contentType = response.headers.get('content-type') || ''
if (contentType.includes('text/html')) {
  let html = await response.text()
  const tag = `<script>${getPolyfillJs()}${getNewPolyfillJs()}</script>`
  const headMatch = html.match(/<head(\s[^>]*)?>/i)
  if (headMatch) {
    const pos = headMatch.index! + headMatch[0].length
    html = html.slice(0, pos) + tag + html.slice(pos)
  } else {
    html = tag + html
  }
  const headers = new Headers(response.headers)
  headers.delete('content-length')
  return new Response(html, { status: response.status, headers })
}

3. Optional: standalone route in src/api/index.ts

If the polyfill should also be loadable as a standalone script (useful for debugging or manual inclusion):

import { getNewPolyfillJs } from './new-polyfill'

app.get('/api/<path>/polyfill.js', (c) => {
  return c.body(getNewPolyfillJs(), 200, {
    'Content-Type': 'application/javascript; charset=utf-8',
    'Cache-Control': 'public, max-age=3600',
  })
})

Register this BEFORE the router mounts (to avoid auth middleware).

4. Documentation for the dashboard builder agent

Three places to update:

a. Full reference doc — agent-container/plugin/skills/dashboards/<API_NAME>.md

Include: quick start, properties, methods, events, error codes, 2-3 practical examples. Call out that it's a web standard (if applicable) so agents can search for more examples online. This file reaches containers through the Gamut plugin (agent-container/plugin/, baked into /opt/gamut/plugin by the Dockerfile).

b. Skill file — agent-container/plugin/skills/dashboards/SKILL.md

Add a bullet under the "Built-in APIs" section:

- **<API Name>** — Brief description. See `/opt/gamut/plugin/skills/dashboards/<API_NAME>.md` for docs.

c. Dashboard builder prompt — agent-container/src/dashboard-builder-agent-prompt.md

Add an entry under the "Built-in APIs" section with a concise code example (5-10 lines) and key properties/events. This is what the agent sees in its system prompt.

Testing

Unit tests: src/api/<name>-polyfill.test.ts

Use // @vitest-environment jsdom pragma. Key patterns:

// Evaluate the polyfill in jsdom's global scope
function installPolyfill() {
  const run = eval
  run(getPolyfillJs())
}

// Mock WebSocket as a class (not vi.fn — needs to work with `new`)
class MockWebSocket { ... }
;(window as any).WebSocket = MockWebSocket

// Mock AudioContext as a function constructor (vi.fn can't be used with `new`)
;(window as any).AudioContext = function() { return mockCtx } as any

// Mock navigator.mediaDevices (jsdom doesn't have it)
;(navigator as any).mediaDevices.getUserMedia = vi.fn().mockResolvedValue(mockStream)

Test coverage should include:

• Global registration (polyfill sets window.X)
• Overrides native broken stubs
• Constructor creates instance with correct defaults
• Instance is an EventTarget
• on* property handlers work
• Happy path flow (token fetch → connect → active state)
• Error paths (permission denied, network errors, service not configured)
• Mode variations (continuous vs one-shot, interim results on/off)
• Result accumulation and event format

Injection test: src/api/routes/artifact-polyfill-injection.test.ts

Replicate the injection logic and test HTML parsing edge cases:

• Injects after <head>
• Handles <head> with attributes
• Case-insensitive matching
• Fallback when no <head> tag
• Content-type check logic

E2E test: e2e/specs/<name>-polyfill.spec.ts

The E2E test validates the full pipeline (proxy → injection → browser execution):

import { test, expect } from '@playwright/test'

test.describe('...', () => {
  let agentSlug: string

  test.beforeEach(async ({ page }) => {
    // Create agent via API (reliable slug extraction)
    const resp = await page.request.post('/api/agents', {
      data: { name: `polyfill-e2e-${Date.now()}` },
    })
    const agent = await resp.json() as { slug: string }
    agentSlug = agent.slug

    // Start the container (so the artifact proxy serves HTML)
    await page.request.post(`/api/agents/${agentSlug}/start`)
  })

  test('polyfill is injected', async ({ page, baseURL }) => {
    const resp = await page.request.get(`${baseURL}/api/agents/${agentSlug}/artifacts/test-dashboard/`)
    const html = await resp.text()
    expect(resp.headers()['content-type']).toContain('text/html')
    expect(html).toContain('YourPolyfillClassName')
  })

  test('polyfill works in browser context', async ({ page, baseURL }) => {
    await page.goto(`${baseURL}/api/agents/${agentSlug}/artifacts/test-dashboard/`)
    const check = await page.evaluate(() => typeof (window as any).YourAPI === 'function')
    expect(check).toBe(true)
  })
})

MockContainerClient (src/shared/lib/container/mock-container-client.ts) already returns HTML for /artifacts/:slug/ paths — your E2E tests will work without further changes.

Checklist

• src/api/<name>-polyfill.ts — polyfill implementation with getPolyfillJs() export
• src/api/routes/agents.ts — import and add to the injection <script> tag
• agent-container/plugin/skills/dashboards/<API_NAME>.md — full reference doc
• agent-container/plugin/skills/dashboards/SKILL.md — bullet under "Built-in APIs"
• agent-container/src/dashboard-builder-agent-prompt.md — section under "Built-in APIs"
• src/api/<name>-polyfill.test.ts — unit tests (jsdom environment)
• src/api/routes/artifact-polyfill-injection.test.ts — update if injection logic changes
• e2e/specs/<name>-polyfill.spec.ts — E2E validation
• npx tsc --noEmit passes
• npx vitest run src/api/<name>-polyfill.test.ts passes
• E2E_MOCK=true npx playwright test e2e/specs/<name>-polyfill.spec.ts passes

Reference: existing polyfill

See src/api/speech-recognition-polyfill.ts and its tests as the reference implementation for this pattern.