create-fluxstack 1.21.1 → 1.22.1

package/app/client/src/live/SharedCounterDemo.tsx

@@ -1,3 +1,4 @@
+'use client'
 // SharedCounterDemo - Contador compartilhado entre todas as abas
 //
 // Abra em varias abas - todos veem o mesmo valor!
@@ -26,7 +27,7 @@ export function SharedCounterDemo() {
     initialState: { ...LiveSharedCounter.defaultState, username }
   })
 
-  // Client-side room events — floating animation
+  // Client-side room events — floating animation
   const [floats, setFloats] = useState<FloatingEvent[]>([])
   const floatIdRef = useRef(0)
 

package/app/client/src/pages/ApiTestPage.tsx

@@ -1,3 +1,4 @@
+'use client'
 import type { ReactNode } from 'react'
 import { BackButton } from '../components/BackButton'
 

package/app/client/src/pages/auth.tsx

@@ -0,0 +1,13 @@
+// Página /auth (file-based). Demo Live — React normal.
+import { LivePage } from '../framework/LivePage'
+import { AuthDemo } from '../live/AuthDemo'
+
+export const title = 'Auth'
+
+export default function AuthPage() {
+  return (
+    <LivePage title="Auth" description="Autenticação declarativa para Live Components com $auth.">
+      <AuthDemo />
+    </LivePage>
+  )
+}

package/app/client/src/pages/blog/[slug].tsx

@@ -0,0 +1,23 @@
+// Rota DINÂMICA /blog/:slug (file-based: pages/blog/[slug].tsx).
+// Server component (0 JS) — recebe os params como PROP. Funciona no server.
+import type { PageProps } from '../../framework/routes'
+
+export const title = 'Blog Post'
+
+export default function BlogPost({ params }: PageProps) {
+  const slug = params.slug as string
+  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 max-w-3xl">
+        <a href="/blog" className="text-sm text-gray-400 hover:text-white">← Blog</a>
+        <h1 className="mt-4 text-4xl font-semibold text-white">Post: {slug}</h1>
+        <p className="mt-4 text-gray-400">
+          Rota dinâmica renderizada no <strong>server</strong> (0 JS). O slug
+          <code className="text-theme"> {slug} </code> veio de <code className="text-theme">params</code>,
+          extraído da URL pelo roteador file-based — arquivo <code className="text-theme">pages/blog/[slug].tsx</code>.
+        </p>
+      </div>
+    </div>
+  )
+}

package/app/client/src/pages/counter.tsx

@@ -0,0 +1,15 @@
+// Página /counter (file-based). Demo Live — React normal.
+// O CounterDemo usa Live.use(); no server vira placeholder (guarda SSR),
+// no client monta e conecta. O LivePage cuida do Provider/ClientOnly.
+import { LivePage } from '../framework/LivePage'
+import { CounterDemo } from '../live/CounterDemo'
+
+export const title = 'Counters'
+
+export default function CounterPage() {
+  return (
+    <LivePage title="Counters" description="Estado local, sala isolada e sala compartilhada em tempo real.">
+      <CounterDemo />
+    </LivePage>
+  )
+}

package/app/client/src/pages/form.tsx

@@ -0,0 +1,13 @@
+// Página /form (file-based). Demo Live — React normal.
+import { LivePage } from '../framework/LivePage'
+import { FormDemo } from '../live/FormDemo'
+
+export const title = 'Form'
+
+export default function FormPage() {
+  return (
+    <LivePage title="Live Form" description="Formulário com campos sincronizados pelo servidor via proxy Live.">
+      <FormDemo />
+    </LivePage>
+  )
+}

package/app/client/src/pages/index.tsx

@@ -0,0 +1,9 @@
+// Página HOME — rota / (file-based: app/client/src/pages/index.tsx)
+// Componente React normal. Server component (sem Live) → 0 JS no client.
+import { RscHomePage } from '../framework/RscHomePage'
+
+export const title = 'Home'
+
+export default function HomePage() {
+  return <RscHomePage />
+}

package/app/client/src/pages/ping-pong.tsx

