create-fluxstack 1.21.1 → 1.22.1

package/app/client/src/components/DemoPage.tsx

@@ -1,135 +1,136 @@
-import type { ReactNode } from 'react'
-import { Link, useLocation } from 'react-router'
-import { FaArrowLeft, FaBolt } from 'react-icons/fa'
-
-const demoNav = [
-  { to: '/counter', label: 'Counter' },
-  { to: '/form', label: 'Form' },
-
-  { to: '/room-chat', label: 'Room Chat' },
-  { to: '/auth', label: 'Auth' },
-  { to: '/ping-pong', label: 'Ping Pong' },
-]
-
-const demoMeta: Record<string, { title: string; description: string; note?: ReactNode }> = {
-  '/counter': {
-    title: 'Counters',
-    description: 'Compare estado local, estado isolado por sala e estado compartilhado em tempo real.',
-  },
-  '/form': {
-    title: 'Live Form',
-    description: 'Formulario com campos sincronizados pelo servidor, debounce e estado compartilhado pelo proxy Live.',
-    note: <>Este formulario usa <code className="text-theme">Live.use()</code> - cada campo sincroniza automaticamente com o servidor.</>,
-  },
-
-  '/shared-counter': {
-    title: 'Shared Counter',
-    description: 'Uma sala global sincroniza usuarios, eventos e estado entre abas abertas ao mesmo tempo.',
-    note: <>Contador compartilhado usando <code className="text-theme">LiveRoom</code> - abra em varias abas.</>,
-  },
-  '/room-chat': {
-    title: 'Room Chat',
-    description: 'Chat multi-sala com salas publicas, salas protegidas por senha e mensagens em tempo real.',
-    note: <>Chat com multiplas salas usando o sistema <code className="text-theme">$room</code>.</>,
-  },
-  '/auth': {
-    title: 'Live Auth',
-    description: 'Fluxo de autenticacao para Live Components com roles, permissoes e painel protegido.',
-    note: <>Sistema de autenticacao declarativo para Live Components com <code className="text-theme">$auth</code>.</>,
-  },
-  '/ping-pong': {
-    title: 'Ping Pong Binary',
-    description: 'Mede round-trip time de mensagens binarias no WebSocket usando codec msgpack.',
-    note: <>Latency demo com <code className="text-theme-secondary">msgpack</code> binary codec - mensagens binarias no WebSocket.</>,
-  },
-}
-
-interface DemoPageProps {
-  children: ReactNode
-  title?: string
-  description?: string
-  eyebrow?: string
-  note?: ReactNode
-}
-
-export function DemoPage({
-  children,
-  title,
-  description,
-  eyebrow = 'Live Demo',
-  note,
-}: DemoPageProps) {
-  const location = useLocation()
-  const meta = demoMeta[location.pathname]
-  const pageTitle = title ?? meta?.title ?? 'Live Component Demo'
-  const pageDescription = description ?? meta?.description ?? 'Explore uma capacidade do runtime Live em uma interface conectada ao servidor.'
-  const pageNote = meta?.note ?? note
-
-  return (
-    <div className="relative min-h-[calc(100vh-128px)] overflow-hidden px-4 py-8 sm:px-6 lg:px-8">
-      <div className="absolute inset-0 app-grid-bg opacity-45" />
-
-      <div className="relative z-10 mx-auto flex w-full max-w-7xl flex-col gap-6">
-        <div className="flex flex-col gap-4">
-          <Link
-            to="/"
-            className="inline-flex w-fit items-center gap-2 rounded-lg border border-white/10 bg-white/[0.03] px-3 py-2 text-sm text-gray-300 transition hover:border-white/20 hover:bg-white/[0.06] hover:text-white"
-          >
-            <FaArrowLeft className="h-3 w-3" />
-            Home
-          </Link>
-
-          <section className="rounded-lg border border-white/10 bg-[#07070b]/75 p-5 shadow-2xl shadow-black/20 backdrop-blur sm:p-6">
-            <div className="flex flex-col gap-5 lg:flex-row lg:items-end lg:justify-between">
-              <div className="max-w-3xl">
-                <div className="mb-4 inline-flex items-center gap-2 rounded-full border border-theme-active bg-theme-muted px-3 py-1 text-xs font-medium text-theme">
-                  <FaBolt className="h-3 w-3" />
-                  {eyebrow}
-                </div>
-                <h1 className="text-3xl font-semibold tracking-tight text-white sm:text-4xl">
-                  {pageTitle}
-                </h1>
-                <p className="mt-3 max-w-2xl text-sm leading-7 text-gray-400 sm:text-base">
-                  {pageDescription}
-                </p>
-              </div>
-
-              <div className="flex flex-wrap gap-2 lg:justify-end">
-                {demoNav.map(item => {
-                  const active = location.pathname === item.to
-                  return (
-                    <Link
-                      key={item.to}
-                      to={item.to}
-                      className={`rounded-lg border px-3 py-2 text-xs font-medium transition ${
-                        active
-                          ? 'border-white bg-white text-black'
-                          : 'border-white/10 bg-white/[0.025] text-gray-400 hover:border-white/20 hover:bg-white/[0.06] hover:text-white'
-                      }`}
-                    >
-                      {item.label}
-                    </Link>
-                  )
-                })}
-              </div>
-            </div>
-          </section>
-        </div>
-
-        <section className="rounded-lg border border-white/10 bg-black/20 p-3 shadow-2xl shadow-black/20 backdrop-blur sm:p-5">
-          <div className="mx-auto flex w-full max-w-6xl flex-col items-center">
-            {children}
-          </div>
-        </section>
-
-        {pageNote && (
-          <aside className="mx-auto w-full max-w-3xl rounded-lg border border-theme bg-theme-accent px-4 py-3 text-center">
-            <p className="text-xs leading-6 text-gray-400 sm:text-sm">
-              {pageNote}
-            </p>
-          </aside>
-        )}
-      </div>
-    </div>
-  )
-}
+'use client'
+import type { ReactNode } from 'react'
+import { Link, useLocation } from 'react-router'
+import { FaArrowLeft, FaBolt } from 'react-icons/fa'
+
+const demoNav = [
+  { to: '/counter', label: 'Counter' },
+  { to: '/form', label: 'Form' },
+
+  { to: '/room-chat', label: 'Room Chat' },
+  { to: '/auth', label: 'Auth' },
+  { to: '/ping-pong', label: 'Ping Pong' },
+]
+
+const demoMeta: Record<string, { title: string; description: string; note?: ReactNode }> = {
+  '/counter': {
+    title: 'Counters',
+    description: 'Compare estado local, estado isolado por sala e estado compartilhado em tempo real.',
+  },
+  '/form': {
+    title: 'Live Form',
+    description: 'Formulario com campos sincronizados pelo servidor, debounce e estado compartilhado pelo proxy Live.',
+    note: <>Este formulario usa <code className="text-theme">Live.use()</code> - cada campo sincroniza automaticamente com o servidor.</>,
+  },
+
+  '/shared-counter': {
+    title: 'Shared Counter',
+    description: 'Uma sala global sincroniza usuarios, eventos e estado entre abas abertas ao mesmo tempo.',
+    note: <>Contador compartilhado usando <code className="text-theme">LiveRoom</code> - abra em varias abas.</>,
+  },
+  '/room-chat': {
+    title: 'Room Chat',
+    description: 'Chat multi-sala com salas publicas, salas protegidas por senha e mensagens em tempo real.',
+    note: <>Chat com multiplas salas usando o sistema <code className="text-theme">$room</code>.</>,
+  },
+  '/auth': {
+    title: 'Live Auth',
+    description: 'Fluxo de autenticacao para Live Components com roles, permissoes e painel protegido.',
+    note: <>Sistema de autenticacao declarativo para Live Components com <code className="text-theme">$auth</code>.</>,
+  },
+  '/ping-pong': {
+    title: 'Ping Pong Binary',
+    description: 'Mede round-trip time de mensagens binarias no WebSocket usando codec msgpack.',
+    note: <>Latency demo com <code className="text-theme-secondary">msgpack</code> binary codec - mensagens binarias no WebSocket.</>,
+  },
+}
+
+interface DemoPageProps {
+  children: ReactNode
+  title?: string
+  description?: string
+  eyebrow?: string
+  note?: ReactNode
+}
+
+export function DemoPage({
+  children,
+  title,
+  description,
+  eyebrow = 'Live Demo',
+  note,
+}: DemoPageProps) {
+  const location = useLocation()
+  const meta = demoMeta[location.pathname]
+  const pageTitle = title ?? meta?.title ?? 'Live Component Demo'
+  const pageDescription = description ?? meta?.description ?? 'Explore uma capacidade do runtime Live em uma interface conectada ao servidor.'
+  const pageNote = meta?.note ?? note
+
+  return (
+    <div className="relative min-h-[calc(100vh-128px)] overflow-hidden px-4 py-8 sm:px-6 lg:px-8">
+      <div className="absolute inset-0 app-grid-bg opacity-45" />
+
+      <div className="relative z-10 mx-auto flex w-full max-w-7xl flex-col gap-6">
+        <div className="flex flex-col gap-4">
+          <Link
+            to="/"
+            className="inline-flex w-fit items-center gap-2 rounded-lg border border-white/10 bg-white/[0.03] px-3 py-2 text-sm text-gray-300 transition hover:border-white/20 hover:bg-white/[0.06] hover:text-white"
+          >
+            <FaArrowLeft className="h-3 w-3" />
+            Home
+          </Link>
+
+          <section className="rounded-lg border border-white/10 bg-[#07070b]/75 p-5 shadow-2xl shadow-black/20 backdrop-blur sm:p-6">
+            <div className="flex flex-col gap-5 lg:flex-row lg:items-end lg:justify-between">
+              <div className="max-w-3xl">
+                <div className="mb-4 inline-flex items-center gap-2 rounded-full border border-theme-active bg-theme-muted px-3 py-1 text-xs font-medium text-theme">
+                  <FaBolt className="h-3 w-3" />
+                  {eyebrow}
+                </div>
+                <h1 className="text-3xl font-semibold tracking-tight text-white sm:text-4xl">
+                  {pageTitle}
+                </h1>
+                <p className="mt-3 max-w-2xl text-sm leading-7 text-gray-400 sm:text-base">
+                  {pageDescription}
+                </p>
+              </div>
+
+              <div className="flex flex-wrap gap-2 lg:justify-end">
+                {demoNav.map(item => {
+                  const active = location.pathname === item.to
+                  return (
+                    <Link
+                      key={item.to}
+                      to={item.to}
+                      className={`rounded-lg border px-3 py-2 text-xs font-medium transition ${
+                        active
+                          ? 'border-white bg-white text-black'
+                          : 'border-white/10 bg-white/[0.025] text-gray-400 hover:border-white/20 hover:bg-white/[0.06] hover:text-white'
+                      }`}
+                    >
+                      {item.label}
+                    </Link>
+                  )
+                })}
+              </div>
+            </div>
+          </section>
+        </div>
+
+        <section className="rounded-lg border border-white/10 bg-black/20 p-3 shadow-2xl shadow-black/20 backdrop-blur sm:p-5">
+          <div className="mx-auto flex w-full max-w-6xl flex-col items-center">
+            {children}
+          </div>
+        </section>
+
+        {pageNote && (
+          <aside className="mx-auto w-full max-w-3xl rounded-lg border border-theme bg-theme-accent px-4 py-3 text-center">
+            <p className="text-xs leading-6 text-gray-400 sm:text-sm">
+              {pageNote}
+            </p>
+          </aside>
+        )}
+      </div>
+    </div>
+  )
+}

