feat(weaverse): per-request projectId resolver + 24h cookie for Cloud Sandbox

[paul-phan]

Summary

Phase 1.5 Slice 1.5c of Weaverse/builder#2222 (Cloud Sandbox).

A single sandbox machine serves multiple projects (M:N preview model from builder#2326). The Weaverse Hydrogen SDK already resolves ?weaverseProjectId=<id> from the URL query with highest priority — the missing piece is that once the user clicks an in-iframe link and the query string disappears, the SDK falls through to env.WEAVERSE_PROJECT_ID and the wrong theme renders.

This PR adds a tiny cookie bridge: ~95 LOC, 3 files, zero SDK changes.

How it fits the SDK's existing priority chain

@weaverse/hydrogen's projectId resolution (already shipping in v5.13+):

  1. ?weaverseProjectId=<id> URL param   ← Studio iframe ALWAYS sets this
  2. projectId function arg              ← THIS PR plugs in here
  3. projectId string arg
  4. env.WEAVERSE_PROJECT_ID             ← bare URL fallback

Slot 2 was unused. We fill it with () => readProjectIdFromCookie(request). Cookie is set on the way out whenever slot 1 fires, so in-iframe navigation after the initial load (which loses the query string) still resolves the same project.

Files

File	What
app/lib/weaverse/resolve-project.server.ts (new)	readProjectIdFromCookie + maybeSetProjectIdCookie. ~75 LOC.
app/.server/context.ts	Pass projectId: () => readProjectIdFromCookie(request) to WeaverseClient.
server.ts	After response, call maybeSetProjectIdCookie(request, response).

Why the call is AFTER session.commit()

This is the subtle bit. server.ts already does:

response.headers.set("Set-Cookie", await hydrogenContext.session.commit())

.set() (not .append()) clobbers any existing Set-Cookie header. If I .append() my project cookie before that line, it gets nuked.

So the order is:

1. handleRequest → response built
2. session.commit() → session cookie .set()
3. maybeSetProjectIdCookie → project cookie .append()

Both cookies ride along on the same response. There's an inline comment in server.ts documenting this so a future refactor doesn't reorder them.

Security

• Cookie value validated against /^[a-zA-Z0-9_-]{1,128}$/ on both read and write paths. Poisoned cookies silently return '', falling through to env.
• Cookie flags: Max-Age=86400; Path=/; SameSite=Lax; Secure; HttpOnly
  • Lax over Strict: cookie is for the sandbox origin (<handle>.weaverse.dev) which IS top-level when the SDK reads it. Strict would break in-iframe nav.
  • HttpOnly: not strictly needed (we never read client-side) but defense-in-depth.
• Studio iframe always sets the explicit ?weaverseProjectId= query param when loading (per Phase 1.5 spec). Cookie is a fallback for in-iframe nav only, never trusted cross-tab.

Test plan

• npm run typecheck — 1 pre-existing error (bun cache duplicate @shopify/hydrogen versions, unrelated, present on bare main), 0 new.
• npm run biome — 3 useBlockStatements style warnings, exit 0.
• Smoke test (manual, post-merge): load <handle>.weaverse.dev/?weaverseProjectId=A, click an in-iframe link, confirm the response still uses project A (not env default). Then load <handle>.weaverse.dev/?weaverseProjectId=B, confirm cookie is updated and B renders.

Why no unit tests

Pilot uses Playwright e2e only; no unit-test runner is configured. The module is small (regex + cookie parse + Set-Cookie header build). Real traffic from Phase 1.5d onward will exercise it within a few days of merge. Adding a Vitest setup just for this would be scope creep.

If you want me to add a Vitest setup anyway, happy to in a follow-up — but for one 75 LOC module on a tight schedule, the cost-benefit doesn't pencil out.

Rollout

Deploys to the weaverse-sandbox Pilot theme image. Once merged, the next bun run build-theme.sh in weaverse-sandbox picks it up and bakes it into a new theme image digest. Then the next sandbox machine boot uses it. Existing running sandboxes pick it up on next image refresh.

No breaking changes for non-sandbox Pilot deployments — the cookie is only ever read when set, and only ever set when the query param is present.

Refs Weaverse/builder#2222 Phase 1.5 Slice 1.5c. Spec: Weaverse/builder/.specs/2026-05-12--cloud-sandbox-phase-1/README.md.

Stacks logically on:

• Weaverse/builder#2326 (schema)
• Weaverse/builder#2327 (API)

Independent at the git level — this can merge any time.

[paul-phan]

Closing \u2014 moving the implementation into @weaverse/hydrogen instead.

Pilot is a starter template that customers fork and maintain on their own schedule; we can't ship cookie + resolver changes here without risking breakage in downstream forks. The proper place for multi-project preview support is the SDK package itself, where:

1. Old themes keep working unchanged (no behavior change for non-sandbox setups).
2. New themes get cookie-based projectId resolution automatically after bumping @weaverse/hydrogen.
3. The cookie WRITE side becomes a single opt-in helper for themes that want sandbox-iframe nav persistence \u2014 documented but not required.

New PR coming on the Weaverse monorepo SDK. Will link back here.