[React][Roadmap] Pre-1.0 @fluojs/react phased delivery plan

[ayden94]

Problem Statement

fluo needs a React integration plan that preserves the existing HTTP router, DTO validation pipeline, runtime-neutral response seams, and Changesets-only release governance. The plan should prevent the implementation from drifting into a Next.js App Router clone or a second URL matcher.

Proposed Solution

Track @fluojs/react as a pre-1.0 roadmap with explicit target versions. Until a maintainer explicitly approves a 1.0 release, planned feature waves should progress as 0.1.0, 0.2.0, 0.3.0, etc.

Version Plan

• 0.1.0: Stable SSR MVP with @Router, @Path, ReactModule, DTO-bound page handlers, Web Streams streaming SSR, hydration asset options, lifecycle regression tests, docs, and changeset.
• 0.2.0: @fluojs/react/vite asset manifest and Vite-backed hydration example.
• 0.3.0: Client navigation runtime under @fluojs/react/client (Link, useRouter, URL hooks), plus an HTTP-first catch-all/wildcard route grammar RFC if needed. No React-only grammar divergence.
• 0.4.0: @fluojs/react/experimental/rsc and experimental Server Functions prototype.
• 0.5.0: Stable React application DX deepening through an application page renderer, direct JSX page returns, phase-aware SSR diagnostics, official SSR/Vite scaffolding, read-only page discovery/type tooling, native-form guidance, and semantics-first render-policy decisions. RSC graduation remains a separate evidence-gated path.
• 0.6.0: Developer-journey consolidation through a shorter zero-to-first-page path, an HTTP-owned content-negotiated HTML error/not-found representation seam, and a deterministic React typegen/testing development loop.

Actual package versions must still be produced only through Changesets and the canonical GitHub Actions release flow.

Accepted Design Decisions

• @fluojs/react owns React rendering integration, not URL matching.
• URL matching remains owned by @fluojs/http via @Controller/route metadata, HandlerDescriptor, createHandlerMapping, and Dispatcher.
• @Router() is a React lexical facade over HTTP controller metadata.
• @Path() is a React lexical facade over HTTP GET route metadata plus React render metadata.
• DTO binding and validation remain first-class for React page handlers: @RequestDto, @FromPath, @FromQuery, @FromHeader, @FromCookie, converters, validation, guards, interceptors, middleware, versioning, and request scopes.
• Related pages like /dashboard, /dashboard/:id, and /dashboard/:id/edit should be grouped in one router class when the route subtree is cohesive.
• Client navigation belongs under @fluojs/react/client; it must not replace server-side DTO validation or leak browser-only APIs into the runtime-neutral root export.
• RSC and Server Functions must start under @fluojs/react/experimental/rsc, not stable root.

Non-goals

• Do not clone Next.js App Router as the core model.
• Do not introduce a routes: [] React route table as the primary API.
• Do not bypass the existing HTTP dispatcher.
• Do not widen route grammar in the SSR MVP.
• Do not export browser-only navigation APIs, RSC, or Server Functions from stable root.
• Do not run local publish commands.

Phase Issues

0.1.0 stable SSR MVP

• [React 0.1.0][Phase 1-1] Scaffold @fluojs/react package contract #2490
• [React 0.1.0][Phase 1-2] Add Router and Path decorators over HTTP metadata #2491
• [React 0.1.0][Phase 1-3] Register React routers through ReactModule without a separate router #2492
• [React 0.1.0][Phase 1-4] Add Web Streams streaming SSR core #2493
• [React 0.1.0][Phase 1-5] Define hydration asset injection contract #2494
• [React 0.1.0][Phase 1-6] Cover HTTP lifecycle preservation for React page handlers #2495
• [React 0.1.0][Phase 1-7] Ship stable SSR docs, examples, and changeset #2496

0.2.0 Vite integration

• [React 0.2.0][Phase 2-1] Add @fluojs/react/vite asset manifest integration #2497
• [React 0.2.0][Phase 2-2] Add Vite-backed SSR hydration example #2498

0.3.0 client navigation and route grammar

• [React 0.3.0][Phase 3-1] Add client navigation runtime #2506
• [React 0.3.0][Phase 3-2] Evaluate HTTP-first catch-all route grammar #2499

