create-fluxstack 1.21.0 → 1.22.0

package/app/client/src/framework/routes.ts

@@ -0,0 +1,143 @@
+// File-based routing — descoberta automática de páginas (com rotas dinâmicas).
+//
+// O dev cria um arquivo em app/client/src/pages/ exportando default um componente
+// React. Ele vira uma rota automaticamente. SEM editar RscRoot, entries, nav.
+//
+// Convenção de nomes (relativo a pages/):
+//   index.tsx          -> /
+//   sobre.tsx          -> /sobre
+//   blog/index.tsx     -> /blog
+//   blog/[slug].tsx    -> /blog/:slug        (dinâmica — params.slug)
+//   user/[id].tsx      -> /user/:id          (dinâmica — params.id)
+//   docs/[...rest].tsx -> /docs/*            (catch-all — params.rest = array)
+//
+// A página recebe `{ params }` como prop (funciona em server E client component).
+// No client, também pode usar useParams() (ver ParamsContext).
+//
+// Metadata opcional: export const title = '...'; export const nav = false|'Label'.
+
+import type { ComponentType } from 'react'
+
+export type RouteParams = Record<string, string | string[]>
+
+export interface PageProps {
+  params: RouteParams
+}
+
+export interface PageModule {
+  default: ComponentType<PageProps>
+  title?: string
+  nav?: boolean | string
+}
+
+export interface RouteEntry {
+  /** path estilo express (ex: /blog/:slug, /docs/*) — só p/ exibição/debug */
+  path: string
+  Component: ComponentType<PageProps>
+  title: string
+  inNav: boolean
+  navLabel: string
+  /** regex que casa o pathname; grupos nomeados = params */
+  matcher: RegExp
+  /** nomes dos params na ordem (p/ catch-all marcamos com flag) */
+  paramNames: { name: string; catchAll: boolean }[]
+  /** true se a rota tem segmentos dinâmicos */
+  dynamic: boolean
+}
+
+const allModules = import.meta.glob<PageModule>('../pages/**/*.tsx', { eager: true })
+
+// Convenção: arquivos de ROTA são kebab-case/lowercase. PascalCase (HomePage.tsx)
+// são COMPONENTES auxiliares, ignorados. [slug] começa com '[', também válido.
+const modules = Object.fromEntries(
+  Object.entries(allModules).filter(([file]) => {
+    const base = file.split('/').pop() ?? ''
+    return !/^[A-Z]/.test(base)
+  }),
+)
+
+/** Converte o caminho do arquivo no path estilo express. */
+function fileToPath(file: string): string {
+  let p = file.replace('../pages', '').replace(/\.tsx$/, '')
+  p = p.replace(/\/index$/, '')
+  if (p === '') p = '/'
+  // [...rest] -> * (catch-all); [slug] -> :slug
+  p = p.replace(/\[\.\.\.([^\]]+)\]/g, '*').replace(/\[([^\]]+)\]/g, ':$1')
+  return p || '/'
+}
+
+/** Compila o path em regex + lista de params. */
+function compile(path: string): { matcher: RegExp; paramNames: { name: string; catchAll: boolean }[] } {
+  const paramNames: { name: string; catchAll: boolean }[] = []
+  // capturar o nome original do arquivo p/ catch-all: refazemos a partir do file
+  // mas aqui derivamos do próprio path: ':x' e '*' (catch-all usa nome 'rest' fixo
+  // quando vier de [...rest]; preservamos abaixo no map principal).
+  const pattern = path
+    .split('/')
+    .map((seg) => {
+      if (seg === '*') {
+        paramNames.push({ name: '*', catchAll: true })
+        return '(?<catchall>.*)'
+      }
+      if (seg.startsWith(':')) {
+        const name = seg.slice(1)
+        paramNames.push({ name, catchAll: false })
+        return `(?<${name}>[^/]+)`
+      }
+      return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    })
+    .join('/')
+  const matcher = new RegExp(`^${pattern}/?$`)
+  return { matcher, paramNames }
+}
+
+export const routes: RouteEntry[] = Object.entries(modules)
+  .map(([file, mod]) => {
+    const path = fileToPath(file)
+    // nome real do catch-all vem do arquivo ([...rest] -> 'rest')
+    const catchAllName = file.match(/\[\.\.\.([^\]]+)\]/)?.[1]
+    const { matcher, paramNames } = compile(path)
+    // substitui o placeholder '*' pelo nome real do catch-all
+    for (const p of paramNames) if (p.catchAll && catchAllName) p.name = catchAllName
+    const dynamic = paramNames.length > 0
+    const title = mod.title ?? deriveTitle(path)
+    const inNav = mod.nav !== false && !dynamic // rotas dinâmicas não vão na navbar por padrão
+    const navLabel = typeof mod.nav === 'string' ? mod.nav : title
+    return { path, Component: mod.default, title, inNav, navLabel, matcher, paramNames, dynamic }
+  })
+  // ESTÁTICAS antes de DINÂMICAS (senão /blog/novo casaria /blog/:slug antes de /blog/novo);
+  // entre estáticas, / primeiro depois alfabético.
+  .sort((a, b) => {
+    if (a.dynamic !== b.dynamic) return a.dynamic ? 1 : -1
+    if (a.path === '/') return -1
+    if (b.path === '/') return 1
+    return a.path.localeCompare(b.path)
+  })
+
+function deriveTitle(path: string): string {
+  if (path === '/') return 'Home'
+  const last = path.split('/').filter(Boolean).pop() ?? ''
+  const clean = last.replace(/^[:*]/, '')
+  return clean.charAt(0).toUpperCase() + clean.slice(1)
+}
+
+export interface MatchResult {
+  route: RouteEntry
+  params: RouteParams
+}
+
+/** Procura a rota que casa com um pathname, extraindo os params. */
+export function matchRoute(pathname: string): MatchResult | undefined {
+  for (const route of routes) {
+    const m = route.matcher.exec(pathname)
+    if (!m) continue
+    const params: RouteParams = {}
+    for (const p of route.paramNames) {
+      const raw = p.catchAll ? m.groups?.catchall : m.groups?.[p.name]
+      if (raw === undefined) continue
+      params[p.name] = p.catchAll ? raw.split('/').filter(Boolean) : raw
+    }
+    return { route, params }
+  }
+  return undefined
+}