@@ -0,0 +1,13 @@
+// Página /ping-pong (file-based). Demo Live — React normal.
+import { LivePage } from '../framework/LivePage'
+import { PingPongDemo } from '../live/PingPongDemo'
+
+export const title = 'Ping-Pong'
+
+export default function PingPongPage() {
+  return (
+    <LivePage title="Ping-Pong" description="Latency demo com codec binário msgpack no WebSocket.">
+      <PingPongDemo />
+    </LivePage>
+  )
+}

package/app/client/src/pages/room-chat.tsx

@@ -0,0 +1,13 @@
+// Página /room-chat (file-based). Demo Live — React normal.
+import { LivePage } from '../framework/LivePage'
+import { RoomChatDemo } from '../live/RoomChatDemo'
+
+export const title = 'Chat'
+
+export default function RoomChatPage() {
+  return (
+    <LivePage title="Room Chat" description="Chat multi-sala usando o sistema $room.">
+      <RoomChatDemo />
+    </LivePage>
+  )
+}

package/app/client/src/pages/shared-counter.tsx

@@ -0,0 +1,13 @@
+// Página /shared-counter (file-based). Demo Live — React normal.
+import { LivePage } from '../framework/LivePage'
+import { SharedCounterDemo } from '../live/SharedCounterDemo'
+
+export const title = 'Shared'
+
+export default function SharedCounterPage() {
+  return (
+    <LivePage title="Shared Counter" description="Sala global sincroniza usuários e estado entre abas.">
+      <SharedCounterDemo />
+    </LivePage>
+  )
+}

package/app/client/src/pages/sobre.tsx

@@ -0,0 +1,19 @@
+// Página /sobre — PROVA do file-based routing. Só criar este arquivo já cria a
+// rota /sobre e o link na navbar. React normal, server component (0 JS).
+export const title = 'Sobre'
+
+export default function SobrePage() {
+  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 max-w-3xl">
+        <h1 className="text-4xl font-semibold text-white">Sobre</h1>
+        <p className="mt-4 text-gray-400">
+          Esta página foi criada só adicionando <code className="text-theme">app/client/src/pages/sobre.tsx</code>.
+          Sem editar router, sem registrar rota, sem tocar em nada. É React normal — e roda
+          como Server Component (zero JS no client).
+        </p>
+      </div>
+    </div>
+  )
+}

package/app/server/index.ts

@@ -12,6 +12,7 @@
 
 import { FluxStackFramework } from "@core/server"
 import { vitePlugin } from "@core/plugins/built-in/vite"
+import { rscPlugin } from "@core/plugins/built-in/rsc"
 import { swaggerPlugin } from "@core/plugins/built-in/swagger"
 import { liveComponentsPlugin, registerAuthProvider } from "@core/server/live"
 import { appInstance } from "@server/app"
@@ -42,8 +43,11 @@ const framework = new FluxStackFramework()
   .use(liveComponentsPlugin)
   .use(csrfProtectionPlugin)
 
-// Vite apenas em full-stack
+// Vite + RSC apenas em full-stack. O rscPlugin (priority 860) intercepta rotas
+// de página antes do vite (800); só age se RSC_ENABLED=true. RSC é o modo SSR
+// oficial (o "Caminho A"/AppShell foi descontinuado — ver .ai-notes).
 if (appConfig.mode !== 'backend-only') {
+  framework.use(rscPlugin)
   framework.use(vitePlugin)
 }
 

package/app/server/live/rooms/index.ts

@@ -0,0 +1,14 @@
+// Registro ESTÁTICO das LiveRoom classes — usado no build de produção.
+//
+// Em dev, as rooms são auto-descobertas varrendo este diretório (import dinâmico).
+// Em PROD isso quebraria (import do disco carrega uma instância separada do
+// @fluxstack/live → context null). Aqui declaramos as rooms estaticamente para
+// entrarem no bundle e serem registradas no LiveServer({ rooms }).
+//
+// Ao adicionar uma room nova em rooms/, inclua-a aqui também (ou rode o gerador).
+import { ChatRoom } from './ChatRoom'
+import { CounterRoom } from './CounterRoom'
+import { DirectoryRoom } from './DirectoryRoom'
+import { PingRoom } from './PingRoom'
+
+export const liveRoomClasses = [ChatRoom, CounterRoom, DirectoryRoom, PingRoom]

