feat: rewrite as TanStack Start app — a clearer HyperFrames-on-Cloudflare example

[tombeckenham]

Summary

Rewrites the template as a TanStack Start app with TanStack AI powering the BYOK generation flow, and applies a round of security/error-handling hardening from a multi-agent review. Same product surface as before — preview the bundled composition, generate one from a prompt with your own OpenRouter account (OAuth login, or paste a key), render MP4s in the Chromium+FFmpeg container, serve them from R2 — but the code now reads as an example rather than as plumbing.

Why TanStack makes this a clearer HyperFrames-on-Cloudflare example

The point of this template is to show how to integrate HyperFrames on Cloudflare — the player, the lint/self-heal loop, and the render container. The previous version buried those integration points inside hand-rolled infrastructure:

• Before: one 263-line src/index.ts doing manual URL routing, request parsing, and SSE plumbing, plus a 381-line static public/index.html with inline vanilla JS managing all UI state and stream handling. To find the HyperFrames-specific code, a reader had to wade through everything else first.
• After: file-based routes make each integration point a small, named file you can read in isolation:
  • src/routes/api/render.ts — the render-container call: composition files in, MP4 out, streamed to R2
  • src/routes/api/generate.ts — the AI pipeline: HyperFrames skill prompt + chat() + OpenRouter adapter over SSE
  • src/components/Player.tsx — exactly how to wrap the <hyperframes-player> web component in React, including the src → srcdoc swap for generated compositions
  • src/lib/server-fns.ts — @hyperframes/core/lint as a typed server function the client calls like a local async function
• TanStack AI replaces hand-rolled streaming state. The generate → lint → fix-turn self-heal loop is now ~40 lines of readable app logic in AiPanel.tsx (useChat + onFinish), instead of bespoke SSE parsing and DOM mutation. Anyone copying this template into a real app gets the pattern they'd actually use.
• It demonstrates the current recommended full-stack React setup on Workers. TanStack Start runs first-class on Cloudflare via @cloudflare/vite-plugin — SSR, typed file routes, server functions, and Vite HMR in dev — so the template doubles as a reference for "modern React app on Workers with a container-backed API," which is the shape most adopters will build.

Log in with OpenRouter (OAuth PKCE)

The AI panel's primary path is now a Log in with OpenRouter button instead of pasting an API key (manual key entry remains as a fallback toggle):

• src/lib/openrouter-oauth.ts runs OpenRouter's OAuth PKCE flow entirely client-side: S256 code challenge → redirect to openrouter.ai/auth → exchange the one-time callback code for a runtime API key scoped to this app (revocable from the OpenRouter dashboard)
• No client secret and no server involvement — the minted key never touches the Worker outside of generate requests, and no callback URL registration is needed, so it works on localhost and any deployment out of the box
• Security posture preserved: the key lives in React memory only, same as the pasted-key flow. The PKCE code verifier is the one sanctioned sessionStorage use — it exists only across the redirect round-trip and is deleted (with ?code stripped from the URL) before any generated composition can run

Security & robustness fixes (from review)

