Adopt an Astro activation shell with an on-demand Flect runtime

[robinbraemer]

Outcome

Make an opened browser interface useful without loading the Flect authoring system. Adopt Astro on top of Vite as the intended static browser document and activation shell if a measured spike proves that it beats an equivalent direct Vite SPA dynamic-import boundary without weakening Tauri packaging, CSP, isolation, focus, or testability.

Opening the product UI and activating Flect are separate lifecycle events.

Architecture decision

The canonical decision is docs/decisions/0003-astro-activation-shell.md.

This issue implements the cold-load and activation boundary required by #20 and #36. It composes with the live canvas in #32 and the persistent workspace in #33.

Required behavior

• Render the view-only browser document and protected unavailable state as static Astro output.
• Let the opened product interface load only its own required application JavaScript.
• Do not construct the Flect agent, Effect client runtime, workspace, Git, compiler, package manager, shell, sandbox, Worker, or Wasm runtime because a shared interface opened.
• Load the protected Flect client only after an explicit signal such as Edit with Flect, composer focus, the Flect shortcut, or an operation requiring a Flect capability.
• Acknowledge activation in the same frame, preserve focus and layout, and mount the protected agent surface through an event-driven dynamic import or reviewed custom client directive.
• Construct one scoped FlectClientLayer after activation.
• Acquire compiler, shell, package, sandbox, Worker, and Wasm Layers only for the typed tool operation that needs them and dispose them through their Effect scopes.
• Keep browser, Tauri, and test composition roots separate. React renders validated snapshots and ephemeral input state; it does not coordinate build, Git, recovery, or capability workflows.
• Package static output in Tauri without an Astro server. Tauri remains responsible for platform-native windows, menus, dialogs, shortcuts, appearance, accessibility, and lifecycle.

Framework boundary

Astro framework integrations are build-time host composition, not a universal runtime for arbitrary source projects.

• Do not install or hydrate every supported framework in the Flect host.
• Do not download multiple framework runtimes speculatively.
• Keep ordinary React/Vite import in Import standard React and Vite projects #8 and framework-neutral browser projects in Run ordinary browser-compatible web frameworks without Flect-specific adapters #9.
• Run user projects through the canonical workspace, build, isolation, live-canvas, diagnostics, and export contracts in Host each Flect app in a persistent incremental frontend workspace #33.

Validation spike

Before replacing the current direct Vite SPA entry, compare an Astro-on-Vite document and island host with a direct Vite SPA using the same event-driven dynamic-import boundary. Both variants continue to use Vite and must include:

1. a static opened-interface route;
2. explicit Edit with Flect activation;
3. the existing React protected shell behind that activation;
4. a stub typed Effect client Layer constructed only after activation;
5. a stub tool Layer loaded only after a tool request;
6. production bundle and request-graph evidence;
7. AXI tests for open, activate, reload, keyboard activation, narrow layout, reduced motion, light/dark, Fast 4G, and Slow 4G; and
8. a Tauri production-bundle smoke test using static output.

Performance gates

• A view-only route requests no Flect agent, Effect runtime, workspace, compiler, shell, package, sandbox, Worker, or Wasm chunk.
• The Flect activation bootstrap is <= 10 KiB gzip.
• The protected interactive Flect client is <= 200 KiB gzip and <= 600 KiB decoded before optional tools.
• esbuild, Rifty, QuickJS, just-bash, package clients, and Worker/Wasm artifacts load only on the typed operation that requires them.
• Activation acknowledges input in the same frame with no layout shift or focus loss.
• The warmed protected composer is usable within 300 ms locally and 1,000 ms on the Fast 4G / 4x CPU profile.
• Opening and using the product interface remains possible while the Flect runtime is offline.
• The stricter browser and packaged-host budgets in Make Flect feel instant with strict live-editing performance budgets #20 and Make every supported Flect host feel native and lag-free #36 remain mandatory.

Acceptance criteria

• Production request graphs prove the view-only, activated-client, and first-tool payloads independently.
• The selected Astro-on-Vite implementation has a smaller initial product path and a clearer lifecycle boundary than the direct Vite SPA baseline.
• Browser history, URLs, selection, clipboard, context menus, zoom, reflow, accessibility settings, and offline behavior remain correct.
• Static output passes the existing Tauri CSP and isolation boundary without adding ambient native authority.
• Tool cancellation, runtime disposal, reload, and repeated activation leave no orphan Workers, sessions, previews, or event listeners.
• The ADR records the measured Astro-on-Vite versus direct Vite SPA result before this issue is closed.

Non-goals

• Treating Astro as the runtime that makes arbitrary frameworks compatible.
• Using server islands or an Astro production server in the initial local host.
• Loading the full authoring system for every shared-interface visitor.
• Replacing Tauri platform adapters or the independent workspace/build contract.
• Migrating before the spike proves the decision.

[robinbraemer]

Pushed verification update — 2026-08-10

The accepted implementation is now pushed. Astro owns the static document and activation boundary while Vite remains the build engine. A view-only load makes exactly four requests and loads no React/Effect workspace, Git, compiler, package, shell, Worker, or Wasm boundary. The activation coordinator is 3,159 B gzip / 6,559 B decoded; initial CSS is 1,094 B gzip; optional shell/compiler/package/Worker/Wasm boundaries remain independently on demand.

Production Chromium records 241 ms cold and 219 ms warm activation with 5 ms composer p95. The static output also passes the Tauri package and isolated packaged-host gate. Evidence: ADR 0003 and current verification.

[robinbraemer]

Final PR #38 evidence:

• Astro owns the static activation document; Vite remains the build and dev engine.
• View-only stays at four requests and does not fetch workspace, React, QuickJS, Rifty, worker, compiler, or Wasm tooling.
• Activation bootstrap: 3,219 B gzip / 6,695 B decoded; initial CSS: 1,094 B gzip.
• Shell, compiler, package, worker, and Wasm remain on-demand boundaries; optional diagnostics, sharing, provider, extension, Markdown, and web-project surfaces are deferred behind the workspace.
• Canonical hosted run https://github.com/akua-dev/flect/actions/runs/31383464208 passed.

Implementation is PR-ready and linked to #38.