package/app/client/src/components/ErrorBoundary.tsx

@@ -1,4 +1,5 @@
-import { Component, type ReactNode, type ErrorInfo } from 'react'
+'use client'
+import { Component, type ReactNode, type ErrorInfo } from 'react'
 
 interface ErrorBoundaryProps {
   children: ReactNode

package/app/client/src/components/LiveErrorBoundary.tsx

@@ -1,4 +1,5 @@
-import type { ReactNode } from 'react'
+'use client'
+import type { ReactNode } from 'react'
 import { ErrorBoundary } from './ErrorBoundary'
 
 function LiveErrorFallback({ error, onReset }: { error: Error; onReset: () => void }) {

package/app/client/src/components/ThemePicker.tsx

@@ -1,3 +1,4 @@
+'use client'
 /**
  * ThemePicker — floating panel with interactive color wheel
  */

package/app/client/src/framework/ClientOnly.tsx

@@ -0,0 +1,14 @@
+'use client'
+// ClientOnly — adia a renderização dos filhos até DEPOIS da hidratação.
+// Os Live Components (@fluxstack/live-react) usam Live.use(), que não suporta
+// render no SSR (server.edge). Então no server/SSR mostramos um placeholder e
+// só montamos o Live no client após o mount. Isso evita o erro de SSR e mantém
+// o resto da página (server components) renderizando normalmente.
+import { useEffect, useState } from 'react'
+import type { ReactNode } from 'react'
+
+export function ClientOnly({ children, fallback = null }: { children: ReactNode; fallback?: ReactNode }) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  return <>{mounted ? children : fallback}</>
+}

package/app/client/src/framework/LivePage.tsx

@@ -0,0 +1,55 @@
+'use client'
+// LivePage — wrapper de página que usa Live Components.
+//
+// Esconde a cerimônia: cabeçalho (server-friendly) + LiveComponentsProvider +
+// ClientOnly. O dev só escreve <LivePage><MeuDemoLive/></LivePage> e os Live
+// Components funcionam (placeholder no SSR, conectam no client). O Provider
+// compartilha a conexão única via connectionPool (keep-alive no entry.browser).
+import type { ReactNode } from 'react'
+import { LiveComponentsProvider } from '@/core/client'
+import { ClientOnly } from './ClientOnly'
+import { ParamsProvider } from './params'
+import type { RouteParams } from './routes'
+
+function Loading() {
+  return (
+    <div className="flex w-full items-center justify-center rounded-lg border border-white/10 bg-white/[0.02] p-12 text-sm text-gray-500">
+      <span className="mr-2 inline-block h-3 w-3 animate-pulse rounded-full bg-theme" />
+      Conectando ao Live…
+    </div>
+  )
+}
+
+export function LivePage({
+  title,
+  description,
+  params = {},
+  children,
+}: {
+  title?: string
+  description?: string
+  /** params da rota — repasse o `params` que a página recebeu, p/ useParams() funcionar */
+  params?: RouteParams
+  children: ReactNode
+}) {
+  return (
+    <div className="relative min-h-[calc(100vh-57px)] px-4 py-10">
+      <div className="absolute inset-0 app-grid-bg opacity-70" />
+      <div className="relative z-10 mx-auto flex max-w-7xl flex-col gap-6">
+        {title && (
+          <div>
+            <h1 className="text-3xl font-semibold text-white">{title}</h1>
+            {description && <p className="mt-1 text-sm text-gray-500">{description}</p>}
+          </div>
+        )}
+        <ClientOnly fallback={<Loading />}>
+          <ParamsProvider params={params}>
+            <LiveComponentsProvider autoConnect reconnectInterval={1000} heartbeatInterval={30000}>
+              {children}
+            </LiveComponentsProvider>
+          </ParamsProvider>
+        </ClientOnly>
+      </div>
+    </div>
+  )
+}

package/app/client/src/framework/RscHomePage.tsx

@@ -0,0 +1,125 @@
+// HomePage como SERVER COMPONENT (RSC) — a página bonita original, portada.
+// Sem estado/interatividade → roda 100% no server, 0 JS no client.
+// Diferenças vs HomePage.tsx original:
+//  - <Link> (react-router) → <a> (navegação RSC usa anchor + fetch do payload)
+//  - apiStatus vem como prop do server (sem fetch client no shell)
+import FluxStack from '@client/src/assets/fluxstack.svg'
+import {
+  FaArrowRight,
+  FaBolt,
+  FaCodeBranch,
+  FaLayerGroup,
+  FaServer,
+  FaShieldAlt,
+  FaTerminal,
+} from 'react-icons/fa'
+
+export function RscHomePage() {
+  const features = [
+    { icon: FaBolt, title: 'Runtime rapido', copy: 'Bun no centro do fluxo de dev e build, com feedback curto para projetos full stack.' },
+    { icon: FaShieldAlt, title: 'Type-safe', copy: 'Contratos compartilhados entre Elysia, Eden Treaty e React sem duplicar modelos.' },
+    { icon: FaLayerGroup, title: 'Live Components', copy: 'Estado no servidor com UI reativa, salas em tempo real e componentes declarativos.' },
+  ]
+  const stackItems = ['Bun', 'Elysia', 'React', 'TypeScript']
+
+  return (
+    <div className="relative min-h-[calc(100vh-72px)] overflow-hidden px-4 py-10 sm:px-6 lg:px-8">
+      <div className="absolute inset-0 app-grid-bg opacity-70" />
+      <div className="absolute inset-x-0 top-0 h-px bg-gradient-to-r from-transparent via-white/25 to-transparent" />
+
+      <div className="relative z-10 mx-auto flex w-full max-w-7xl flex-col gap-10 lg:min-h-[calc(100vh-144px)] lg:justify-center">
+        <section className="grid items-center gap-8 lg:grid-cols-[1.04fr_0.96fr]">
+          <div className="max-w-3xl">
+            <div className="mb-6 inline-flex items-center gap-2 rounded-full border border-white/10 bg-white/[0.04] px-3 py-1.5 text-xs text-gray-300 shadow-[inset_0_1px_0_rgba(255,255,255,0.08)]">
+              <span className="h-1.5 w-1.5 rounded-full bg-emerald-300" />
+              <span className="rounded-full border border-emerald-400/25 bg-emerald-400/10 text-emerald-200 px-2 py-0.5">Server Rendered (RSC)</span>
+              <span className="hidden sm:inline">Full-stack starter for production apps</span>
+            </div>
+
+            <div className="mb-5 flex items-center gap-4">
+              <div className="relative flex h-16 w-16 items-center justify-center rounded-lg border border-white/10 bg-white/[0.04] shadow-2xl shadow-black/30">
+                <img src={FluxStack} alt="FluxStack" className="h-11 w-11 glow-theme" />
+              </div>
+              <div className="hidden h-px flex-1 bg-gradient-to-r from-white/20 to-transparent sm:block" />
+            </div>
+
+            <h1 className="max-w-4xl text-left text-5xl font-semibold tracking-tight text-white sm:text-6xl lg:text-7xl">
+              FluxStack
+              <span className="block bg-theme-gradient bg-clip-text text-transparent">TypeScript full stack.</span>
+            </h1>
+
+            <p className="mt-5 max-w-2xl text-left text-base leading-8 text-gray-400 sm:text-lg">
+              Um framework direto ao ponto para construir APIs Elysia, interfaces React,
+              componentes em tempo real e contratos type-safe em uma unica base.
+            </p>
+
+            <div className="mt-8 flex flex-col gap-3 sm:flex-row">
+              <a href="/counter" className="inline-flex h-11 items-center justify-center gap-2 rounded-lg bg-white px-5 text-sm font-semibold text-black transition hover:bg-gray-200">
+                Ver demos
+                <FaArrowRight className="h-3.5 w-3.5" />
+              </a>
+              <a href="/swagger" target="_blank" rel="noopener noreferrer" className="inline-flex h-11 items-center justify-center gap-2 rounded-lg border border-white/10 bg-white/[0.03] px-5 text-sm font-semibold text-white transition hover:border-white/20 hover:bg-white/[0.06]">
+                <FaServer className="h-3.5 w-3.5 text-theme" />
+                API docs
+              </a>
+            </div>
+
+            <div className="mt-8 flex flex-wrap gap-2">
+              {stackItems.map((item) => (
+                <span key={item} className="rounded-full border border-white/10 bg-black/20 px-3 py-1 text-xs font-medium text-gray-300">{item}</span>
+              ))}
+            </div>
+          </div>
+
+          <div className="relative">
+            <div className="rounded-lg border border-white/10 bg-[#050508]/80 shadow-2xl shadow-black/40 backdrop-blur">
+              <div className="flex items-center justify-between border-b border-white/10 px-4 py-3">
+                <div className="flex items-center gap-2">
+                  <span className="h-2.5 w-2.5 rounded-full bg-red-400/80" />
+                  <span className="h-2.5 w-2.5 rounded-full bg-amber-300/80" />
+                  <span className="h-2.5 w-2.5 rounded-full bg-emerald-300/80" />
+                </div>
+                <span className="font-mono text-xs text-gray-500">fluxstack.config.ts</span>
+              </div>
+              <div className="space-y-5 p-5 sm:p-6">
+                <div className="rounded-lg border border-white/10 bg-white/[0.03] p-4">
+                  <div className="mb-3 flex items-center gap-2 text-sm font-semibold text-white">
+                    <FaTerminal className="text-theme" />
+                    Ship from one command
+                  </div>
+                  <pre className="overflow-x-auto rounded-md bg-black/50 p-4 text-left text-xs leading-6 text-gray-300">
+                    <code>{`bunx create-fluxstack my-app\ncd my-app\nbun dev`}</code>
+                  </pre>
+                </div>
+                <div className="grid gap-3 sm:grid-cols-2">
+                  <div className="rounded-lg border border-white/10 bg-white/[0.03] p-4">
+                    <FaCodeBranch className="mb-4 text-theme-secondary" />
+                    <p className="text-sm font-semibold text-white">Typed routes</p>
+                    <p className="mt-1 text-xs leading-5 text-gray-500">Client e server compartilham o contrato.</p>
+                  </div>
+                  <div className="rounded-lg border border-white/10 bg-white/[0.03] p-4">
+                    <FaLayerGroup className="mb-4 text-theme" />
+                    <p className="text-sm font-semibold text-white">Live UI</p>
+                    <p className="mt-1 text-xs leading-5 text-gray-500">WebSocket, rooms e estado remoto.</p>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </section>
+
+        <section className="grid gap-3 sm:grid-cols-3">
+          {features.map(({ icon: Icon, title, copy }) => (
+            <article key={title} className="group rounded-lg border border-white/10 bg-white/[0.025] p-5 text-left transition hover:border-white/20 hover:bg-white/[0.045]">
+              <div className="mb-5 flex h-9 w-9 items-center justify-center rounded-lg border border-white/10 bg-black/30 text-theme transition group-hover:border-theme-active">
+                <Icon className="h-4 w-4" />
+              </div>
+              <h2 className="text-sm font-semibold text-white">{title}</h2>
+              <p className="mt-2 text-sm leading-6 text-gray-500">{copy}</p>
+            </article>
+          ))}
+        </section>
+      </div>
+    </div>
+  )
+}

package/app/client/src/framework/RscLink.tsx

@@ -0,0 +1,31 @@
+'use client'
+// Link client-side para navegação RSC sem reload. Intercepta o clique e usa
+// o navigate do RootClient (fetch do .rsc + transition). Cai pra <a> normal
+// em ctrl/cmd-click, target _blank, ou links externos.
+import type { ReactNode, MouseEvent } from 'react'
+import { navigate } from './navigation'
+
+export function RscLink({
+  href,
+  className,
+  children,
+  external,
+}: {
+  href: string
+  className?: string
+  children: ReactNode
+  external?: boolean
+}) {
+  function onClick(e: MouseEvent<HTMLAnchorElement>) {
+    if (external) return // deixa o browser tratar (ex: /swagger, target _blank)
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return
+    e.preventDefault()
+    navigate(href)
+  }
+
+  return (
+    <a href={href} className={className} onClick={onClick} {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}>
+      {children}
+    </a>
+  )
+}

package/app/client/src/framework/RscNav.tsx

@@ -0,0 +1,42 @@
+// Navbar SERVER COMPONENT — gerada automaticamente a partir das rotas descobertas
+// (file-based). Adicionar uma página em pages/ a faz aparecer aqui sozinha
+// (a menos que a página exporte `nav = false`). Links via RscLink (SPA sem reload).
+import FluxStackLogo from '@client/src/assets/fluxstack.svg'
+import { RscLink } from './RscLink'
+import { routes } from './routes'
+
+export function RscNav({ active }: { active: string }) {
+  const navItems = routes.filter((r) => r.inNav)
+
+  return (
+    <header className="sticky top-0 z-50 border-b border-white/10 bg-black/60 backdrop-blur">
+      <div className="mx-auto flex max-w-7xl items-center gap-6 px-4 py-3">
+        <RscLink href="/" className="flex items-center gap-2">
+          <img src={FluxStackLogo} alt="FluxStack" className="h-6 w-6" />
+          <span className="font-semibold text-white">FluxStack</span>
+        </RscLink>
+        <nav className="flex flex-wrap items-center gap-1">
+          {navItems.map((item) => {
+            const isActive = item.path === active
+            return (
+              <RscLink
+                key={item.path}
+                href={item.path}
+                className={`rounded-lg px-3 py-1.5 text-sm transition ${
+                  isActive
+                    ? 'bg-white/10 text-white'
+                    : 'text-gray-400 hover:bg-white/[0.05] hover:text-white'
+                }`}
+              >
+                {item.navLabel}
+              </RscLink>
+            )
+          })}
+        </nav>
+        <RscLink href="/swagger" external className="ml-auto text-sm text-gray-400 hover:text-white">
+          API docs
+        </RscLink>
+      </div>
+    </header>
+  )
+}

package/app/client/src/framework/RscRoot.tsx

@@ -0,0 +1,54 @@
+// SERVER COMPONENTS do site FluxStack via RSC — agora com roteamento FILE-BASED.
+//
+// O dev NÃO edita este arquivo para adicionar páginas: basta criar um arquivo em
+// app/client/src/pages/ (ver framework/routes.ts). Aqui só montamos a casca
+// (navbar + a página que casa com o pathname) a partir do mapa descoberto.
+import '../index.css' // Tailwind + temas
+import { RscNav } from './RscNav'
+import { routes, matchRoute } from './routes'
+
+function NotFound({ pathname }: { pathname: string }) {
+  return (
+    <div className="flex min-h-[calc(100vh-57px)] flex-col items-center justify-center gap-4 text-center">
+      <h1 className="text-6xl font-black text-white">404</h1>
+      <p className="text-gray-400">A rota <code className="text-theme">{pathname}</code> não existe.</p>
+      <a href="/" className="rounded-lg bg-white px-5 py-2 text-sm font-semibold text-black">Voltar ao início</a>
+    </div>
+  )
+}
+
+/** Conteúdo da rota (nav + página). É o que as navegações client buscam (.rsc). */
+export function RscPage({ pathname = '/' }: { pathname?: string }) {
+  const match = matchRoute(pathname)
+  return (
+    <>
+      <RscNav active={pathname} />
+      {match
+        ? <match.route.Component params={match.params} />
+        : <NotFound pathname={pathname} />}
+    </>
+  )
+}
+
+/** Documento completo. Controle client (navegação + keep-alive WS) vive no
+ *  entry.browser; o body renderiza o RscPage direto.
+ *  csrfToken: injetado pelo server p/ o client não precisar fazer fetch('/api/__csrf'). */
+export function RscDocument({ pathname = '/', csrfToken }: { pathname?: string; csrfToken?: string }) {
+  return (
+    <html lang="pt-BR">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        {csrfToken && <meta name="csrf-token" content={csrfToken} />}
+        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+        <title>FluxStack</title>
+      </head>
+      <body>
+        <RscPage pathname={pathname} />
+      </body>
+    </html>
+  )
+}
+
+// re-export para conveniência
+export { routes }