• /api/render custom-HTML rendering is now gated by ENABLE_AI_GEN — previously a public demo with generation "disabled" still let anyone run arbitrary HTML through the render container on the deployer's account
• The BYOK key is held in memory only, never sessionStorage: generated compositions execute same-origin inside the player iframe (allow-scripts allow-same-origin) and could read origin storage; the UI now says so and recommends a spend-capped key
• Removed the empty preview_image_url that re-broke the Deploy to Cloudflare button (same issue as 02b8a69)
• Server error messages now reach the user (the ENABLE_AI_GEN hint, prompt-size caps, container failures) instead of bare status codes; lint-service failures warn instead of reporting false success
• /r/$ serves only renders/* keys; R2 writes are logged with context on failure; message roles and durationSec are validated at the boundary

Testing

• Vitest suite (22 tests): stripMarkdownFence edge cases, fix-message formatting, base64/UTF-8 encoding round-trips across the 32KB chunk boundary — covering both the native Uint8Array.toBase64() path (Workers/Node 25+) and the chunked fallback (Node 22 LTS) — plus the OAuth PKCE helpers (base64url encoding, the RFC 7636 appendix B challenge test vector, auth URL construction)
• npm test, npm run typecheck, and npm run build all pass; independently re-verified by two review agents against @tanstack/ai-client internals (error propagation, stream finalization)

🤖 Generated with Claude Code

[jrusso1020]

Ran an ultra-critical pass per Bin's ask — read the full files, not just the diff, and verified each of the six flagged security surfaces at source (and against the test vectors). No blockers. The security-critical invariants are all correct. Two non-blocking findings and one minor nit are worth the author's consideration; leading with those since scrutiny was the point.

Findings

1. allow-same-origin means "memory-only" is a bar-raiser, not an isolation boundary (non-blocking, but the security note slightly overstates it).
The BYOK key genuinely never touches sessionStorage/localStorage — verified: it lives only in useState/useRef (AiPanel.tsx:49,57) and is forwarded per-request (:108). That correctly removes the trivial sessionStorage.getItem() read vector. But the framing "held in memory only … generated compositions could read origin storage" implies memory placement keeps the key away from the composition, and it doesn't: with allow-scripts allow-same-origin, a generated composition can reach window.parent (same-origin), and from there walk the React fiber tree (__reactFiber$* → memoizedState of the key hooks) or override parent.fetch to capture apiKeyRef.current on the next generate/self-heal turn. So the real blast-radius control is the spend-capped, revocable key (which the UI does recommend — good), not where the key is stored. Two options: (a) tighten the wording so it credits the spend-cap rather than the memory placement, and/or (b) if you want true isolation, run the generated preview in a sandboxed iframe without allow-same-origin (opaque origin) — with the caveat that this likely breaks the <hyperframes-player> runtime, which is presumably why same-origin is used. Fine to ship as-is for a template; worth a precise sentence so adopters don't over-trust it.

2. OAuth-callback effect gates a one-time, irreversible side effect behind cancelled (non-blocking robustness).
consumeOAuthCallback() synchronously consumes the one-time code, removes the verifier, and strips the URL — then awaits the key exchange (openrouter-oauth.ts:58-85). In AiPanel.tsx:64-83 the minted key is applied only if !cancelled. If <AiPanel> unmounts between the synchronous strip and the async resolve, the successfully-minted key is discarded with no recovery (code already consumed, verifier gone, ?code stripped) — login silently no-ops and the user must restart. Today this can't fire (StrictMode is off and AiPanel doesn't remount in the normal flow), but the inline comment at :61-63 ("a second effect run (React strict mode) is a no-op") is subtly wrong: under StrictMode the first run's key is the one dropped by cancelled, so enabling StrictMode — a common hardening — would make OAuth login silently fail in dev. Suggest applying the minted key regardless of the closure's cancelled flag (it's a legitimate one-shot mint), or hoisting the exchange behind a useRef/module one-shot guard so the result survives a remount.

3. durationSec has a lower bound but no upper clamp (minor).
generate.ts:111-114 validates Number.isFinite && > 0 but doesn't cap it. It's only a prompt hint (feeds buildUserPrompt), so blast radius is small — output is capped by MAX_OUTPUT_TOKENS and render is separately gated — but an absurd value could nudge the model toward a very long composition that inflates render time/cost on the deployer's account. A Math.min(durationSec, MAX) closes it cheaply.

Observation (pre-existing, out of scope): the bundled-composition render path (/api/render with no body) is intentionally ungated so the public "Render" button works, so a public demo can be driven to re-run the (bounded, known) bundled render on the deployer's account. Same property as the pre-rewrite version — a per-IP rate limit would harden a public demo, but that's not this PR's job.

Verified correct (the surfaces Bin flagged)

• ENABLE_AI_GEN render gate — closes the arbitrary-HTML hole on every custom-HTML path: the gate is the first check inside if (body?.html) (render.ts:40-49), so non-string/truthy html still hits it; omitting content-type: application/json doesn't smuggle HTML past it (it falls through to the bundled composition, ignoring the body). Matched at /api/generate too (:58-63).
• R2 /r/$ serving — key.startsWith("renders/") gate (r.$.ts:10); R2 keys are literal strings (no filesystem traversal, so renders/../x is just a non-existent key), and RENDERS is a dedicated bucket (hyperframes-renders) holding only render outputs. No prefix bypass, no traversal.
• base64 chunk boundary — the chunked fallback builds one binary string across 0x8000 chunks then a single btoa (encoding.ts:24-33), so the boundary can't corrupt output; encoding.test.ts exercises below/at/above (0x7fff/0x8000/0x8001) + multi-chunk and asserts native === chunked. Correct and genuinely covered.
• OAuth PKCE — S256 challenge matches the RFC 7636 Appendix B test vector (openrouter-oauth.test.ts:33), verifier is 32 random bytes → RFC-compliant 43-char base64url, and the verifier is removed + ?code stripped synchronously before the exchange, so it can't leak to a composition (which can't run until after a key exists anyway).
• Boundary validation / errors — message role is validated and a client-supplied system role is rejected (generate.ts:89-92), which nicely blocks client-side system-prompt injection since the real system prompt is server-injected; size caps are present everywhere (key 1KB, prompt 8KB, render HTML 2MB, output 16k tokens); server error messages now propagate to the user in both AiPanel and RenderControls.

Nice rewrite — the integration points read much more clearly as an example, and the hardening is real. Findings 1 and 2 are the two I'd want the author to weigh before merge; neither blocks.

— Jerrai

[jrusso1020]

durationSec is validated > 0 && finite but not upper-bounded. It's only a prompt hint so blast radius is small, but an absurd value could push the model toward a very long composition that inflates render cost. A Math.min(durationSec, MAX) closes it. (Summary finding #3, minor.)

[jrusso1020]

Verified: this gate is the first statement inside if (body?.html), so it covers every custom-HTML path — a non-string/truthy html still hits it, and a request without application/json content-type falls through to the bundled composition (body ignored) rather than smuggling HTML past the gate. This closes the arbitrary-HTML-on-deployer's-account hole cleanly.

[jrusso1020]

Verified path-traversal-safe: R2 keys are literal strings (not filesystem paths), so renders/../x is just a non-existent literal key, and RENDERS is a dedicated bucket holding only render outputs. The startsWith("renders/") gate is sufficient here — nothing sensitive is reachable.

[tombeckenham]

Thanks for the review @jrusso1020. I've made some changes to the wording and comments around the sign in with openrouter key.

[miguel-heygen]

Additive exact-head review at 4fd6d67b4c51020e81ff3b355c93eaadaa50ff84. Rames already covered the OAuth, same-origin key exposure, render gate, R2 prefix, and base64 boundary surfaces; this pass focused on the freshness delta and clean-checkout reproducibility.

Audited: src/components/AiPanel.tsx, src/lib/openrouter-oauth.ts + tests, src/routes/api/{generate,render,preview}.ts, src/routes/r.$.ts, server asset/lint functions, package scripts, and the full 7a6439c..4fd6d67 delta.

Trusting: generated worker-configuration.d.ts / routeTree.gen.ts, lockfile internals, CSS, and unchanged composition assets.

The freshness fixes are structurally sound: openrouter-oauth.ts:64-70 memoizes the one-shot exchange at module scope, and openrouter-oauth.test.ts:39-83 pins the consumed-code/repeat-call behavior. The revised same-origin warning in AiPanel.tsx:14-21,225-241 is also materially more accurate.

blocker — the advertised typecheck does not work from a clean checkout. package.json:36 runs bare tsc --noEmit, while src/lib/server/assets.ts:2 imports src/composition-manifest.json, which is generated by scripts/build.mjs and explicitly gitignored. I reproduced this from the exact head:

npm ci
npm run typecheck
src/lib/server/assets.ts(2,22): error TS2307: Cannot find module '../../composition-manifest.json'
src/lib/server/assets.ts(23,31): error TS7006: Parameter 'rel' implicitly has an 'any' type.

Running npm run build first creates the manifest and makes typecheck pass, which explains how the PR-body claim could look green locally, but fresh contributors and any standalone typecheck job get a deterministic red command. Make typecheck prepare the required assets (or commit/provide a typed manifest that exists before build) and pin the clean-checkout sequence in CI. This repo currently reports no PR checks, so nothing catches the regression.

Local verification: npm test — 23/23 pass; npm run build — pass; npm run typecheck after build — pass.

Verdict: REQUEST CHANGES
Reasoning: the current runtime/security fixes look sound, but a documented verification command deterministically fails on the exact head from a clean clone because its generated input is missing.

— Magi