Make Cloudflare streaming work end to end and align docs

.dockerignore

@@ -0,0 +1,31 @@
+# VCS
+.git
+
+# Node
+node_modules
+
+# Build artifacts / Logs
+.turbo
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# OS / IDE generated
+.DS_Store
+*.pem
+*.key
+
+# Examples (ignore all except the one we are building)
+examples/*
+!examples/bun-stream-server
+
+# Packages (ignore node_modules within packages, keep source)
+packages/*/node_modules
+packages/*/dist
+packages/*/tsconfig.tsbuildinfo
+
+# Specific files
+.env
+.env.*
+!.env.example 

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
     - name: Install pnpm
       uses: pnpm/action-setup@v2
       with:
-        version: 8
+        version: 9
 
     - name: Get pnpm store directory
       shell: bash
@@ -66,10 +66,10 @@ jobs:
     - name: Install pnpm
       uses: pnpm/action-setup@v2
       with:
-        version: 8
+        version: 9
 
     - name: Install dependencies
       run: pnpm install
 
     - name: Lint
-      run: pnpm lint 
+      run: pnpm lint 

.github/workflows/cloudflare-preview-cleanup.yml

@@ -0,0 +1,37 @@
+name: Cloudflare Preview Cleanup
+
+on:
+  pull_request:
+    branches: [ main ]
+    types: [closed]
+
+jobs:
+  cleanup-preview:
+    runs-on: ubuntu-latest
+    env:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+      STREAM_KIT_WORKER_NAME: bun-stream-server-pr-${{ github.event.pull_request.number }}
+      STREAM_KIT_CONTAINER_NAME: codeflare-containers-pr-${{ github.event.pull_request.number }}
+      STREAM_KIT_CONFIG_PATH: ${{ github.workspace }}/examples/bun-stream-server/.wrangler/preview-wrangler.json
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Render Wrangler config
+        run: node examples/bun-stream-server/scripts/render-wrangler-config.mjs
+
+      - name: Delete preview Worker and container
+        run: node examples/bun-stream-server/scripts/cleanup-preview.mjs

.github/workflows/cloudflare-preview-e2e.yml