package/config/system/plugins.config.ts

@@ -75,8 +75,18 @@ export const pluginsConfig = defineConfig({
   viteEnabled: config.boolean('VITE_PLUGIN_ENABLED', true),
   viteExcludePaths: config.array('VITE_EXCLUDE_PATHS', [
     '/api',
-    '/swagger'
-  ])
+    '/swagger',
+    '/ssr-demo',
+    '/ssr'
+  ]),
+
+  // SSR (server-side rendering das rotas de página). Off por padrão: ligar
+  // troca o SPA vazio do `/` por HTML pré-renderizado + hydration.
+  // RSC (React Server Components) — modo de renderização PADRÃO do FluxStack.
+  // Server components (0 JS) + client islands (Live Components) servidos pelo
+  // proxy interno. Para usar SPA puro, defina RSC_ENABLED=false no .env.
+  // Requer o rsc() no vite.config (também lê RSC_ENABLED). Ver core/plugins/built-in/rsc.
+  rscEnabled: config.boolean('RSC_ENABLED', true)
 })
 
 export type PluginsConfig = typeof pluginsConfig

package/core/cli/commands/dev.ts

@@ -70,7 +70,15 @@ export const devCommand: CLICommand = {
 
     buildLogger.info(`⚡ Starting ${mode} development server...`)
 
-    const devProcess = spawn("bun", ["--watch", entryPoint], {
+    // SSR: o loader de asset DEVE ser preloaded (antes do grafo de imports),
+    // senão imports de .svg no AppShell resolvem para caminho de arquivo (Bun)
+    // em vez da URL do Vite — causando hydration mismatch. Só em backend que
+    // serve frontend (não frontend-only) e quando SSR está habilitado.
+    const ssrPreload = !frontendOnly && process.env.SSR_ENABLED === 'true'
+      ? ['--preload', './core/plugins/built-in/ssr/bun-asset-loader.ts']
+      : []
+
+    const devProcess = spawn("bun", ["--watch", ...ssrPreload, entryPoint], {
       stdio: "inherit",
       cwd: process.cwd(),
       env: {

package/core/plugins/built-in/rsc/index.ts

@@ -0,0 +1,156 @@
+/**
+ * FluxStack RSC Plugin
+ *
+ * Serve React Server Components pelo proxy interno do FluxStack (Elysia), em vez
+ * do middleware próprio do @vitejs/plugin-rsc. Prioridade 860 > ssr (850) >
+ * vite (800): intercepta rotas de página antes deles. Só age se RSC_ENABLED=true.
+ *
+ * DEV: chama o handler do ambiente Vite `rsc` via runner (Vite dev server).
+ * PROD: importa o handler RSC BUILDADO (app/client/dist/rsc/index.js, default) e
+ *   serve os assets buildados (app/client/dist/client/assets). Sem Vite em prod.
+ *
+ * Em erro NÃO trata (fallback pro Vite/SPA). Requer o Vite criado com
+ * rsc({serverHandler:false}) — ver vite.config.ts (condicionado a RSC_ENABLED).
+ */
+
+import type { FluxStack, PluginContext, RequestContext } from '@core/plugins/types'
+import { FLUXSTACK_VERSION } from '@core/utils/version'
+import { isDevelopment } from '@core/utils/helpers'
+import { clientConfig, pluginsConfig } from '@config'
+import { isRunnableDevEnvironment } from 'vite'
+import { join } from 'path'
+import { existsSync } from 'fs'
+
+type Plugin = FluxStack.Plugin
+type RscHandler = (request: Request) => Promise<Response>
+
+const PLUGIN_PRIORITY = 860 // > ssr (850) > vite (800)
+const IS_DEV = isDevelopment()
+
+/** id do entry rsc no runner (dev) — relativo ao root app/client */
+const RSC_ENTRY_ID = '/src/framework/entry.rsc.tsx'
+/** caminho do handler RSC buildado (prod) e dos assets do client */
+const PROD_RSC_HANDLER = join(process.cwd(), 'app', 'client', 'dist', 'rsc', 'index.js')
+const PROD_CLIENT_DIR = join(process.cwd(), 'app', 'client', 'dist', 'client')
+
+const ASSET_EXT = /\.(js|mjs|ts|tsx|jsx|css|map|json|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|eot|wasm|txt|xml|webmanifest)$/i
+const PASSTHROUGH_PREFIXES = ['/@', '/src/', '/node_modules/', '/api', '/swagger', '/__plugins']
+
+function isPageRoute(path: string): boolean {
+  if (ASSET_EXT.test(path)) return false
+  return !PASSTHROUGH_PREFIXES.some((p) => path === p || path.startsWith(p))
+}
+
+/** Vite dev server (dev) — capturado do vitePlugin. */
+let viteServer: { environments: Record<string, unknown> } | null = null
+/** Handler RSC buildado (prod) — importado uma vez e cacheado. */
+let prodHandler: RscHandler | null = null
+
+/** Normaliza a URL da request para absoluta (handler RSC precisa de URL completa). */
+function absoluteUrl(ctx: RequestContext): string {
+  try {
+    return new URL(ctx.request.url).href
+  } catch {
+    const host = ctx.request.headers.get('host') || `${clientConfig.vite.host}:3000`
+    const proto = ctx.request.headers.get('x-forwarded-proto') || 'http'
+    const q = ctx.request.url.indexOf('?')
+    const search = q === -1 ? '' : ctx.request.url.slice(q)
+    return `${proto}://${host}${ctx.path}${search}`
+  }
+}
+
+/** Resolve o handler RSC (dev via runner, prod via import do build). */
+async function getHandler(): Promise<RscHandler | null> {
+  if (IS_DEV) {
+    if (!viteServer) return null
+    const rscEnv = viteServer.environments.rsc
+    if (!rscEnv || !isRunnableDevEnvironment(rscEnv as never)) return null
+    const mod = await (rscEnv as { runner: { import: (id: string) => Promise<{ default: RscHandler }> } })
+      .runner.import(RSC_ENTRY_ID)
+    return mod.default
+  }
+  // prod: importa o handler buildado uma vez
+  if (!prodHandler) {
+    if (!existsSync(PROD_RSC_HANDLER)) return null
+    const mod = await import(/* @vite-ignore */ PROD_RSC_HANDLER) as { default: RscHandler }
+    prodHandler = mod.default
+  }
+  return prodHandler
+}
+
+export const rscPlugin: Plugin = {
+  name: 'rsc',
+  version: FLUXSTACK_VERSION,
+  description: 'React Server Components served through the FluxStack proxy',
+  author: 'FluxStack Team',
+  priority: PLUGIN_PRIORITY,
+  category: 'rendering',
+  tags: ['rsc', 'react', 'server-components'],
+  dependencies: [],
+
+  setup: async (context: PluginContext) => {
+    if (!(pluginsConfig as Record<string, unknown>).rscEnabled) {
+      context.logger.debug('RSC plugin disabled (set RSC_ENABLED=true)')
+      return
+    }
+    if (!IS_DEV && !existsSync(PROD_RSC_HANDLER)) {
+      context.logger.warn(`RSC: handler buildado não encontrado (${PROD_RSC_HANDLER}). Rode o build com RSC_ENABLED=true.`)
+      return
+    }
+    context.logger.debug(`RSC plugin active (priority ${PLUGIN_PRIORITY}, ${IS_DEV ? 'dev' : 'prod'})`)
+  },
+
+  // DEV: captura o Vite dev server (do vitePlugin) para o runner.
+  onServerStart: async (context: PluginContext) => {
+    if (!(pluginsConfig as Record<string, unknown>).rscEnabled || !IS_DEV) return
+    const cfg = (context as PluginContext & { viteConfig?: { server?: unknown } }).viteConfig
+    if (cfg?.server) {
+      viteServer = cfg.server as { environments: Record<string, unknown> }
+      context.logger.debug('RSC: Vite dev server capturado para o runner')
+    }
+  },
+
+  onBeforeRoute: async (ctx: RequestContext) => {
+    if (!(pluginsConfig as Record<string, unknown>).rscEnabled) return
+    if (ctx.method !== 'GET') return
+
+    // PROD: servir assets buildados (/assets/*, /favicon.svg) do dist/client.
+    if (!IS_DEV && !isPageRoute(ctx.path)) {
+      const assetPath = join(PROD_CLIENT_DIR, ctx.path)
+      if (ctx.path !== '/' && existsSync(assetPath)) {
+        ctx.handled = true
+        ctx.response = new Response(Bun.file(assetPath))
+      }
+      return
+    }
+    if (!isPageRoute(ctx.path)) return // dev: assets vão pro Vite
+
+    try {
+      const handler = await getHandler()
+      if (!handler) return // sem handler → fallback
+
+      // Cold-start (dev): a 1ª render pode suspender enquanto o grafo client
+      // carrega; um retry cobre. Em prod o handler já está pronto (1 tentativa).
+      const attempts = IS_DEV ? 2 : 1
+      let response: Response | null = null
+      for (let i = 0; i < attempts; i++) {
+        try {
+          const request = new Request(absoluteUrl(ctx), { method: ctx.method, headers: ctx.request.headers })
+          response = await handler(request)
+          break
+        } catch (e) {
+          if (i === attempts - 1) throw e
+        }
+      }
+      if (response) {
+        ctx.handled = true
+        ctx.response = response
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      console.error(`[RSC] render failed for ${ctx.path}, falling back: ${msg}`)
+    }
+  },
+}
+
+export default rscPlugin

package/core/plugins/built-in/ssr/bun-asset-loader.ts

@@ -0,0 +1,46 @@
+/**
+ * Bun asset loader para SSR — alinha imports de asset com o Vite.
+ *
+ * Problema: no client, o Vite resolve `import logo from '...x.svg'` para a URL
+ * `/src/assets/x.svg`. No server, o Bun resolve o MESMO import para o caminho
+ * de arquivo absoluto (C:\...\x.svg). Strings diferentes no atributo src/href
+ * → hydration mismatch (o React descarta o HTML do server e re-renderiza tudo).
+ *
+ * Solução: registrar um plugin no Bun que, ao carregar um asset, exporta a
+ * MESMA URL que o Vite geraria — relativa ao root do client (app/client).
+ * Em dev essa URL é servida pelo Vite; em prod, pelos assets buildados.
+ *
+ * Registrar via bunfig.toml [run].preload ANTES de qualquer import do app.
+ */
+
+import { plugin } from 'bun'
+import { sep } from 'path'
+
+/** Root do client onde o Vite baseia as URLs (app/client) */
+const CLIENT_ROOT = 'app' + sep + 'client' + sep
+
+/** Extensões que o Vite trata como asset-URL (não código) */
+const ASSET_RE = /\.(svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|eot|mp4|webm|mp3|wav)$/i
+
+plugin({
+  name: 'ssr-asset-url',
+  setup(build) {
+    build.onLoad({ filter: ASSET_RE }, (args) => {
+      // args.path é absoluto. Converter para a URL que o Vite usa:
+      // .../app/client/src/assets/x.svg  ->  /src/assets/x.svg
+      const idx = args.path.replace(/\//g, sep).indexOf(CLIENT_ROOT)
+      let url: string
+      if (idx !== -1) {
+        const rel = args.path.slice(idx + CLIENT_ROOT.length).replaceAll(sep, '/')
+        url = '/' + rel
+      } else {
+        // fallback: usa o basename
+        url = '/' + args.path.split(/[\\/]/).pop()
+      }
+      return {
+        exports: { default: url },
+        loader: 'object',
+      }
+    })
+  },
+})

package/core/plugins/built-in/ssr/index.ts

@@ -0,0 +1,143 @@
+/**
+ * FluxStack SSR Plugin
+ *
+ * Renderiza o HTML do app no servidor (renderToString) para rotas de PÁGINA,
+ * substituindo o `<div id="root"></div>` vazio do SPA por markup pronto.
+ * Os assets (JS/CSS/imagens, /@vite, /src/*) continuam servidos pelo Vite (dev)
+ * ou pelo static fallback (prod) — o SSR só intercepta navegação de página.
+ *
+ * Ordem: prioridade 850 > vite (800), então o onBeforeRoute do SSR roda ANTES
+ * do proxy do Vite. Se o SSR tratar a request (handled=true), o Vite não vê.
+ *
+ * O renderer do app é injetado via registry (registerSsrRenderer) — o core não
+ * conhece o React do app. Ver ./registry.ts.
+ *
+ * LIMITAÇÃO ATUAL (PoC): pipeline de hydration montado para DEV (Vite :5173).
+ * Produção (sem Vite dev) precisa apontar para os assets buildados — TODO abaixo.
+ */
+
+import type { FluxStack, PluginContext, RequestContext } from '@core/plugins/types'
+import { FLUXSTACK_VERSION } from '@core/utils/version'
+import { isDevelopment } from '@core/utils/helpers'
+import { clientConfig, pluginsConfig } from '@config'
+import { getSsrRenderer } from './registry'
+
+type Plugin = FluxStack.Plugin
+
+const PLUGIN_PRIORITY = 850 // > vite (800): intercepta páginas antes do proxy Vite
+const IS_DEV = isDevelopment()
+
+/** Extensões de asset — nunca devem ser tratadas como página */
+const ASSET_EXT = /\.(js|mjs|ts|tsx|jsx|css|map|json|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|eot|wasm|txt|xml|webmanifest)$/i
+
+/** Prefixos internos (Vite/API/dev) que NUNCA são páginas — passam direto */
+const PASSTHROUGH_PREFIXES = ['/@', '/src/', '/node_modules/', '/api', '/swagger', '/__plugins']
+
+/** Decide se um path é uma rota de PÁGINA (candidata a SSR) */
+function isPageRoute(path: string): boolean {
+  if (ASSET_EXT.test(path)) return false
+  return !PASSTHROUGH_PREFIXES.some((p) => path === p || path.startsWith(p))
+}
+
+/** Monta o documento HTML completo com o markup SSR + pipeline de hydration */
+function buildDocument(opts: {
+  appHtml: string
+  bootstrapData?: Record<string, unknown>
+  headTags?: string
+}): string {
+  const { appHtml, bootstrapData, headTags = '' } = opts
+
+  const viteHost = (clientConfig.vite.host as string) || 'localhost'
+  const vitePort = (clientConfig.vite.port as number) || 5173
+  const viteBase = `http://${viteHost}:${vitePort}`
+  const entry = (pluginsConfig as Record<string, unknown>).ssrClientEntry as string | undefined
+    ?? '/src/entry-ssr.tsx'
+
+  const dataScript = bootstrapData
+    ? `<script>window.__SSR_DATA__ = ${JSON.stringify(bootstrapData).replace(/</g, '\\u003c')};</script>`
+    : ''
+
+  // DEV: pipeline do Vite (react-refresh preamble + client + entry TSX)
+  const devScripts = IS_DEV
+    ? `<script type="module">
+      import RefreshRuntime from "${viteBase}/@react-refresh"
+      RefreshRuntime.injectIntoGlobalHook(window)
+      window.$RefreshReg$ = () => {}
+      window.$RefreshSig$ = () => (type) => type
+      window.__vite_plugin_react_preamble_installed__ = true
+    </script>
+    <script type="module" src="${viteBase}/@vite/client"></script>
+    <script type="module" src="${viteBase}${entry}"></script>`
+    // PROD: TODO — apontar para o entry buildado (ler do manifest do Vite).
+    // Por ora, sem script em prod (HTML estático apenas, sem interatividade).
+    : `<!-- TODO(SSR prod): injetar /assets/entry-ssr.[hash].js do build manifest -->`
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>FluxStack</title>
+    ${headTags}
+    ${IS_DEV ? devScripts : ''}
+  </head>
+  <body>
+    <div id="root">${appHtml}</div>
+    ${dataScript}
+    ${IS_DEV ? '' : devScripts}
+  </body>
+</html>`
+}
+
+export const ssrPlugin: Plugin = {
+  name: 'ssr',
+  version: FLUXSTACK_VERSION,
+  description: 'Server-side rendering of the React app for page routes',
+  author: 'FluxStack Team',
+  priority: PLUGIN_PRIORITY,
+  category: 'rendering',
+  tags: ['ssr', 'react', 'hydration'],
+  dependencies: [],
+
+  setup: async (context: PluginContext) => {
+    const enabled = (pluginsConfig as Record<string, unknown>).ssrEnabled
+    if (!enabled) {
+      context.logger.debug('SSR plugin disabled (set SSR_ENABLED=true)')
+      return
+    }
+    context.logger.debug(`SSR plugin active (priority ${PLUGIN_PRIORITY})`)
+  },
+
+  onBeforeRoute: async (ctx: RequestContext) => {
+    if (!(pluginsConfig as Record<string, unknown>).ssrEnabled) return
+    if (ctx.method !== 'GET') return
+    if (!isPageRoute(ctx.path)) return
+
+    const renderer = getSsrRenderer()
+    if (!renderer) return // app não registrou renderer → deixa o SPA fallback agir
+
+    try {
+      const result = await renderer({ url: ctx.path, headers: ctx.headers })
+      const html = buildDocument({
+        appHtml: result.html,
+        bootstrapData: result.bootstrapData,
+        headTags: result.headTags,
+      })
+      ctx.handled = true
+      ctx.response = new Response(html, {
+        status: result.status ?? 200,
+        headers: { 'Content-Type': 'text/html; charset=utf-8' },
+      })
+    } catch (err) {
+      // SSR falhou → NÃO trata (handled fica false), deixa o Vite/SPA servir.
+      // Falhar para o SPA é melhor que mostrar 500: o client ainda renderiza.
+      const msg = err instanceof Error ? err.message : String(err)
+      ;(ctx as unknown as { logger?: { error: (m: string) => void } }).logger?.error?.(
+        `SSR render failed for ${ctx.path}, falling back to SPA: ${msg}`
+      )
+    }
+  },
+}
+
+export default ssrPlugin

package/core/plugins/built-in/ssr/registry.ts

@@ -0,0 +1,38 @@
+/**
+ * FluxStack SSR — Renderer Registry
+ *
+ * Inversão de dependência: o CORE (framework) não conhece o App do usuário.
+ * O app registra sua função de render (que importa o AppShell client) aqui,
+ * e o plugin SSR a consome. Assim o core fica agnóstico ao React do app.
+ */
+
+export interface SsrRenderInput {
+  /** Caminho da rota a renderizar (ex: '/', '/counter') */
+  url: string
+  /** Headers da request original (útil para cookies/auth no futuro) */
+  headers: Record<string, string>
+}
+
+export interface SsrRenderOutput {
+  /** HTML do corpo do app (vai dentro de <div id="root">) */
+  html: string
+  /** Status HTTP (default 200; use 404 para rota não encontrada) */
+  status?: number
+  /** Dados serializáveis injetados como window.__SSR_DATA__ para hydration */
+  bootstrapData?: Record<string, unknown>
+  /** <head> extra opcional (meta tags, title dinâmico) */
+  headTags?: string
+}
+
+export type SsrRenderer = (input: SsrRenderInput) => SsrRenderOutput | Promise<SsrRenderOutput>
+
+let registeredRenderer: SsrRenderer | null = null
+
+/** O app chama isto no boot para registrar seu renderer (AppShell). */
+export function registerSsrRenderer(renderer: SsrRenderer): void {
+  registeredRenderer = renderer
+}
+
+export function getSsrRenderer(): SsrRenderer | null {
+  return registeredRenderer
+}

package/core/plugins/built-in/vite/index.ts

@@ -226,6 +226,13 @@ export const vitePlugin: Plugin = {
     }
 
     if (!IS_DEV) {
+      // Em prod com RSC, o rscPlugin serve o HTML (handler buildado) e os assets
+      // (app/client/dist/client). O static fallback do vite procuraria dist/client
+      // (que não existe nesse layout) e quebraria — então pulamos.
+      if ((pluginsConfig as Record<string, unknown>).rscEnabled) {
+        context.logger.debug('Production + RSC: static serving handled by rsc plugin')
+        return
+      }
       context.logger.debug("Production mode: static file serving enabled")
       ;(context.app as Record<string, Function>).all('*', createStaticFallback())
       return