package/app/client/src/framework/vite-rsc.d.ts

@@ -0,0 +1,21 @@
+// Tipos da extensão `import.meta.viteRsc` do @vitejs/plugin-rsc.
+// O plugin injeta essas APIs em build/dev, mas os tipos nem sempre são
+// captados pelo tsconfig do app — declaramos aqui para o type-check passar.
+import type { ReactNode } from 'react'
+
+declare global {
+  interface ImportMeta {
+    readonly viteRsc: {
+      /** Carrega um módulo de outro ambiente (ex: 'ssr', 'index'). */
+      loadModule<T = unknown>(environment: string, entry: string): Promise<T>
+      /** Conteúdo JS do bootstrap do client entry (para renderToReadableStream). */
+      loadBootstrapScriptContent(entry: string): Promise<string>
+    }
+  }
+}
+
+// createFromReadableStream / createFromFetch retornam a árvore React desserializada
+// tipada como unknown; usamos este alias quando precisamos de ReactNode.
+export type RscNode = ReactNode
+
+export {}

package/app/client/src/hooks/useThemeClock.ts

@@ -1,3 +1,4 @@
+'use client'
 /**
  * React hook for the palette system — respects theme.config.ts
  *
@@ -44,8 +45,22 @@ function getConfiguredPalette(): ColorPalette {
   return generatePalette()
 }
 
+/**
+ * Paleta inicial DETERMINÍSTICA para o primeiro render (SSR + primeira render
+ * do client). Em modo 'auto', generatePalette() depende de new Date(), o que
+ * difere entre server e client e causa hydration mismatch. Por isso o estado
+ * inicial usa sempre 'midday' (fixo); a paleta real baseada na hora é aplicada
+ * no useEffect, que só roda no client após o mount.
+ */
+function getInitialPalette(): ColorPalette {
+  if (themeConfig.mode === 'auto') {
+    return buildPaletteFromHues(themeConfig.hue ?? 270, 'midday')
+  }
+  return getConfiguredPalette()
+}
+
 export function useThemeClock(): ColorPalette {
-  const [palette, setPalette] = useState<ColorPalette>(getConfiguredPalette)
+  const [palette, setPalette] = useState<ColorPalette>(getInitialPalette)
 
   useEffect(() => {
     const initial = getConfiguredPalette()

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

@@ -1,3 +1,4 @@
+'use client'
 import { useState } from 'react'
 import { Live, useLiveComponents } from '@/core/client'
 import { LiveCounter } from '@server/live/LiveCounter'

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

@@ -1,3 +1,4 @@
+'use client'
 import { useMemo } from 'react'
 import { Live } from '@/core/client'
 import { LiveCounter } from '@server/live/LiveCounter'

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

@@ -1,3 +1,4 @@
+'use client'
 import { Live } from '@/core/client'
 import { LiveForm } from '@server/live/LiveForm'
 import { FaCheck, FaCode, FaEnvelope, FaRegMessage, FaUser } from 'react-icons/fa6'

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

@@ -1,3 +1,4 @@
+'use client'
 import { useMemo, useState, useEffect, useRef, useCallback } from 'react'
 import { Live } from '@/core/client'
 import { LivePingPong } from '@server/live/LivePingPong'

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

@@ -1,3 +1,4 @@
+'use client'
 import { useEffect, useMemo, useReducer, useRef } from 'react'
 import { Live } from '@/core/client'
 import { LiveRoomChat } from '@server/live/LiveRoomChat'

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