modem-dev/sideshow

Purpose and entry points

Sideshow is a live visual-surface system for coding agents: agents publish typed, composable content cards and users view them live in a browser, respond in threads, or connect through HTTP/MCP/CLI. Primary Node entry points are bin/sideshow.js and server/index.ts; demo seeding is bin/demoData.js. The browser viewer begins at viewer/src/main.tsx.

Server application and API

The Node application assembles HTTP routes, static viewer delivery, session/surface APIs, and runtime services in server/app.ts and server/index.ts. Surface creation/update logic and post-oriented surface handling sit in server/postSurfaces.ts; externally consumable/API-oriented views are defined in server/apiViews.ts. This is the boundary between agent-facing writes and viewer-facing reads.

Persistence and migration

A storage abstraction permits local persistence implementations behind the app layer: server/storage.ts, server/sqlStore.ts, and server/sqliteStorage.ts. Data-directory and data-model evolution is handled by server/migrateDataDir.ts. This isolates sessions, posts/surfaces, comments, and assets from Node versus Worker deployment concerns.

Live updates and interaction flow

Agents publish surfaces through HTTP or MCP; the server persists them and broadcasts updates through server/events.ts. The viewer consumes API/event state via viewer/src/api.ts and viewer/src/state.ts, then renders session timelines and cards. User feedback travels back as posts/notes, with viewer-side handling in viewer/src/viewerPost.ts and viewer/src/notes.ts.

Viewer rendering boundary

The Solid/Vite viewer is a self-contained client application rooted in viewer/src/App.tsx. It dispatches typed surface parts to native renderers such as viewer/src/TraceSurface.tsx, viewer/src/JsonSurface.tsx, and viewer/src/ImageSurface.tsx; themes are applied through viewer/src/theme.ts. Agent-authored HTML is a distinct rendering/security boundary, while markdown, diffs, code, Mermaid, JSON, terminal output, and traces are rendered using viewer-owned chrome and styles.

Agent integrations

The CLI launches and connects local instances through bin/sideshow.js. MCP support has both transport/runtime handling and a formal tool specification in server/mcpHttp.ts and server/mcpSpec.ts; a stdio MCP server is exposed from mcp/server.ts. Claude integration is distributed as plugin/skill metadata under plugin/.claude-plugin/plugin.json and plugin/skills/sideshow/SKILL.md; a lightweight extension exists at extensions/sideshow.js.

Cloudflare deployment and image capture

A Cloudflare Worker entry point adapts the service for remote/shared deployments in workers/index.ts, with public-serving behavior in workers/public.ts. Worker storage/runtime typing is represented by workers/modules.d.ts. PNG surface capture is Worker-only and integrates Cloudflare Browser Rendering through workers/screenshot.ts; local Node deliberately does not provide this headless-browser capability. Wrangler deployment configuration is wrangler.jsonc.

Terminal sibling

sideshow-term/ is an alpha sibling rather than the browser viewer: it parses and renders terminal surface markup through sideshow-term/src/parse.ts, sideshow-term/src/render.ts, and CLI preview/watch flows such as sideshow-term/src/previewCli.ts. It has its own server and package boundary at sideshow-term/server.ts.