feat: Shader Playground (Phase B, #52)

[devallibus]

Summary

Implements the Shader Playground — an agent-first shader editor where AI agents write GLSL via MCP tools and get visual feedback (screenshots), while humans see a live preview + code editor side-by-side.

• Design spec at docs/specs/playground.md
• Session store: SQLite (follows reviews-db.ts pattern), in-memory SSE registry, screenshot wait queue
• API routes: catch-all at /api/playground/* — create, update, state, screenshot, SSE events, errors
• UI: CodeMirror 6 editor + Three.js WebGL canvas, split layout, SSE-connected for agent updates
• MCP tools: create_playground, update_shader, get_preview, get_errors — screenshots returned as MCP image content
• 23 new tests (15 DB + 8 MCP handlers), all existing tests updated and passing

Closes #52

Test plan

• bun test passes (verified locally — 0 failures across 13 files)
• bun run dev:web → /playground loads with default shader rendering
• Edit GLSL in CodeMirror → canvas updates live
• MCP create_playground → returns session ID + URL
• MCP update_shader → returns errors + screenshot
• MCP get_errors with invalid GLSL → returns compilation errors
• Existing shader pages unaffected

🤖 Generated with Claude Code

[devallibus]

Findings:

1. High: apps/web/src/routes/playground.tsx:32 does an unconditional window.location / window.history.replaceState inside the createResource fetcher. That fetcher runs during SSR when /playground is requested without a session query, so the server path creates a session and then hits window is not defined before hydration. I built apps/web and the generated SSR bundle still contains those raw window calls, so this is not being compiled away.

2. Medium: apps/web/src/components/playground/PlaygroundLayout.tsx:63 posts manual editor changes to /api/playground/:id/update without any auth header, while apps/web/src/routes/api/playground/$.ts:140 rejects that route unless Authorization: Bearer <PLAYGROUND_SECRET> is present. In a real secured deployment, browser-side editing silently stops persisting or broadcasting changes because the fetch error is swallowed. The playground then only works for agent-driven updates.

3. Medium: The new tool contract advertises less than the implementation supports. Both schemas for create_playground in packages/mcp/src/index.ts:111 and packages/mcp/src/index.ts:238 omit uniforms, but the handler and shared API types explicitly accept it in packages/mcp/src/playground-handlers.ts:21 and apps/web/src/lib/playground-types.ts:57. Schema-driven MCP clients will therefore never expose or may outright reject the uniforms input, even though the backend supports it.

Checks run:

• node --experimental-strip-types packages/mcp/src/playground-handlers.test.ts
• node --experimental-strip-types apps/web/src/lib/server/playground-db.test.node.ts
• bun run build:web

[devallibus]

All three findings addressed in 4f77b48. Here's the breakdown:

1. High — SSR crash from window access

Fixed. Moved the URL update out of the createResource fetcher entirely. Now uses a createEffect with isServer guard from solid-js/web and useNavigate from TanStack Router (which is SSR-safe). The fetcher just returns the session — no browser APIs touched during SSR.

2. Medium — Browser editor blocked by auth on /update

Fixed. Removed the isAuthorized() check from /update. The session UUID itself acts as a capability token — it's a random UUID, unguessable, and scoped to a single session. Both the browser editor and the MCP worker can now update without a secret. Only /create still requires PLAYGROUND_SECRET since that's the only endpoint that allocates new server resources.

3. Medium — uniforms missing from create_playground schema

Fixed. Added the uniforms array (with name, type, defaultValue required + optional description, min, max) to both TOOLS and TOOLS_MCP_FORMAT definitions for create_playground.

---

Re: what is PLAYGROUND_SECRET — it's a shared secret between the MCP Cloudflare Worker and the Railway web app, set as an environment variable on both. The MCP worker sends it as Authorization: Bearer <secret> when calling the web app's /api/playground/create endpoint. This prevents arbitrary external callers from creating sessions (which allocate DB rows). It does NOT gate session-scoped operations (/update, /screenshot, /errors) — those use the UUID as the auth token.

In dev mode (no PLAYGROUND_SECRET set), all endpoints are open. In production, you'd set it via railway variables and wrangler secret put PLAYGROUND_SECRET.

[devallibus]

Follow-up fix pushed in 4d5c112.

I found one residual edge case after the earlier review fixes: when /playground?session=<id> was present but invalid, the route correctly created a fresh session on the server, but the client only rewrote the URL when the query param was missing entirely. That meant a bad session param could keep producing hidden replacement sessions on refresh while the address bar continued to point at the stale ID.

The change in apps/web/src/routes/playground.tsx now replaces the URL whenever the loaded session ID differs from search.session, not just when search.session is empty. In practice:

• missing session param -> URL is populated with the created session ID
• valid session param -> URL is left alone
• invalid session param -> URL is rewritten to the newly created replacement session ID

I also included the regenerated apps/web/src/routeTree.gen.ts that the web build updated alongside the route change.

Verification:

• bun run build:web