open-game-system · jonmumm · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026 · Mar 13, 2026
diff --git a/.gitignore b/.gitignore
@@ -56,4 +56,8 @@ junit.xml
 .wrangler/
 
 # LLM context docs
-.llms
+.llms
+
+# Agent working files
+.swarm/
+.claude/
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -0,0 +1,10 @@
+# Stream Kit Architecture
+
+The canonical architecture document now lives at [`docs/architecture.md`](./docs/architecture.md).
+
+For the latest repo map and current status, start with:
+
+- [`docs/index.md`](./docs/index.md)
+- [`docs/architecture.md`](./docs/architecture.md)
+- [`docs/integration.md`](./docs/integration.md)
+- [`docs/status.md`](./docs/status.md)
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,61 @@
+# AGENTS.md
+
+## Project
+
+- **Name:** Stream Kit
+- **Description:** OGS cloud rendering and remote streaming workspace
+- **Tech stack:** TypeScript, pnpm workspaces, Turbo, Vitest, Cloudflare Workers, Durable Objects, Containers, PeerJS, Puppeteer
+- **Package manager:** pnpm
+- **Source layout:**
+  - `packages/` — reusable SDK and testing packages
+  - `examples/bun-stream-server/` — working Cloudflare runtime example
+  - `docs/` — repo map, integration guidance, and current status
+
+## Feedback Commands
+
+Run in this order before committing:
+
+1. `pnpm test`
+2. `pnpm typecheck`
+3. `pnpm build`
+
+## Knowledge Base
+
+Start here. Load deeper docs only when needed.
+
+| Topic | Location |
+|---|---|
+| Docs catalog | [docs/index.md](docs/index.md) |
+| Architecture | [docs/architecture.md](docs/architecture.md) |
+| OGS integration and target SDK shape | [docs/integration.md](docs/integration.md) |
+| Current verified state and next steps | [docs/status.md](docs/status.md) |
+| Cloudflare example walkthrough | [examples/bun-stream-server/README.md](examples/bun-stream-server/README.md) |
+| Workspace overview | [README.md](README.md) |
+
+> Progressive disclosure: do not load all docs up front. Start with this file, then open only the doc that matches the task.
+
+## Current Reality
+
+- The deployed Cloudflare example is working end to end.
+- The package layer is still less mature than the example runtime.
+- The intended product direction is OGS-owned infrastructure with a simpler client-facing `stream-kit` SDK.
+- `app-bridge` should likely be hidden inside the eventual OGS SDK experience rather than exposed as the primary developer API.
+
+## Boundaries
+
+- `stream-kit` should own streaming runtime and SDK behavior.
+- `opengame-api` should own the public control plane.
+- `opengame-app` should own native cast and app-shell UX.
+
+## Key Conventions
+
+- Prefer `rg` for search.
+- Use `apply_patch` for manual code edits.
+- Never revert user changes unless explicitly asked.
+- Treat `examples/bun-stream-server/` as the source of truth for end-to-end behavior.
+- Keep docs aligned with verified behavior; if the architecture changes, update `docs/`.
+
+## Git
+
+- Current branch work should go through a `codex/*` branch for PR prep.
+- Keep commits focused and descriptive.
diff --git a/README.md b/README.md
@@ -1,43 +1,63 @@
-# ☁️ @open-game-system/stream-kit
+# @open-game-system/stream-kit
 
-Monorepo for the Open Game System (OGS) Cloud Rendering service ("Stream Kit").
+Stream Kit is the Open Game System's cloud rendering and remote streaming workspace.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+Today this repo contains two layers:
 
-## Overview
+- the reusable SDK packages under [`packages/`](./packages)
+- the working Cloudflare streaming runtime under [`examples/bun-stream-server/`](./examples/bun-stream-server)
 
-Stream Kit enables web games to offload intensive graphics rendering to powerful cloud servers and stream the output via WebRTC to the client. This allows for high-fidelity experiences even on devices with limited GPU capabilities.
+The recent Cloudflare work is now verified end to end: the deployed example successfully boots a container, launches Chromium, captures a page, and delivers playable video to the receiver over WebRTC using Cloudflare TURN.
 
-This monorepo contains the core libraries, React bindings, and server implementation for the Stream Kit service.
+## Read This First
 
-## Packages
+- Repo map: [`docs/index.md`](./docs/index.md)
+- Architecture: [`docs/architecture.md`](./docs/architecture.md)
+- OGS integration guide: [`docs/integration.md`](./docs/integration.md)
+- Current status and next steps: [`docs/status.md`](./docs/status.md)
 
--   [`@open-game-system/stream-kit-types`](packages/stream-kit-types): Core TypeScript types.
--   [`@open-game-system/stream-kit-web`](packages/stream-kit-web): Core client library for web browsers.
--   [`@open-game-system/stream-kit-react`](packages/stream-kit-react): React hooks and components.
--   [`@open-game-system/stream-kit-server`](packages/stream-kit-server): Server-side implementation (headless browser management, signaling).
+## What This Repo Is For
 
