Skip to main content

Scope

This page records the current behaviour of apps/playground (Next.js 16.4) that the TanStack Start + Void + Vite+ + Cloudflare migration must preserve. It is the first Playground PR from the migration inventory: contracts only, with no framework or hosting change. The contract tests live in apps/playground and run with bun run test from that directory. They use module fakes for the API proxy guard, the AI provider and satellite staff-session dependencies, so they make no network calls and need no credentials.

What Playground does not own

apps/playground is an internal experiment surface. It does not evaluate user-supplied code. Code-execution playgrounds (sandboxed runtimes, previews and checkpoints) are owned by the devbox sandbox in packages/sdk and by Web routes under /api/v1/users/me/playgrounds/**, and are accepted by playground-runtime-acceptance.yaml. The migration must not move execution, preview or sandbox responsibilities into this app. Adding any of them is a new trust boundary that needs its own design, review and contract tests first.

Current shape

Invariants and tests

Paths are relative to apps/playground.

Migration rules

  • Port these tests with the app; keep each invariant green on the Start/Worker runtime before any cutover. Changing an invariant is a reviewed behaviour change, not a migration detail.
  • Header invariants (9–12) must be reproduced by the Worker response path, using the shared framable-path list from @tuturuuu/utils/framable-paths as the start-bridge Worker does.
  • The /api ordering in invariant 13 must hold on Cloudflare: local handlers answer first, then Web. Do not add a catch-all route that captures /api/*.
  • Keep the API proxy guard (17–21) in front of local and proxied /api traffic.
  • Keep API ownership with Web; do not copy Web handlers into this app.
  • Keep the current host until the app’s explicit cutover, per the active runtime rules.