0.4.0 experimental RSC/Server Functions

• [React 0.4.0][Phase 4-1] Prototype experimental RSC subpath #2500
• [React 0.4.0][Phase 4-2] Prototype experimental Server Functions #2501

0.5.0 stable application DX and RSC graduation policy

• [React 0.5.0][Phase 5-1] Define experimental/rsc to rsc graduation path #2502
• [React 0.5.0][Phase 5-2] Add application-level ReactPageRenderer / renderPage seam #2828
• [React 0.5.0][Phase 5-3] Allow direct ReactElement returns from @Path handlers and add phase-aware SSR diagnostics #2829
• [React 0.5.0][Phase 5-4] Add an official CLI starter for React SSR + Vite #2831
• [React 0.5.0][Phase 5-5] Add a read-only React page catalog with inspect and Studio visibility #2830
• [React 0.5.0][Phase 5-6] Add path-only typegen and typed href builders for React pages #2832
• [React 0.5.0][Phase 5-7] Document a native form HTTP mutation recipe with progressive enhancement #2833
• [React 0.5.0][Phase 5-8] Decide semantics-first render-policy decorators #2834
• [React 0.5.0][Phase 5-9] Document fluo's React model in familiar React-user concepts #2854
• [React 0.5.0][Phase 5-10] Improve typed React navigation DX from generated page routes #2855
• [React 0.5.0][Phase 5-11] Define the next bounded set of React page render policies #2856

0.6.0 developer journey and HTTP-owned document representation

• [React 0.6.0][Phase 6-1] Simplify zero-to-first-page developer experience #2888
• [React 0.6.0][Phase 6-2] Define an HTTP-owned HTML error and not-found representation seam #2889
• [React 0.6.0][Phase 6-3] Improve the typegen and testing development loop #2890
• [audit][area:http-runtime] Correct React metadata descriptor identity docs (P2) #2981
• [audit][area:http-runtime] Cover Server Function result-size limits (P2) #2982
• [audit][area:http-runtime] Cover rejected React client destinations (P2) #2983

Current Status

All 0.1.0 through 0.5.0 phase issues are complete. The completed 0.6.0 issues #2888, #2889, and #2890 established the developer-journey phase; open follow-ups #2981, #2982, and #2983 preserve its documentation and regression-test contracts without reopening or expanding the accepted scope of closed phases.

Acceptance Criteria

• All phase issues include Target version, dependencies, non-goals, acceptance criteria, test/docs/changeset expectations.
• 0.x.0 release cadence is reflected in every phase issue until explicit maintainer approval for 1.0.
• Stable root remains runtime-neutral and RSC-free.
• Docs and tests make route ownership and DTO preservation impossible to miss.

Roadmap Clarification: fluo HTTP-first React app DX

North Star

@fluojs/react should deliver a complete React application experience: streamed SSR, safe hydration, Vite-backed assets, progressive client navigation, current-route state hooks, navigation lifecycle state, and documentation/examples that make the app model easy to use. This is the target usability bar, not a commitment to copy another framework's internal route model.

TanStack Start-level usability, not feature parity

The roadmap aims for comparable app-building ergonomics, not TanStack Start/TanStack Router feature parity. @fluojs/react must not adopt a typed route tree, file-route discovery, route manifest as the primary application API, or TanStack-style loader/action ownership. fluo's type safety remains centered on standard decorators, HTTP route metadata, DTO binding, validation, converters, guards, interceptors, middleware, versioning, request scopes, and service-layer DI.

HTTP-first routing ownership

URL matching stays owned by @fluojs/http through @Controller/route metadata, HandlerDescriptor, createHandlerMapping, and Dispatcher. @Router(...) and @Path(...) are React lexical facades over those contracts. Client navigation is progressive enhancement over server-owned route matching; it must not become a second URL matcher.

Export surface boundaries

• Stable root @fluojs/react stays runtime-neutral and may not eagerly import browser APIs, Vite, React Server Components, Server Functions, or Node-only rendering APIs.
• Browser navigation APIs live under @fluojs/react/client.
• React asset/build integration lives under @fluojs/react/vite.
• RSC and Server Functions start under @fluojs/react/experimental/rsc.
• Future stable subpath graduation requires explicit release/docs/test evidence; it is not implied by this roadmap.

