sideshow: Instructions file for Codex

sideshow — agent guide

Guidance for agents developing this repo. (The block that teaches agents to use a running sideshow lives in guide/AGENT_SETUP.md, served at /setup.) CLAUDE.md symlinks here.

What this is and why

A live visual surface for terminal coding agents: agents publish posts (multi-surface cards — html, markdown, diff, terminal, image, mermaid, json, code) over CLI/MCP/HTTP; the user watches them render in a browser and comments back. The two-way loop — publish → live render → comment → revise/reply — is the product. When in doubt, optimize for the loop.

Current product stances (deliberate choices, not accidents — revisit consciously, not as a side effect):

• One workspace per person; one session per agent conversation. Accounts and multi-user are out of scope; auth is a single deploy token.
• Three integration tiers, most universal first: zero-dependency CLI, MCP (stdio and streamable HTTP at /mcp), raw HTTP. Features should work on all three — the CLI and curl tiers are why agents with only a shell can use this.
• Feedback is never silently lost: a user comment renders in the viewer (the card's thread) and reaches the agent (userFeedback piggybacked on writes, a blocking wait, or a background watch). Guard this hardest — both halves have regressed before.
• Trace exists in the codebase as an experimental path. Keep it out of the product-facing surface taxonomy and agent guidance unless the task is explicitly about deciding or finishing traces.

Map

• server/app.ts — runtime-agnostic Hono app: all routes, SSE /api/events, long-poll /api/comments, renderer /s/:id, asset upload/serve (/api/assets, /a/:id), and the shared flow functions both REST and MCP call.
• server/types.ts — data model + Store interface; no runtime imports. A post is an ordered list of surfaces (html | markdown | diff | terminal | image | mermaid | json | code); a snippet is sugar for a single html surface. htmlSurface bridges the legacy snippet shape. Assets (uploaded blobs) are a separate entity, referenced by image surfaces and the experimental trace path; selectEvictions is the reference-aware LRU policy.
• server/public.ts — the sideshow/server package export (createApp, SqlStore, createSqliteStorage, JsonFileStore, types) for embedding the app.
• server/sqlStore.ts — SqlStore, the SQLite-backed Store. It takes a SqlStorage (the narrow SQL surface declared in types.ts, not the ambient Cloudflare global), so the SAME store runs on the Durable Object (ctx.storage.sql) and on Node via server/sqliteStorage.ts's node:sqlite adapter — the local default, so dev mirrors the deploy. server/storage.ts — JsonFileStore, the legacy single-file store, still selectable with SIDESHOW_STORE=json. All must pass test/storeContract.ts, and all migrate legacy snippets/snippetId data to surfaces on load. On first SQLite boot migrateJsonToSqlite copies an existing JSON workspace in once (identity, history, and comment seq preserved via JsonFileStore.exportBoard → SqlStore.importBoard); it's idempotent and never imports into a non-empty db.
• server/kits.ts — opt-in style/behavior bundles for html surfaces (issues, slides). An html surface lists kit ids in kits; renderHtmlPage injects each kit's CSS/JS into the sandbox after the base. Runtime-agnostic; allowlisted in server/postSurfaces.ts and listed at /api/kits. Adding a kit is a registry entry + a guide bullet — no new surface kind, no native renderer.
• server/richRender.ts — server-side renderers for the rich kinds (renderMarkdown/renderCode/renderDiff/renderTerminal → {body, css}), runtime-agnostic so they run on the Worker DO too (shiki on the JS regex engine, @pierre/diffs SSR via shiki-js, markdown-it, ansi_up — no WASM/DOM). /s/:id calls these and wraps the result in renderSandboxedPart.
• server/surfacePage.ts — sandboxed documents for surface markup. renderHtmlPage wraps an html surface (CDN-allowlist CSP + the postMessage bridge: resize, sendPrompt, openLink) and injects any opted-in kits (kits.ts). renderSandboxedPart wraps a server-rendered rich body (markdown/code/diff/ terminal — see richRender.ts) under a tighter CSP (no connect-src, no CDN). renderMermaidPage is the one exception: mermaid needs a DOM, so it can't be server-rendered — instead it emits a self-rendering doc that loads mermaid from the CDN allowlist (so it uses the html-surface CSP, which permits the CDN). Image and json surfaces stay native because they have no HTML sink; the experimental trace path follows the same data-only rule. Comments render as escaped Solid text nodes. No agent markup is ever set as innerHTML in the trusted viewer origin.
• server/themes.ts — theme registry (github/gruvbox/one), runtime-agnostic so both server and viewer import it. One Palette per light/dark per theme; the viewer-chrome vars and the html-surface --color-* tokens are both derived from it, so they can't drift. Persisted per workspace (Store.getSetting), switched at /api/theme.
• server/mcpHttp.ts — stateless MCP at /mcp. mcp/server.ts — stdio MCP, a thin client over the HTTP API (passes response fields through untouched).
• viewer/ — the viewer: Solid + TypeScript in viewer/src/, built by Vite (vite.config.ts) into a single self-contained viewer/dist/index.html (vite-plugin-singlefile) that the server still serves as one in-memory document — there are no static-asset routes.
• bin/sideshow.js — CLI, Node built-ins only; bin/demoData.js — seed content for sideshow demo.
• workers/index.ts — Cloudflare entry; one Durable Object runs the whole app.
• skills/sideshow/ + guide/ — teach agents to use a running sideshow.
• scripts/record-demo.mjs — regenerates the README gif.