feat(bundler): add Vite and Rsbuild integrations

.claude/PR-summary.md

@@ -0,0 +1,115 @@
+# PR Summary — Vite 8 + Federation Wrapper Architecture
+
+> This summary covers the major architectural changes layered onto PR #300
+> (feat: add Vite and Rsbuild integrations) during the validation push.
+> Source-of-truth is the diff itself; this is the human-readable narrative.
+
+## 1. Vite 7 → 8(rolldown 1.0.3)
+
+**Why**: keep parity with the current Vite latest; surface rolldown-specific issues early.
+
+**Changes**:
+- `@esmx/vite` deps: `vite` ^7.0.0 → ^8.0.0
+- `@esmx/vite-react` deps: `@vitejs/plugin-react` ^5 → ^6 (peer requires vite ^8)
+- `examples/ssr-vite-html` deps: vite ^8
+- `@esmx/vite` tsconfig: `moduleResolution: node` → `bundler` (vite 8 types require)
+- `examples/ssr-vite-react`, `ssr-rsbuild-react`, `templates/react-csr`: react ^18 → ^19.2.6 (dedup with the rest of the repo)
+
+**New plugin** — `packages/vite/src/vite/external-require-plugin.ts`:
+- Rolldown 1.0.3 ESM output for CJS modules that depend on an EXTERNAL package emits
+  `var __require = createRequire(import.meta.url); var React = __require("react")`.
+  That `createRequire` bypasses esmx's `module.register` ESM resolve hook (and the
+  browser has no `createRequire` at all), splitting the react instance and crashing
+  SSR / hydration.
+- The plugin runs in `generateBundle` (rolldown injects these helpers AFTER
+  `renderChunk`) and:
+  1. patches the `__toESM` ternary so `.default = exports` is set
+     unconditionally (vue's `runtime-dom` was hitting the
+     `__esModule: true` skip path);
+  2. rewrites `<alias>("<external>")` call sites to top-level
+     `import * as __esmExt_<X> from "<X>"`, routing both sides of the chunk
+     graph through ESM resolve.
+
+Verified by an isolated demo: a pure vite-8 + rolldown SSR app works on its own
+but crashes with `useState is not a function` once `module.register` rewrites
+the bare `react` specifier — exactly the esmx federation case.
+
+## 2. Federation wrapper architecture(`@esmx/pkg-wrapper`)
+
+**Why**: rspack / rsbuild **dev mode** skips CJS named-export enumeration for
+the federation entry — `import { useState } from 'react'` resolves to
+`undefined`, SSR crashes with `createContext is not a function`. Prod build is
+fine (it does the enumeration); only dev is affected. Vite has the same shape
+of problem but in a different mode.
+
+**New package** — `packages/pkg-wrapper`:
+- Exports `buildPkgWrapper`, `inspectPkg`, `generatePkgWrapperSource`.
+- Uses **`cjs-module-lexer`** (CJS) and **`es-module-lexer`** (ESM), the exact
+  tools rspack / vite / rolldown use internally — so the names we emit
+  in the wrapper match the names the bundler can see during static analysis.
+- Handles the four real-world shapes encountered:
+  - CJS `if (NODE_ENV === 'production') module.exports = require('./prod')
+    else require('./dev')` (react, react-dom, react-router) → lex **both**
+    branches, take the **intersection**;
+  - ESM proxy `export * from './impl'` (vue's `index.mjs` → `index.js`) →
+    recursive ESM lex falling through to CJS lex at the boundary;
+  - ESM-only `exports` map with only an `import` condition
+    (`@esmx/router`) → resolved via Node 24's `findPackageJSON` (the two-arg
+    form of `import.meta.resolve` is unreliable across cwd contexts);
+  - Failing-package graceful warn (no throw, empty result).
+
+**Adapter integration** — every federation `pkg:` export is installed as a
+**virtual module** (mental model: `esmx://<spec>`):
+
+| Adapter | Virtual mechanism |
+|---|---|
+| `@esmx/vite` | native rolldown `resolveId` + `load` plugin hooks (`esmxPkgReexportPlugin` in `vite/config.ts`) |
+| `@esmx/rspack` | `rspack-plugin-virtual-module@^1.0.1` (new dep) |
+| `@esmx/rsbuild` | `rspack-plugin-virtual-module@^1.0.1` (new dep) |
+
+The entry points at the virtual id; the wrapper internally does
+`export { useState, ... } from 'react'`; the bundler's externalizer is told
+to **skip** that import when the issuer is the wrapper itself (otherwise the
+wrapper would loop back through `module.register` and `import` itself).
+
+## 3. Dependency churn
+
+- **New**: `cjs-module-lexer`, `es-module-lexer` (already a core dep, now also in
+  pkg-wrapper), `rspack-plugin-virtual-module` (rspack + rsbuild)
+- **Bumped**: `vite` ^7→^8, `@vitejs/plugin-react` ^5→^6
+- **Workspace**: new package `@esmx/pkg-wrapper` (depended on by rspack /
+  rsbuild)
+
+## 4. Verification (this session)
+
+| Surface | Result |
+|---|---|
+| `pnpm build` × 21 examples (17 micro remotes + 4 standalones) | ✅ |
+| `lint:type` × 17 packages | ✅ |
+| Unit tests × 8 packages | ✅ **1438 tests** (1428 + 10 new in pkg-wrapper) |
+| Standalone runtime SSR(`node dist/index.mjs` + curl) × 20 | ✅ |
+| **Hub-composed cross-remote SSR × 20 paths**(15 remotes + landing + demo + 3 zh) | ✅ |
+| Dev SSR matrix × 12 (vite + rspack + rsbuild × {react, vue, html, preact, solid, svelte, lit}) | ✅ |
+| Browser hydration via hub:`/react/`, `/vue3/`, `/vite-react/`, `/rsbuild-vue/` — counter actually updates | ✅ |
+
+See `.claude/validation-matrix.md` for the row-by-row tally and iteration log.
+
+## 5. Known limitations
+
+- `ssr-vite-vue` standalone postBuild SSR works in this session(was a stub
+  earlier; restored). Still produces an `<h1>Vue SSR Demo`-rendered
+  index.html. Live deploy(Cloudflare Pages) needs a re-run after merging
+  since SRI hashes change with the new wrapper.
+- Preview MCP proxy alters byte-stream-on-the-wire, mismatching SRI in some
+  sessions(infrastructure-only; real deployments unaffected, as verified
+  via curl directly against `node dist/index.mjs`).
+
+## 6. Next steps
+
+- Automate the matrix(this session's `.claude/validation-matrix.md` →
+  CI workflow with the same checks).
+- Open upstream issues:
+  - rolldown 1.0.3 `__require` external CJS handling(esmx tracks via
+    the local patch in `external-require-plugin.ts`).
+  - rolldown 1.0.3 `__toESM` mis-skipping `.default` for
+    `__esModule:true` CJS modules.