Angular-inspired lessons we adopt, without cloning Angular

Angular is a useful comparison because it treats routing, DI, SSR, hydration, request context, navigation lifecycle, and testing as one framework contract. fluo should adopt those lessons in fluo terms:

• rendering-mode compatibility should remain possible for SSR, CSR, and future prerendering, but not through an Angular-style ServerRoute[] primary API;
• hydration mismatch constraints must be explicit: server HTML and the first client render must match, and browser-only work belongs behind client-only boundaries;
• pre-hydration interaction behavior must be documented, either as ordinary anchor/form fallback or as a future tested event-replay contract;
• current route state should be available as a fluo HTTP route-match snapshot, not as an Angular ActivatedRoute clone;
• server/browser provider separation should use fluo modules and DI seams;
• SSR-to-hydration transfer data must be escaped, bounded where practical, and safe around auth, cookies, Set-Cookie, and private/no-store responses;
• navigation events/state should be minimal and app-useful rather than a clone of Angular's router event class taxonomy;
• every phase needs tests that lock the contract before implementation.

Patterns this roadmap rejects

• Next.js App Router clone
• TanStack Router typed route tree clone
• Angular Routes[] or ServerRoute[] clone as the primary routing API
• primary routes: [] React route table
• file-system routing as the source of truth
• client-side validation replacing @RequestDto/DTO validation
• browser-only APIs in the runtime-neutral root export

0.5.0 stable application DX deepening

Roadmap phase 0.5.0 now includes stable HTTP-first React authoring and tooling work alongside the already-completed RSC graduation policy definition in #2502. This phase label is a roadmap position, not a guarantee that the package will publish as version 0.5.0; actual package versions remain determined only by committed Changesets and the canonical GitHub Actions release flow.

The DX work is sequenced as follows:

• [React 0.5.0][Phase 5-2] Add application-level ReactPageRenderer / renderPage seam #2828 deepens ReactModule.forRoot(...) with one application-level ReactPageRenderer / renderPage seam while preserving ReactServerEntry and HTTP dispatch.
• [React 0.5.0][Phase 5-3] Allow direct ReactElement returns from @Path handlers and add phase-aware SSR diagnostics #2829 allows direct ReactElement returns from @Path(...) handlers and defines phase-aware SSR diagnostics without changing ordinary HTTP handler values.
• [React 0.5.0][Phase 5-4] Add an official CLI starter for React SSR + Vite #2831 turns the proven React SSR/Vite example wiring into an official CLI starter while keeping @fluojs/react/vite parse-only.
• [React 0.5.0][Phase 5-5] Add a read-only React page catalog with inspect and Studio visibility #2830 projects a read-only React page catalog from authoritative HTTP descriptors for inspect and Studio visibility; it never participates in matching.
• [React 0.5.0][Phase 5-6] Add path-only typegen and typed href builders for React pages #2832 builds path-only type generation and absolute href builders from that catalog without creating a client route tree.
• [React 0.5.0][Phase 5-7] Document a native form HTTP mutation recipe with progressive enhancement #2833 establishes native <form> + @Post + DTO + 303 redirect as the progressive-enhancement mutation baseline.
• [React 0.5.0][Phase 5-8] Decide semantics-first render-policy decorators #2834 decides whether semantics-first render policies such as PageLayout and SuspenseFallback should be added after renderer and error-phase semantics are stable.

The whole DX phase rejects file routing as the source of truth, a second matcher, URL-prefix layout ancestry, SPA document caches, route prefetch without an owned cache, compiled Server Actions, and Next.js-style segment semantics. URL matching, DTO binding, guards, interceptors, middleware, versioning, request scopes, and not-found ownership remain in @fluojs/http. RSC stabilization remains governed independently by #2502 and the repository graduation policy.

Closed phase clarification policy

Clarifications added after some phase issues are closed are governance guardrails for subsequent phases, documentation alignment, and future implementation interpretation. They do not retroactively expand the completed scope of closed phase issues or turn already-accepted work into incomplete work.

TDD and documentation rule for every phase

Each phase issue must describe the failing contract tests, negative tests for forbidden surfaces, package README/README.ko updates, governed docs updates when relevant, example coverage, and Changesets release intent before implementation is considered complete.