-## Development
+The long-term product direction is:
+
+- third-party web games integrate a small `stream-kit` SDK
+- `stream-kit` hides the `app-bridge` details when running inside `opengame-app`
+- `opengame-api` exposes the product-facing control plane
+- OGS-owned Cloudflare Workers/Containers run the streaming infrastructure
+
+That means third-party developers should not need to deploy their own Workers, TURN servers, or container stacks just to use cloud rendering in the OGS ecosystem.
+
+## What Works Today
 
-This project uses `pnpm` workspaces and `turbo` for managing the monorepo.
+- Local streaming works through the Bun/container example.
+- Deployed streaming works through the Cloudflare example.
+- Cloudflare TURN-backed WebRTC connectivity is working in the deployed path.
+- Session routing is isolated per receiver session.
+- Worker seam tests cover TURN normalization, debug auth, and session routing.
+
+## Workspace Layout
+
+- [`packages/stream-kit-types`](./packages/stream-kit-types): shared TypeScript types
+- [`packages/stream-kit-web`](./packages/stream-kit-web): browser-side `RenderStream` client primitives
+- [`packages/stream-kit-react`](./packages/stream-kit-react): React bindings around an existing stream
+- [`packages/stream-kit-server`](./packages/stream-kit-server): experimental server-side abstractions
+- [`packages/stream-kit-testing`](./packages/stream-kit-testing): testing helpers
+- [`examples/bun-stream-server`](./examples/bun-stream-server): working Cloudflare Worker/DO/container example
+
+## Development
 