.claude/audit-api-docs.md

@@ -0,0 +1,124 @@
+# API Documentation Audit: Implicit Magic Report
+
+## Summary
+Audit of `/examples/docs/src/en/api/` (English version) identified **11 issues** across 8 files that rely on implicit conventions or lack self-contained examples. Issues range from undocumented file path conventions to code snippets with missing context.
+
+---
+
+## Issues by File
+
+### File: core/esmx.md
+**Issue 1: Implicit entry.server file convention**
+- **Line 379**: Code uses `esmx.render()` in `postBuild()` without mentioning that `render()` loads the server entry file by convention.
+- **Evidence**: "Loads the built server entry file (entry.server)" — doesn't say where this file must be located or that naming is conventional.
+- **Suggested fix**: Explicitly state: "The framework loads the server entry from `src/entry.server.ts` (or `.js`) by convention during SSR."
+
+**Issue 2: Undocumented entry.client convention**
+- **Line 379**: Example uses `esmx.render()` which internally loads `entry.client` but this is never documented.
+- **Evidence**: Code samples reference rendering but don't explain the implicit file discovery.
+- **Suggested fix**: Document: "During SSR, the framework looks for client entry at `src/entry.client.ts` which is bundled and referenced by the manifest."
+
+**Issue 3: Implicit dist/client/manifest.json path**
+- **Lines 509, 526**: Code calls `esmx.resolvePath('dist/client', 'manifest.json')` — assumes manifest exists there without documenting the convention.
+- **Evidence**: "const manifest = esmx.readJsonSync(esmx.resolvePath('dist/client', 'manifest.json'));"
+- **Suggested fix**: Add: "The build process generates `manifest.json` at `dist/client/manifest.json` for the client build and `dist/server/manifest.json` for the server build."
+
+### File: core/manifest-json.md
+**Issue 4: Missing manifest location documentation**
+- **Lines 1-12**: Describes what `manifest.json` contains but never explicitly states it's generated at `dist/client/` and `dist/server/` by convention.
+- **Evidence**: "The manifest file generated by the Esmx framework during the build process" — vague location.
+- **Suggested fix**: Add explicit note: "Generated at `dist/client/manifest.json` (client) and `dist/server/manifest.json` (server) after build completion."
+
+### File: core/render-context.md
+**Issue 5: Undefined rc variable without import context**
+- **Lines 68-71, 147-154**: Code snippets use `rc` (RenderContext) without showing where it comes from or how it's passed.
+- **Evidence**: 
+  ```ts
+  const rc = await esmx.render({
+    params: { url: '/page' }
+  });
+  res.end(rc.html);
+  ```
+  Doesn't show `esmx` initialization or that `rc` is the return value of `render()`.
+- **Suggested fix**: Precede examples with: "RenderContext is obtained from `await esmx.render(options)` in your server entry handler."
+
+**Issue 6: Implicit route.params without explanation**
+- **Line 254**: Documentation shows `rc.params` but doesn't clarify that params come from the URL request object passed to `render()`.
+- **Evidence**: "Rendering parameters. Can pass parameters of any type to the rendering function, commonly used to pass request information (URL, query parameters, etc.)."
+- **Suggested fix**: Add: "Parameters are passed explicitly via `esmx.render({ params: { url: req.url } })` — not auto-extracted from the request."
+
+### File: core/app.md
+**Issue 7: Code block references undefined rc variable**
+- **Lines 68-71**: Snippet uses `rc` without showing initialization or imports.
+- **Evidence**:
+  ```ts
+  const rc = await esmx.render({
+    params: { url: '/page' }
+  });
+  res.end(rc.html);
+  ```
+  `esmx` is undefined in this snippet.
+- **Suggested fix**: Add context above the code: "Assuming `esmx` is an initialized Esmx instance from your entry handler."
+
+### File: router/router.md
+**Issue 8: Implicit appId default value undocumented in examples**
+- **Line 37**: Code creates Router without `appId`, defaults to `'app'` without mentioning this magic default.
+- **Evidence**: "appId?: string;...defaults to `'app'`" — in one place, but examples don't show the actual element requirement.
+- **Suggested fix**: Add: "If no `appId` is set, the router will look for element with id='app'. If missing, it creates and appends a `<div id='app'>` to document.body."
+
+### File: router/route-config.md
+**Issue 9: asyncComponent import path convention not documented**
+- **Line 84**: Example shows `asyncComponent: () => import('./Dashboard.vue')` but doesn't clarify that the path is relative to where the route config is defined.
+- **Evidence**: No mention of import semantics or relative path resolution.
+- **Suggested fix**: Add: "Paths are resolved relative to the JavaScript module containing the route configuration."
+
+### File: router-react/hooks.md
+**Issue 10: RouterContext assumed to exist without showing setup**
+- **Lines 29-42**: Code defines `RouterContext` but a fresh AI couldn't understand it wasn't exported from the package.
+- **Evidence**: "const RouterContext = createContext<Router | null>(null);" — appears as user code, not package code.
+- **Suggested fix**: Clarify: "The above is for illustration. In practice, use `RouterProvider` from `@esmx/router-react` which handles context setup automatically."
+
+### File: router-react/ssr.md
+**Issue 11: Implicit window.__ROUTE_DATA__ convention**
+- **Line 56**: Code stores route data in `window.__ROUTE_DATA__` with no explanation of why this variable name is chosen or documented elsewhere.
+- **Evidence**: "rc.html = `...${routeData ? \`<script>window.__ROUTE_DATA__ = ${JSON.stringify(routeData)}</script>\` : ''}\`"
+- **Suggested fix**: Add comment: "The framework convention is to use `window.__ROUTE_DATA__` for passing route state from server to client hydration. You can change the variable name — just keep it consistent across server and client."
+
+---
+
+## Clean Files (No Issues)
+
+- **core/module-config.md** — Well-documented with explicit interface definitions and type mappings
+- **core/pack-config.md** — Clear callback signatures and lifecycle hooks
+- **router/dynamic-matching.md** — Comprehensive param and pattern documentation
+- **router/error-types.md** — Explicit error hierarchy and catch patterns
+- **router/layer.md** — Clear lifecycle and layer result type definitions
+- **router/micro-app.md** — Explicit lifecycle interface with mount/unmount/renderToString
+- **router/navigation-guards.md** — Execution order diagram removes ambiguity
+- **router/nested-routes.md** — Visual diagrams and depth tracking explained
+- **router/programmatic-navigation.md** — All navigation methods documented with return types
+- **router/router-link.md** — CSS classes and link attributes clearly defined
+- **router/route.md** — All route properties explicitly typed with examples
+- **router/scroll-behavior.md** — Scroll flow documented with state property names
+- **router/types.md** — Type reference with deprecation notices
+- **router-react/components.md** — Props table and usage examples clear
+- **router-react/micro-app.md** — Lifecycle interface explicit
+- **router-vue/components.md** — Props documentation complete
+- **router-vue/composables.md** — Function signatures and Vue version handling clear
+- **router-vue/plugin.md** — Installation and behavior explicitly documented
+- **router-vue/type-augmentation.md** — Type augmentation clearly shown for Vue 2 and 3
+
+---
+
+## Recommendations
+
+1. **Add "conventions" section** to core/esmx.md listing all implicit file path conventions (entry.client, entry.server, manifest.json locations)
+
+2. **Precede all code snippets** with minimal context showing variable initialization and imports
+
+3. **Document rc, router instance creation** before examples that use them
+
+4. **Clarify relative path resolution** for dynamically imported modules in route configs
+
+5. **Make context setup explicit** in React/Vue integration docs rather than assuming package internals
+

