@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.31 → 3.2.0-ultramodern.35

package/docs/en/guides/get-started/ultramodern.mdx

@@ -76,6 +76,90 @@ In this repo, the reference examples are:
 - `bff-runtime-parity` for generated-client build/serve parity,
 - `bff-hono` for the compatibility lane.
 
+## Tractor Reference Workspace
+
+The BleedingDev create entrypoint now scaffolds the real Tractor reference workspace instead of the earlier visual boundary demo:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create tractor-super-app
+cd tractor-super-app
+mise install
+mise exec -- pnpm install
+mise exec -- pnpm ultramodern:check
+```
+
+The generated workspace has one shell and three full-stack vertical remotes:
+
+| Package | Owner role | Port | Owns |
+| --- | --- | --- | --- |
+| `apps/shell-super-app` | platform shell | `3020` | route assembly, topology selection, MF host config, shell CSS overlays, global fallback policy |
+| `apps/remotes/remote-explore` | Explore vertical | `3021` | tractor discovery routes, header/footer/recommendations/store picker exposes, `/explore-api/effect/explore/*` |
+| `apps/remotes/remote-decide` | Decide vertical | `3022` | product selection and configuration routes, `ProductPage`, `/decide-api/effect/decide/*` |
+| `apps/remotes/remote-checkout` | Checkout vertical | `3023` | cart, checkout, thanks routes, cart exposes, `/checkout-api/effect/checkout/*` |
+
+The shell consumes remotes through Module Federation references in topology metadata and `zephyr:dependencies`; it should not hardcode deployed remote URLs in source. Each vertical owns its UI route subtree, browser-safe MF exposes, Effect BFF contract, generated client export, locale JSON, CSS entrypoint, Cloudflare Worker metadata, and build marker.
+
+### Route-Owned I18n
+
+Each app emits `src/routes/ultramodern-route-metadata` with `ultramodernLocalisedUrls`. The i18n plugin reads that map in `localeDetection.localisedUrls`, serves dynamic backend JSON from `/locales/{{lng}}/{{ns}}.json`, and keeps `reactI18next` disabled for the generated shell and remotes.
+
+Examples:
+
+| Vertical | Canonical route | English | Czech |
+| --- | --- | --- | --- |
+| Explore | `/tractors` | `/tractors` | `/traktory` |
+| Explore | `/stores` | `/stores` | `/prodejci` |
+| Decide | `/tractors/:slug` | `/tractors/:slug` | `/traktory/:slug` |
+| Checkout | `/cart` | `/cart` | `/kosik` |
+| Checkout | `/checkout/thank-you/:orderId?` | `/checkout/thank-you/:orderId?` | `/pokladna/dekujeme/:orderId?` |
+
+The route owner changes localized paths and locale resource JSON together. Shell-owned URL rewrites are not part of the contract.
+
+### Federated CSS Contract
+
+The generated contract writes `.modernjs/ultramodern-generated-contract.json` with a `cssFederation` section:
+
+- `packages/shared-design-tokens` owns the shared token layer and exports `./tokens.css`.
+- Shell CSS owns only shell base and overlay layers under `[data-app-id="shell-super-app"]`.
+- Remote CSS owns one vertical layer, for example `[data-app-id="remote-explore"]` with `explore-` class prefixes.
+- Tailwind CSS v4 is local to each generated app through `@tailwindcss/postcss`; shared base styles must not be duplicated by remotes.
+- SSR first paint requires shared token CSS and app-owned CSS to be emitted by Modern/Rspack assets. Remote CSS is loaded through remote manifest ownership, not copied into shell source.
+
+Version switching must select UI, Effect API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
+
+### Validation And Proof
+
+Local gates:
+
+```bash
+mise exec -- pnpm ultramodern:check
+mise exec -- pnpm build
+mise exec -- pnpm cloudflare:build
+```
+
+Local Cloudflare artifact validation can run without public credentials:
+
+```bash
+node scripts/ultramodern-cloudflare-ssr-validation/validate-cloudflare-ssr.js \
+  --root-dir apps/remotes/remote-explore \
+  --bff /explore-api/effect/explore/readiness \
+  --expect-en "Explore Remote" \
+  --match-build-marker \
+  --out .codex/reports/cloudflare-ssr/remote-explore-local.json
+```
+
+Generated workspaces also include `scripts/proof-cloudflare-version.mjs`:
+
+```bash
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_REMOTE_EXPLORE=https://remote-explore.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_REMOTE_DECIDE=https://remote-decide.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_REMOTE_CHECKOUT=https://remote-checkout.example.workers.dev \
+mise exec -- pnpm cloudflare:proof -- --require-public-urls
+```
+
+Live Cloudflare and Zephyr proof requires public Worker URLs and Zephyr credentials. Without those, the repo can validate generated contracts, local builds, local Cloudflare output, dry-run Zephyr evidence plans, and local evidence schemas, but it cannot prove shell-driven live version selection.
+
 ## Baseline Switches (Opt-out)
 
 The generated `presetUltramodern(...)` starter enables strict platform contracts. Use these env switches to opt out per app or per environment:

package/package.json

@@ -18,14 +18,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.2.0-ultramodern.31",
+  "version": "3.2.0-ultramodern.35",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.2.0-ultramodern.31"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.2.0-ultramodern.35"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "1.5.2",