-1.  **Install Dependencies:**
-    ```bash
-    pnpm install
-    ```
-2.  **Build all packages:**
-    ```bash
-    pnpm build
-    ```
-3.  **Run tests:**
-    ```bash
-    pnpm test
-    ```
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm typecheck
+```
 
-## Contributing
+## Notes
 
-Contributions are welcome! Please see `CONTRIBUTING.md` (to be created).
+- The reusable package API is still behind the working Cloudflare example in product maturity.
+- The current OGS-facing SDK shape described in `docs/integration.md` is a target design, not a fully published package contract yet.
 
 ## License
 
-MIT License. 
+MIT
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -0,0 +1,92 @@
+# Stream Kit Architecture
+
+## Repo Shape
+
+This repository currently contains two related but distinct layers:
+
+1. `packages/` — reusable SDK and testing primitives
+2. `examples/bun-stream-server/` — the working Cloudflare runtime
+
+The example is the truth for deployed behavior today. The package layer is the productization path.
+
+## Current Working Runtime
+
+The deployed runtime lives in [`examples/bun-stream-server/`](../examples/bun-stream-server).
+
+Main pieces:
+
+- [`src/index.ts`](../examples/bun-stream-server/src/index.ts): Worker entrypoint, TURN minting, session routing, DO proxying
+- [`container/src/server.ts`](../examples/bun-stream-server/container/src/server.ts): browser lifecycle and container HTTP server
+- [`container/extension/`](../examples/bun-stream-server/container/extension): tab capture and PeerJS sender
+- [`receiver.html`](../examples/bun-stream-server/receiver.html): browser receiver used for local and deployed testing
+
+## Deployed Flow
+
+```mermaid
+flowchart LR
+  Game["Receiver / OGS client"] -->|"GET /ice-servers"| Worker["Cloudflare Worker"]
+  Game -->|"POST /start-stream"| Worker
+  Worker --> DO["Durable Object"]
+  DO --> Container["Cloudflare Container"]
+  Container --> Chromium["Chromium + extension"]
+  Chromium -->|"WebRTC media"| Game
+```
+
+Detailed flow:
+
+1. The receiver creates a session-scoped ID and PeerJS receiver peer.
+2. The receiver asks the Worker for Cloudflare TURN credentials.
+3. The receiver posts `/start-stream` with the target URL, receiver peer ID, and session header.
+4. The Worker routes that request to a session-scoped Durable Object.
+5. The Durable Object starts or reuses a container for that session.
+6. The container launches Chromium, loads the target page, and captures the tab through the extension.
+7. The extension creates a sender peer and calls the receiver using the same ICE configuration.
+8. The receiver attaches the returned media to the page and plays the stream.
+
+## OGS Product Direction
+
+The intended product architecture is different from the standalone example:
+
+- `opengame-app` owns native app UX and cast picker integration.
+- `app-bridge` is the transport between the WebView game and the native app.
+- `stream-kit` should expose the game-developer-facing SDK and hide most `app-bridge` details.
+- `opengame-api` should expose public stream and cast session APIs.
+- OGS-owned Cloudflare infrastructure should run the actual streaming runtime.
+
+## Boundary Recommendation
+
+### `stream-kit`
+
+Should own:
+
+- client SDK primitives
+- stream session client behavior
+- React components/hooks
+- app-bridge integration adapters
+- streaming runtime implementation
+
+Should not be the public place where third-party developers manage infrastructure.
+
+### `opengame-api`
+
+Should own:
+
+- authenticated public API
+- developer/game authorization
+- entitlement and quota checks
+- stream or cast session lifecycle endpoints
+- usage accounting and audit trails
+
+### `opengame-app`
+
+Should own:
+
+- native cast UI
+- session UX
+- native capability bridging
+
+## Near-Term Reality
+
+- The deployed example works.
+- The package API is not yet the polished OGS SDK shape.
+- The internal architecture is now good enough to power a productized API, but that public API still needs to be designed and implemented.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,16 @@
+# Stream Kit Docs
+
+Start here, then load only the document you need.
+
+| Topic | Location |
+|---|---|
+| Architecture and repo boundaries | [architecture.md](./architecture.md) |
+| OGS integration model and third-party developer story | [integration.md](./integration.md) |
+| Current verified state and next steps | [status.md](./status.md) |
+| Cloudflare example walkthrough | [../examples/bun-stream-server/README.md](../examples/bun-stream-server/README.md) |
+
+## Quick Summary
+
+- The Cloudflare example is the current source of truth for end-to-end streaming.
+- The long-term product should be OGS-owned infrastructure, not self-hosting by third-party game developers.
+- `stream-kit` should become the simple client SDK layer, likely hiding `app-bridge` internally when running inside `opengame-app`.
diff --git a/docs/integration.md b/docs/integration.md
@@ -0,0 +1,107 @@
+# OGS Integration Guide
+
+## Intended Developer Experience
+
+For a third-party web game inside the OGS app, the developer should ideally:
+
+1. install `@open-game-system/stream-kit` or `@open-game-system/stream-kit-react`
+2. wrap the app in an OGS provider
+3. add a `CastButton`, `StreamCanvas`, or similar primitive
+4. let OGS handle native bridge wiring, backend orchestration, and Cloudflare runtime management
+
+The developer should not need to run their own Workers, TURN servers, or Cloudflare containers.
+
+## Dependency Model
+
+Recommended model:
+
+- `stream-kit` depends on `app-bridge` internally
+- `stream-kit` exposes the high-level developer API
+- `app-bridge` remains mostly an implementation detail
+
+That keeps the public mental model simple while still using the existing `opengame-app` bridge architecture.
+
+## Theoretical Getting Started
+
+### React
+
+```tsx
+import {
+  OGSProvider,
+  CastButton,
+  StreamCanvas,
+} from "@open-game-system/stream-kit-react";
+
+export function App() {
+  return (
+    <OGSProvider config={{ gameId: "your-game-id", environment: "production" }}>
+      <CastButton />
+      <StreamCanvas route="/render/world" />
+    </OGSProvider>
+  );
+}
+```
+
+### Non-React
+
+```ts
+import { createOGSClient } from "@open-game-system/stream-kit";
+
+const ogs = createOGSClient({
+  gameId: "your-game-id",
+  environment: "production",
+});
+
+await ogs.cast.showPicker();
+
+const stream = await ogs.streaming.createStream({
+  route: "/render/world",
+});
+
+stream.mount(document.getElementById("stream-container")!);
+```
+
+## How This Should Work Under The Hood
+
+1. `stream-kit` detects whether it is running inside `opengame-app`.
+2. If available, it uses `app-bridge` to talk to the native shell.
+3. For cast actions, it dispatches native bridge events rather than exposing raw bridge APIs to the game developer.
+4. For cloud rendering, it calls OGS-owned APIs that provision stream sessions on OGS-owned Cloudflare infrastructure.
+
+## Recommended Public API Shape
+
+React surface:
+
+- `OGSProvider`
+- `CastButton`
+- `StreamCanvas`
+- `useCastSession()`
+- `useStreamingSupport()`
+- `useTVStream()`
+
+Non-React surface:
+
+- `createOGSClient()`
+- `ogs.cast.showPicker()`
+- `ogs.cast.subscribe()`
+- `ogs.streaming.createStream()`
+- `ogs.streaming.startTVStream()`
+
+## What OGS Should Own
+
+- `opengame-app`: native cast/session UX
+- `opengame-api`: public control plane endpoints
+- OGS Cloudflare Workers/Containers: streaming runtime
+
+## What Is Already True In The Codebase
+
+- `opengame-app` already exposes native cast state and `SHOW_CAST_PICKER` through `app-bridge`.
+- `stream-kit` already has a working Cloudflare runtime example.
+- `opengame-api` does not yet expose cast or stream control-plane endpoints.
+
+## What Still Needs To Be Built
+
+- a polished public `stream-kit` SDK API
+- `opengame-api` stream/cast session endpoints
+- a supported integration path from the OGS app to the stream runtime
+- docs that distinguish current implementation from target public SDK shape