@@ -0,0 +1,149 @@
+name: Cloudflare Preview E2E
+
+on:
+  pull_request:
+    branches: [ main ]
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: cloudflare-preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    outputs:
+      preview_url: ${{ steps.deploy.outputs.preview_url }}
+      worker_name: ${{ steps.names.outputs.worker_name }}
+      container_name: ${{ steps.names.outputs.container_name }}
+      container_image: ${{ steps.image.outputs.container_image }}
+    env:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+      STREAM_KIT_TURN_API_TOKEN: ${{ secrets.CLOUDFLARE_TURN_API_TOKEN }}
+      STREAM_KIT_TURN_KEY_ID: ${{ secrets.CLOUDFLARE_TURN_KEY_ID }}
+      STREAM_KIT_DEBUG_STATE_TOKEN: ${{ secrets.DEBUG_STATE_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Validate required Cloudflare secrets
+        run: |
+          test -n "$CLOUDFLARE_API_TOKEN" || (echo "CLOUDFLARE_API_TOKEN is required" && exit 1)
+          test -n "$CLOUDFLARE_ACCOUNT_ID" || (echo "CLOUDFLARE_ACCOUNT_ID is required" && exit 1)
+          test -n "$STREAM_KIT_TURN_API_TOKEN" || (echo "CLOUDFLARE_TURN_API_TOKEN is required" && exit 1)
+          test -n "$STREAM_KIT_TURN_KEY_ID" || (echo "CLOUDFLARE_TURN_KEY_ID is required" && exit 1)
+
+      - name: Compute preview names
+        id: names
+        run: |
+          echo "worker_name=bun-stream-server-pr-${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
+          echo "container_name=codeflare-containers-pr-${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
+
+      - name: Resolve base container image
+        id: image
+        working-directory: examples/bun-stream-server
+        run: |
+          container_image=$(node <<'NODE'
+          const { execFileSync } = require("node:child_process");
+          const output = execFileSync("npx", ["wrangler", "containers", "list"], {
+            encoding: "utf8",
+            cwd: process.cwd(),
+          });
+          const match = output.match(/(\[\s*\{[\s\S]*\])\s*$/);
+          if (!match) {
+            throw new Error(`Could not parse wrangler containers list output:\n${output}`);
+          }
+          const containers = JSON.parse(match[1]);
+          const container = containers.find((item) => item.name === "codeflare-containers");
+          if (!container || !container.configuration?.image) {
+            throw new Error("Could not resolve the base codeflare-containers image");
+          }
+          process.stdout.write(container.configuration.image);
+          NODE
+          )
+          echo "container_image=$container_image" >> "$GITHUB_OUTPUT"
+
+      - name: Render Wrangler config
+        env:
+          STREAM_KIT_WORKER_NAME: ${{ steps.names.outputs.worker_name }}
+          STREAM_KIT_CONTAINER_NAME: ${{ steps.names.outputs.container_name }}
+          STREAM_KIT_CONTAINER_IMAGE: ${{ steps.image.outputs.container_image }}
+          STREAM_KIT_CONFIG_PATH: ${{ github.workspace }}/examples/bun-stream-server/.wrangler/preview-wrangler.json
+        run: node examples/bun-stream-server/scripts/render-wrangler-config.mjs
+
+      - name: Clean any stale preview resources
+        env:
+          STREAM_KIT_WORKER_NAME: ${{ steps.names.outputs.worker_name }}
+          STREAM_KIT_CONTAINER_NAME: ${{ steps.names.outputs.container_name }}
+          STREAM_KIT_CONFIG_PATH: ${{ github.workspace }}/examples/bun-stream-server/.wrangler/preview-wrangler.json
+        run: node examples/bun-stream-server/scripts/cleanup-preview.mjs || true
+
+      - name: Deploy preview Worker
+        id: deploy
+        working-directory: examples/bun-stream-server
+        run: |
+          set -euo pipefail
+          deploy_output=$(npx wrangler deploy --config .wrangler/preview-wrangler.json --name "${{ steps.names.outputs.worker_name }}" 2>&1 | tee /tmp/wrangler-deploy.log)
+          preview_url=$(printf '%s\n' "$deploy_output" | grep -Eo 'https://[A-Za-z0-9._/-]+workers.dev' | tail -n1)
+          if [ -z "$preview_url" ]; then
+            echo "Failed to parse preview URL from wrangler deploy output"
+            exit 1
+          fi
+          echo "preview_url=$preview_url" >> "$GITHUB_OUTPUT"
+
+      - name: Configure preview Worker secrets
+        working-directory: examples/bun-stream-server
+        env:
+          WORKER_NAME: ${{ steps.names.outputs.worker_name }}
+        run: |
+          printf '%s' "$STREAM_KIT_TURN_API_TOKEN" | npx wrangler secret put CLOUDFLARE_TURN_API_TOKEN --config .wrangler/preview-wrangler.json --name "$WORKER_NAME"
+          printf '%s' "$STREAM_KIT_TURN_KEY_ID" | npx wrangler secret put CLOUDFLARE_TURN_KEY_ID --config .wrangler/preview-wrangler.json --name "$WORKER_NAME"
+          if [ -n "${STREAM_KIT_DEBUG_STATE_TOKEN:-}" ]; then
+            printf '%s' "$STREAM_KIT_DEBUG_STATE_TOKEN" | npx wrangler secret put DEBUG_STATE_TOKEN --config .wrangler/preview-wrangler.json --name "$WORKER_NAME"
+          fi
+
+  e2e:
+    runs-on: ubuntu-latest
+    needs: deploy-preview
+    env:
+      E2E_STREAM_SERVER_URL: ${{ needs.deploy-preview.outputs.preview_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run deployed stream E2E
+        run: pnpm --dir examples/bun-stream-server test:e2e
+
+      - name: Upload Playwright artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-preview-artifacts
+          path: |
+            examples/bun-stream-server/playwright-report
+            examples/bun-stream-server/test-results

.gitignore

@@ -52,11 +52,14 @@ junit.xml
 # Logs
 *.log
 
-# Docker
-Dockerfile
-.dockerignore
-docker-compose.yml
-*.dockerfile 
-
 # Wrangler
-.wrangler/
+.wrangler/
+playwright-report/
+test-results/
+
+# LLM context docs
+.llms
+
+# Agent working files
+.swarm/
+.claude/

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

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)

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.