.claude/audit-errors.md

@@ -0,0 +1,46 @@
+# E5 — Error Message Audit
+
+Date: 2026-06-12. Scope: `packages/{core,router,router-vue,router-react,rsbuild,rspack,vite,import,class-state}/src/`.
+Total error/warning sites surveyed: ~46. **21 GOOD · 8 WEAK · 9 BAD**.
+
+Agent-friendly bar (the user's coding agent must, without leaving the terminal, identify cause + fix):
+1. Name the API / config key / file involved
+2. State what was wrong AND what was expected
+3. Hint at the fix when a common cause exists
+4. Stable wording so LLMs can match patterns
+
+## Top 10 worst offenders (fixed this round)
+
+| # | File:line | Old | New |
+|---|-----------|-----|-----|
+| 1 | core/src/core.ts:635 | bare `console.error(e)` | `console.error('[@esmx/core] postBuild hook failed:', e)` |
+| 2 | router/src/router.ts:388 | bare `console.error(e)` | `console.error('[@esmx/router] SSR render failed:', e)` |
+| 3 | router/src/micro-app.ts:92 | `'MicroApp unmount failed:'` | adds framework-unmount hint |
+| 4 | import/src/import-loader.ts:23 | "can only be created once and cannot be created repeatedly" | references singleton + dedup hint |
+| 5 | import/src/import-loader.ts:31 | `Failed to import '${specifier}'` | chains original error + importMap hint |
+| 6 | class-state/src/connect.ts:198 | "agreed commit function" (vague) | references commit fn + example |
+| 7 | class-state/src/connect.ts:280 | "No state context found" | references provider boundary |
+| 8 | core/src/app.ts:140 | "only available in production" | adds `esmx build` instruction |
+| 9 | rsbuild/src/manifest-plugin.ts:170 | `missing entrypoint "${exp.name}"` | references modules.exports config |
+| 10 | vite/src/manifest-plugin.ts:147 | `missing output chunk for export "${exp.name}"` | references modules.exports config |
+
+## Backlog (WEAK sites, follow-up)
+
+- core/src/core.ts:396 — "Cannot be initialized repeatedly" → name the API (`esmx.init`)
+- core/src/core.ts:1134 — "'devApp' function not set" → reference EsmxOptions.devApp
+- router/src/route-transition.ts:70 — async component error needs expected-export shape
+- router/src/route-transition.ts:435 + micro-app.ts:31 — "X has been destroyed" → reference lifecycle methods
+- router/src/util.ts:149,178 — duplicate "exactly one root HTML element" → add tip on single-root wrapper
+- router/src/micro-app.ts:58 — "hydration function not provided" → reference `app.hydration()`
+- rsbuild/src/app.ts:159 — watch error → include target value
+- rsbuild/src/manifest-plugin.ts:179 — "no .mjs output" → reference bundler format
+- rspack/src/utils/rsbuild.ts:5 — bare red `console.error` → require caller prefix
+- vite/src/manifest-plugin.ts:147 — same backlog as fixed but for other export shapes
+
+## Pattern to enforce
+
+```
+[package-namespace] <what-went-wrong>: <what-was-expected>.
+<config-key-or-file>: <example-or-hint>
+Original error: <chained-error-if-applicable>
+```