Remote and bundled modes

Remote mode keeps the server as the document origin. Bundled mode moves the UI into the shell and keeps data on an API origin. That choice changes startup and the browser's request boundary.

flowchart TD
  subgraph Remote
      R[Remote WebView] -->|HTTP document, fetch, or form with radical-context cookie| S[Framework server]
      S -->|Server-rendered HTML and data| R
  end
  subgraph Bundled
      L[Packaged SPA on local shell origin] --> F[createRadicalFetch]
      F -->|Eligible local or API URL rewritten to config.origin| C[Credentialed CORS request with x-radical-context]
      C --> W[withBundledRequests]
      W -->|Allowed OPTIONS: 204 CORS response| L
      W -->|Other requests| M[createRadicalRequestMiddleware]
      M --> A[Start handler and API]
      A -->|Response through wrapper, CORS and exposed headers| L
  end

The bundled origins are https://localhost on Android and capacitor://localhost on iOS. Global fetch, HTML forms, third-party origins, and ordinary browsers retain normal request behavior. Only createRadicalFetch routes eligible shell requests.

Startup follows the UI locationCopy Anchor Link

Packaging HTML does not make remote data available offline.

CORS grants access, not identityCopy Anchor Link

The wrapper grants credentialed CORS only to the two local origins. Start's middleware permits those origins through server-function CSRF checks and retains checks for other callers. Neither authenticates requests.

The TanStack wrapper exposes x-tss-serialized, x-tss-raw, and x-tss-error. Core withBundledRequests(handler, outputs?) exposes no headers unless supplied with adapter outputs. Without those headers, bundled Start clients cannot read the response protocol.

Switch to bundled mode contains the setup steps. The bundled-mode decision records the request contract.