feat: lexically scoped React Server Components (#355)

# Lexically Scoped React Server Components

## Summary

This PR introduces **inline `"use client"` and `"use server"`
directives** at the function level, eliminating the requirement that
these directives apply to entire modules. Developers can now define
client components and server functions directly inside any function body
— at arbitrary nesting depths — within a single file.

No other React framework currently supports this capability.

## Motivation

In the standard RSC model, `"use client"` and `"use server"` are
module-level declarations. This forces developers to split
tightly-coupled server and client logic across separate files, leading
to:

- **File proliferation** — a server component with one client button
requires at least two files.
- **Artificial indirection** — the logical unit ("this server page
contains this interactive widget") is scattered across the filesystem.
- **Impossible compositions** — a server function that dynamically
constructs and returns different client components cannot exist, since
they must live in separate modules.

## What's New

### Inline `"use client"` inside server components

```jsx
import { useState } from "react";

function Counter() {
  "use client";
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

export default function Page() {
  return <Counter />;
}
```

### Inline `"use server"` inside client components

```jsx
"use client";
import { useState } from "react";

export default function LikeButton() {
  async function like() {
    "use server";
    await db.likes.increment();
  }
  const [liked, setLiked] = useState(false);
  return <button onClick={() => { like(); setLiked(true); }}>{liked ? "❤️" : "🤍"}</button>;
}
```

### Arbitrary nesting (server → client → server → …)

Directives can alternate at any depth. A server component can define an
inline client component, which itself defines an inline server function,
and so on.

### Lexical scope capture

Variables from parent scopes are automatically forwarded to extracted
modules:
- **Client components**: captured variables become destructured props,
passed via `createElement` wrappers at the call site.
- **Server functions**: captured variables become
`Function.prototype.bind` arguments prepended to the function
parameters.

### Module state sharing

Top-level declarations (constants, mutable variables, class instances)
are **not** duplicated into extracted modules. Instead, extracted
virtual modules import them from the original module, preserving
identity and mutation semantics.

## Architecture

The implementation consists of three components:

| Component | Role |
|---|---|
| `use-directive-inline.mjs` | Core Vite plugin. Performs AST analysis,
outermost-first multi-pass extraction, virtual module serving, and
source transformation. Generic over directive type. |
| `use-client-inline.mjs` | Configuration for `"use client"`. Defines
how captured variables become destructured props and how call sites
become `createElement` wrappers. |
| `use-server-inline.mjs` | Configuration for `"use server"`. Defines
how captured variables become `.bind()` arguments and how call sites
become direct references. |

The plugin is instantiated once with both configs and registered as a
single Vite plugin (`react-server:use-directive-inline`).

### Extraction algorithm

1. **Parse** the source file and find all functions containing a
directive in their body.
2. **Outermost-first**: only extract the outermost directive functions
across all directive types. Inner directives are handled in subsequent
passes when the extracted virtual module is itself transformed.
3. For each outermost directive function:
- Detect **captured scope variables** (not imports, not top-level
declarations, not the function's own locals).
- Generate a **virtual module** (`file.jsx?use-client-inline=FnName` or
`?use-server-inline=FnName`) containing the extracted function with its
directive, necessary imports, and captured variable injection.
- **Replace** the original function in the source with an import from
the virtual module (or a `createElement` wrapper / `.bind()` call if
captured variables are present).
4. **Remove unused imports** from the original module.
5. **Export top-level declarations** used by extracted functions so
virtual modules can import them.
6. Cache extracted modules for consistent resolution across `resolveId`
/ `load` / `transform` lifecycle.

### Build integration

- The `use-client.mjs` plugin's transform filter was updated to match
query-parameterized module IDs (`/\.m?[jt]sx?(\?.*)?$/`).
- `manifest.mjs` now handles virtual modules with query parameters,
correctly resolving file paths by stripping queries before
`realpathSync` and re-appending them for consistent key generation.
- A second pass in `manifest.mjs` processes `buildClientManifest`
entries that only appear as dynamic imports in the SSR build (inline
`"use client"` modules).
- Both `client.mjs` and `server.mjs` build configurations register the
unified `useDirectiveInline` plugin.

Author: lazarv

docs/messages/en.json

@@ -6,6 +6,7 @@
   "category_router": "Router",
   "category_deploy": "Deploy",
   "category_tutorials": "Tutorials",
+  "category_advanced": "Advanced",
   "category_team": "Team",
   "algolia_placeholder": "Search docs",
   "algolia_buttonText": "Search",

docs/messages/ja.json

@@ -6,6 +6,7 @@
   "category_router": "ルーター",
   "category_deploy": "デプロイ",
   "category_tutorials": "チュートリアル",
+  "category_advanced": "高度な",
   "category_team": "チーム",
   "algolia_placeholder": "ドキュメントを検索",
   "algolia_buttonText": "検索",

docs/package.json

@@ -10,6 +10,7 @@
     "start": "react-server start"
   },
   "dependencies": {
+    "@docsearch/css": "^3.6.0",
     "@docsearch/react": "3",
     "@lazarv/react-server": "workspace:^",
     "@opentelemetry/api": "^1.9.0",
@@ -24,10 +25,13 @@
     "@uidotdev/usehooks": "^2.4.1",
     "algoliasearch": "^4.24.0",
     "highlight.js": "^11.9.0",
+    "katex": "^0.16.38",
     "lucide-react": "^0.408.0",
     "rehype-highlight": "^7.0.0",
+    "rehype-katex": "^7.0.1",
     "rehype-mdx-code-props": "^3.0.1",
     "remark-gfm": "^4.0.0",
+    "remark-math": "^6.0.0",
     "three": "^0.183.1",
     "vite-plugin-svgr": "^4.5.0"
   },

docs/react-server.config.mjs

@@ -1,6 +1,8 @@
 import rehypeHighlight from "rehype-highlight";
+import rehypeKatex from "rehype-katex";
 import rehypeMdxCodeProps from "rehype-mdx-code-props";
 import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
 
 export default {
   root: "src/pages",
@@ -12,8 +14,12 @@ export default {
     },
   ],
   mdx: {
-    remarkPlugins: [remarkGfm],
-    rehypePlugins: [[rehypeHighlight, { detect: true }], rehypeMdxCodeProps],
+    remarkPlugins: [remarkGfm, remarkMath],
+    rehypePlugins: [
+      [rehypeHighlight, { detect: true }],
+      rehypeMdxCodeProps,
+      rehypeKatex,
+    ],
     components: "./src/mdx-components.jsx",
   },
   prerender: false,
@@ -25,6 +31,7 @@ export default {
     return [
       ...paths.map(({ path }) => ({
         path: path.replace(/^\/en/, ""),
+        filename: path === "/" ? "index.html" : `${path.slice(1)}.html`,
         rsc: false,
       })),
       // Markdown versions of all docs pages for AI usage

docs/src/components/PageMeta.jsx

@@ -0,0 +1,34 @@
+export default function PageMeta({ date, author, github, lang }) {
+  if (!date && !author && !github) return null;
+
+  return (
+    <div className="flex flex-col items-end self-end gap-1 text-sm text-gray-500 dark:text-gray-400 mt-2 mb-6">
+      {github ? (
+        <a
+          href={`https://github.com/${github}`}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="flex items-center gap-2 hover:text-gray-700 dark:hover:text-gray-300"
+        >
+          <img
+            src={`https://github.com/${github}.png?size=48`}
+            alt={author || github}
+            className="w-6 h-6 rounded-full"
+          />
+          {author || github}
+        </a>
+      ) : author ? (
+        <span>{author}</span>
+      ) : null}
+      {date ? (
+        <time dateTime={date}>
+          {new Date(date).toLocaleDateString(lang, {
+            year: "numeric",
+            month: "long",
+            day: "numeric",
+          })}
+        </time>
+      ) : null}
+    </div>
+  );
+}

docs/src/components/Sidebar.module.css

@@ -152,7 +152,7 @@ article ~ .root {
     background: transparent;
 
     & a {
-      white-space: nowrap;
+      white-space: normal;
       float: left;
       clear: left;
       margin-right: auto;

docs/src/components/Subtitle.jsx

@@ -0,0 +1,7 @@
+export default function Subtitle({ children }) {
+  return (
+    <p className="text-lg text-gray-500 dark:text-gray-400 -mt-4 mb-6">
+      {children}
+    </p>
+  );
+}

docs/src/pages.mjs

@@ -7,6 +7,7 @@ const frontmatterLoaders = import.meta.glob(
   { import: "frontmatter" }
 );
 const loaders = import.meta.glob("./pages/*/\\(pages\\)/**/*.{md,mdx}");
+const indexPages = import.meta.glob("./pages/*/*.\\(index\\).{md,mdx}");
 export const pages = await Promise.all(
   Object.entries(frontmatterLoaders).map(async ([key, load]) => [
     key,
@@ -21,6 +22,7 @@ export const categories = [
   "Router",
   "Deploy",
   "Tutorials",
+  "Advanced",
   "Team",
 ];
 
@@ -112,3 +114,25 @@ export function getPages(pathname, lang) {
 export function hasCategory(category) {
   return categories?.find((c) => c.toLowerCase() === category?.toLowerCase());
 }
+
+export function hasCategoryIndex(category, lang) {
+  return (
+    Object.keys(indexPages).some(
+      (key) =>
+        key === `./pages/${lang}/${category.toLowerCase()}.(index).md` ||
+        key === `./pages/${lang}/${category.toLowerCase()}.(index).mdx`
+    ) ||
+    pages.some(
+      ([, { frontmatter }]) => frontmatter?.slug === category.toLowerCase()
+    )
+  );
+}
+
+export function getPageFrontmatter(pathname, lang) {
+  const allPages = getPages(pathname, lang);
+  for (const { pages: categoryPages } of allPages) {
+    const page = categoryPages.find((p) => p.isActive);
+    if (page) return page.frontmatter;
+  }
+  return null;
+}

docs/src/pages/(root).layout.jsx

@@ -1,14 +1,17 @@
+import "@docsearch/css";
 import "highlight.js/styles/github-dark-dimmed.css";
+import "katex/dist/katex.min.css";
 import "./global.css";
 
 import { cookie, usePathname } from "@lazarv/react-server";
 import { useMatch } from "@lazarv/react-server/router";
 
 import EditPage from "../components/EditPage.jsx";
+import PageMeta from "../components/PageMeta.jsx";
 import ViewMarkdown from "../components/ViewMarkdown.jsx";
 import { useLanguage, m } from "../i18n.mjs";
 import { defaultLanguage, defaultLanguageRE, languages } from "../const.mjs";
-import { categories } from "../pages.mjs";
+import { categories, getPageFrontmatter } from "../pages.mjs";
 
 const lowerCaseCategories = categories.map((category) =>
   category.trim().toLowerCase()
@@ -36,6 +39,7 @@ export default function Layout({
     new RegExp(`^/(${defaultLanguage}|${lang})`),
     ""
   );
+  const frontmatter = getPageFrontmatter(pathname, lang);
 
   return (
     <html
@@ -77,10 +81,7 @@ export default function Layout({
         <meta name="description" content="Run React anywhere" />
         <meta property="og:title" content="@lazarv/react-server" />
         <meta property="og:description" content="Run React anywhere" />
-        <link
-          rel="stylesheet"
-          href="https://cdn.jsdelivr.net/npm/@docsearch/css@3"
-        />
+
         <link
           rel="preconnect"
           href="https://OVQLOZDOSH-dsn.algolia.net"
@@ -114,6 +115,12 @@ export default function Layout({
             <EditPage pathname={pathname} />
             <ViewMarkdown pathname={pathname} />
             {children}
+            <PageMeta
+              date={frontmatter?.date}
+              author={frontmatter?.author}
+              github={frontmatter?.github}
+              lang={lang}
+            />
             {navigation}
           </article>
           {contents}

docs/src/pages/@sidebar/[[lang]]/(sidebar).[...slug].page.jsx

@@ -4,7 +4,7 @@ import { usePathname } from "@lazarv/react-server";
 
 import Sidebar from "../../../components/Sidebar.jsx";
 import { defaultLanguage, defaultLanguageRE } from "../../../const.mjs";
-import { hasCategory, getPages } from "../../../pages.mjs";
+import { hasCategory, hasCategoryIndex, getPages } from "../../../pages.mjs";
 import { m } from "../../../i18n.mjs";
 
 export default function PageSidebar({ lang, slug: [category] }) {
@@ -23,7 +23,8 @@ export default function PageSidebar({ lang, slug: [category] }) {
           <div
             className={`text-md font-semibold mb-2${i > 0 ? " pt-4 dark:border-gray-800" : ""}`}
           >
-            {!pages.some(
+            {hasCategoryIndex(category, lang) &&
+            !pages.some(
               ({ frontmatter }) => frontmatter?.slug === category.toLowerCase()
             ) ? (
               <a
@@ -45,7 +46,7 @@ export default function PageSidebar({ lang, slug: [category] }) {
               <a
                 key={src}
                 href={langHref.replace(defaultLanguageRE, "")}
-                className={`block pb-1 last:pb-0 after:mb-1 last:after:mb-0 text-sm pl-3 border-l border-gray-300 dark:border-gray-600${isActive ? " text-indigo-500 dark:text-yellow-600 active" : ""}`}
+                className={`block pb-1 w-max max-w-[185px] line-clamp-2 last:pb-0 after:mb-1 last:after:mb-0 text-sm pl-6 -indent-3 border-l border-gray-300 dark:border-gray-600${isActive ? " text-indigo-500 dark:text-yellow-600 active" : ""}`}
               >
                 {frontmatter?.title ?? basename(src).replace(/\.mdx?$/, "")}
               </a>