@madojs/mado 0.10.1 → 0.11.0

package/docs/en/01-routing.md

@@ -1,204 +1,152 @@
 # Routing
 
-> One manifest file. No folder scanners. No special characters.
+> One app map. No folder scanners. No special path syntax.
 
-## Why not file-based
+Mado does not infer routes from files. The browser sees files as files; route
+composition should be readable in one place.
 
-In Next/SvelteKit/SolidStart routes appear "magically" from file names. This has
-advantages (URL structure visible in `pages/`), but in production it means:
+## App Manifest
 
-- An invisible plugin-scanner in the build. Without it the files are just files.
-- Special characters in paths: `[id]`, `(group)`, `_layout`, `+page.svelte`, `...slug`.
-- Server-routes and client-routes get confused.
-- Testing routing is a pain: you need a build-tool emulator.
+Use `src/app.routes.ts` as the application map:
 
-Mado considers this **too much magic**. We do it differently.
+```ts
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./modules/auth/auth.public";
+import { authRoutes } from "./modules/auth/auth.routes";
+import { billingRoutes } from "./modules/billing/billing.routes";
+
+export const manifest = {
+  "/": () => import("./modules/home/home.page.js"),
+  "/login": layout({
+    layout: () => import("./layouts/auth-shell.layout.js"),
+    routes: authRoutes,
+  }),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout.js"),
+    guard: requireAuth,
+    routes: billingRoutes,
+  }),
+  "*": () => import("./modules/home/not-found.page.js"),
+};
+
+export default routes(manifest);
+```
 
-## Manifest
+Open `app.routes.ts` and you can see the whole app: public pages, auth zone,
+protected app zones, guards and shells.
 
-One file — `src/routes.ts`. One object. Read top to bottom.
+Exporting `manifest` is important because `mado bake` reads it.
+
+## Module Routes
+
+Modules export plain route maps. They do not call `layout()` and they do not
+decide which shell wraps them.
 
 ```ts
-// src/routes.ts
-import { routes } from '@madojs/mado';
-
-export default routes({
-  '/':              () => import('./pages/home.js'),
-  '/about':         () => import('./pages/about.js'),
-  '/users/:id':     () => import('./pages/user-profile.js'),
-  '/users/:id/edit':() => import('./pages/user-edit.js'),
-  '*':              () => import('./pages/not-found.js'),
-});
+// src/modules/billing/billing.routes.ts
+export const billingRoutes = {
+  "/invoices": () => import("./pages/invoices-list.page.js"),
+  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
+};
 ```
 
-Want to see all routes? Open `routes.ts`. No surprises.
-
-## What goes on the right side of a path
+The prefix is applied by `src/app.routes.ts` when the module is mounted under
+`"/billing"`.
 
-Every entry is **one of three things**:
+## What Goes On The Right Side
 
-### 1. Lazy import (recommended)
+### Lazy page import
 
 ```ts
-'/posts': () => import('./pages/posts.js'),
+"/users/:id": () => import("./modules/users/pages/user-profile.page.js"),
 ```
 
-- The browser makes its own chunk when bundling (esbuild --bundle --splitting).
-- The module is loaded only when the user visits the route.
-- Subsequent navigations use the cached result.
+Vite creates a separate chunk for dynamic imports in production.
 
-### 2. Ready Page (eager)
+### Eager page
 
 ```ts
-import about from './pages/about.js';
+import home from "./modules/home/home.page.js";
 
-'/about': about,
+export const manifest = {
+  "/": home,
+};
 ```
 
-In the bundle immediately, no delay. Use for critical pages (home, login).
+Use this only for tiny critical pages.
 
-### 3. Nested with layout
+### Layout group
 
 ```ts
-import { routes, nested } from '@madojs/mado';
-
-export default routes({
-  '/': () => import('./pages/home.js'),
-
-  '/admin/*': nested({
-    layout: () => import('./layouts/admin.js'),
-    routes: {
-      '':       () => import('./pages/admin/dashboard.js'),
-      'users':  () => import('./pages/admin/users.js'),
-      'logs':   () => import('./pages/admin/logs.js'),
-    },
-  }),
-});
+"/admin": layout({
+  layout: () => import("./layouts/app-shell.layout.js"),
+  guard: requireAuth,
+  routes: adminRoutes,
+}),
 ```
 
-A layout is just a regular `page({...})` that renders `ctx.child` wherever it wants:
+A layout is a normal `page({...})` file:
 
 ```ts
-// src/layouts/admin.ts
-import { page, html, css, component } from '@madojs/mado';
+import { html, page } from "@madojs/mado";
 
 export default page({
   view: ({ child }) => html`
-    <div class="admin">
-      <aside><nav>...</nav></aside>
-      <main>${child}</main>
+    <div class="layout layout--app">
+      <main class="app-main">${child}</main>
     </div>
   `,
 });
 ```
 
-## Page contract
+Keep layout views stateless. Put page-specific signals, resources and forms in
+pages/components/resources, not in layout locals.
 
-```ts
-import { page, html, resource, jsonFetcher } from '@madojs/mado';
-
-export default page({
-  title: ({ id }) => `User #${id}`,        // string | (params) => string
-  load:  ({ id }) => resource(...),         // optional, returns Resource or data
-  view:  ({ params, data, path, child }) => html`...`,  // REQUIRED
-});
-```
-
-Three slots, that's all. If you export something other than `page({...})`, a plain
-function for instance — `routes()` throws a clear error:
-
-```
-[Mado] Lazy route did not return page({...}) as the default export.
-```
-
-## URL parameters
+## Page Contract
 
 ```ts
-'/users/:id': () => import('./pages/user.js'),
-```
+import { html, page } from "@madojs/mado";
 
-```ts
 export default page<{ id: string }>({
   title: ({ id }) => `User ${id}`,
-  view:  ({ params }) => html`<h1>${params.id}</h1>`,
+  view: ({ params }) => html`<h1>${params.id}</h1>`,
 });
 ```
 
-Types are passed in `page<Params>` — `tsc` verifies that you don't access
-`params.foo` which doesn't exist in the route.
-
-## Global options
-
-```ts
-export default routes(
-  { '/': home, '/about': about, '*': nf },
-  {
-    titleSuffix: ' · MyApp',                       // → "Home · MyApp"
-    loading: () => html`<x-spinner/>`,             // while module loads
-    error:   (err) => html`<x-fatal-error .err=${err}/>`,
-  },
-);
-```
+If a lazy route does not default-export `page({...})`, `routes()` throws a clear
+error.
 
-## Programmatic navigation
+## Navigation
 
 ```ts
-import route from './routes.js';
+import appRoutes from "./app.routes.js";
 
-route.navigate('/posts');
-route.navigate('/posts?page=2');
-route.navigate('/posts', { replace: true });
+appRoutes.navigate("/billing/invoices");
+appRoutes.navigate("/billing/invoices?page=2");
+appRoutes.navigate("/login", { replace: true });
 ```
 
-Clicks on `<a href="/foo" data-link>` are intercepted globally (without the
-attribute — the browser does a full reload, as expected for external links).
+Clicks on `<a href="/foo">` are intercepted for same-origin SPA navigation.
+External links still use normal browser navigation.
 
-## Query parameters
+## Query Parameters
 
 ```ts
-import { queryParam } from '@madojs/mado';
+import { queryParam } from "@madojs/mado";
 
-const page = queryParam('page', '1');
-page();              // '1'
-page.set('2');       // history.replaceState + re-render
-page.set(null);      // delete the parameter
-page.set('3', { push: true });   // history.pushState
+const page = queryParam("page", "1");
+page();
+page.set("2");
+page.set(null);
+page.set("3", { push: true });
 ```
 
-`queryParam` is a normal signal. Use it anywhere: in pages, components, computed.
-
-## What is intentionally absent
-
-- ❌ Auto-scan of `pages/`. **One explicit manifest file**.
-- ❌ Special characters in paths (`[id]`, `(group)`, `_layout`). **Parameters are
-  `:name` only, nothing else**.
-- ❌ Server-side routing in the same manifest. Mado is a client-side framework.
-- ❌ Auto-prefetch on hover. If you really need it — do it manually:
-  `link.addEventListener('mouseenter', loader)`. Usually unnecessary.
-
-## FAQ
-
-**What if I have 100 routes? Won't the file get huge?**
-It will grow to ~150 lines. That is still **one source of truth** versus a hundred
-files in `pages/` with magic names. In practice even large projects (1000+ pages)
-can split into feature manifests:
-
-```ts
-import { routes } from '@madojs/mado';
-import adminRoutes from './features/admin/routes.js';
-import billingRoutes from './features/billing/routes.js';
-
-export default routes({
-  ...adminRoutes,
-  ...billingRoutes,
-  '*': () => import('./pages/not-found.js'),
-});
-```
+`queryParam()` is a signal. Use it in pages or components when URL state is part
+of the UI.
 
-**How do I test routing?**
-Import `routes.ts` — it is just an object. Substitute your mock router. No build
-tool emulation needed.
+## What Is Intentionally Absent
 
-**Does code splitting work?**
-Yes. With `esbuild --bundle --splitting --format=esm` every
-`() => import('./pages/x.js')` becomes its own chunk.
+- No auto-scan of page folders.
+- No special filesystem route syntax like `[id]`, `(group)`, `_layout`.
+- No server routes in the client manifest.
+- No hidden layout discovery. App zones are explicit in `app.routes.ts`.

package/docs/en/02-project-layout.md

@@ -8,40 +8,42 @@ things live.
 my-app/
 ├── package.json              # exactly one runtime dep: @madojs/mado
 ├── tsconfig.json             # strict TS, ES2022, Bundler resolution
-├── mado.config.json          # single config file (dev/build/bake/bundle)
-├── index.html                # SPA shell (also the template for `mado bake`)
+├── vite.config.ts            # optional; use mado() from @madojs/mado/vite
+├── index.html                # Vite entry + SPA shell
 ├── public/                   # static assets (favicons, images, robots.txt)
 └── src/
     ├── main.ts               # entry: mount router into #app
-    ├── routes.ts             # route manifest (default + named `manifest`)
-    ├── layouts/              # `page({ child })` layouts for nested routes
-    ├── pages/                # one page = one file
-    ├── components/           # reusable x-* Web Components
-    └── lib/
-        ├── api.ts            # API client + error type
-        ├── auth.ts           # auth recipe (token + guard)
-        └── ...               # contexts, helpers, business rules
+    ├── app.routes.ts         # one app map (default + named `manifest`)
+    ├── layouts/              # app-zone layouts, not domain modules
+    ├── shared/               # ui, http, lib, styles
+    └── modules/              # bounded contexts
+        └── billing/
+            ├── billing.routes.ts
+            ├── billing.public.ts
+            ├── billing.types.ts
+            ├── pages/
+            ├── data/
+            ├── api/
+            └── _contracts/
 ```
 
 ## The three artifact states (read this once, never wonder again)
 
 | Folder      | What it is                                                     | Who writes        | Who reads                  | Deploy?           |
 |-------------|----------------------------------------------------------------|-------------------|----------------------------|-------------------|
-| `src/`      | your source (TypeScript)                                       | you               | `tsc`, `esbuild`           | ❌ no             |
-| `dist/`     | `tsc` output — native ESM `.js` for the browser                | `mado build`      | `mado dev` (during dev)    | ❌ no (internal)  |
-| `public/`   | static assets you authored (favicon, images, robots.txt)       | you               | `mado release` copies it   | ✅ via `out/`     |
-| `out/`      | **the deploy artifact**: SPA shell + bundles + baked HTML      | `mado release`    | nginx / CDN / Cloudflare   | ✅ **yes**        |
+| `src/`      | your source (TypeScript)                                       | you               | Vite, `tsc --noEmit`       | ❌ no             |
+| `public/`   | static assets copied as-is (favicon, images, robots.txt)       | you               | Vite build                 | ✅ via `out/`     |
+| `out/`      | **the deploy artifact**: SPA shell + assets + baked HTML       | `mado release`    | nginx / CDN / Cloudflare   | ✅ **yes**        |
 
 One-liner to remember:
 > Develop with `mado dev`. To ship: run `mado release`, then upload `out/`.
 
-`mado release` = `typecheck` + `build` (tsc → `dist/`) + `bundle` (esbuild
-→ `out/assets/`) + `bake` (HTML → `out/baked/`) + promote baked HTML and
-`sitemap.xml` into deployable `out/` paths + copy `public/*` → `out/`.
+`mado release` = `typecheck` + Vite build (`out/index.html`, `out/assets/`,
+`public/*`) + `bake` directly into deployable route paths + `sitemap.xml` +
+precompressed assets and CDN helper files.
 
-You almost never need to look inside `dist/`. It exists so the dev browser can
-load native ESM modules without a bundler during development. In production
-the equivalent code is bundled and hashed into `out/assets/`.
+`index.html` belongs at the project root because Vite treats it as an entry
+template, not as a static public file. Put only copy-as-is files in `public/`.
 
 ### Quick deployment matrix
 
@@ -57,14 +59,19 @@ See `docs/en/13-deployment.md` for full recipes.
 
 | What                                | Where                                                |
 |-------------------------------------|------------------------------------------------------|
-| Page for a new URL                  | `src/pages/<name>.ts` + add to `src/routes.ts`       |
-| Layout for a group of routes        | `src/layouts/<name>.ts` (referenced from `routes.ts`)|
-| Reusable UI widget                  | `src/components/<x-name>.ts`                         |
-| API call                            | `src/lib/api.ts` (add a method)                      |
-| Auth/session                        | `src/lib/auth.ts`                                    |
-| Global context (theme, user, i18n)  | `src/lib/<name>.ts`                                  |
-| Pure function with no UI            | `src/lib/util/<name>.ts`                             |
+| Page for a new URL                  | `src/modules/<module>/pages/<name>.page.ts` + module routes |
+| Module route map                    | `src/modules/<module>/<module>.routes.ts`            |
+| App shell/layout                    | `src/layouts/<zone>.layout.ts`                       |
+| Reusable shared UI widget           | `src/shared/ui/<x-name>.component.ts`                |
+| Module-only UI widget               | `src/modules/<module>/components/<name>.component.ts` |
+| API connector                       | `src/modules/<module>/api/<provider>.connector.ts`   |
+| Data resource/mutation              | `src/modules/<module>/data/<name>.resource.ts`       |
+| Auth/session                        | `src/modules/auth/`                                  |
+| Public module surface               | `src/modules/<module>/<module>.public.ts`            |
+| Pure function with no UI            | `src/shared/lib/<name>.ts`                           |
 | Static image / favicon              | `public/<file>`                                      |
+| App-zone shell CSS                  | `src/shared/styles/shell.css`                       |
+| Page-level table/form/prose CSS      | `src/shared/styles/content.css`                     |
 
 If you don't know where — that is a signal that **the architecture is
 suffering**. Ask the team and **record** the answer in `docs/`. Don't invent a
@@ -80,39 +87,38 @@ new top-level folder.
 | Signal                              | camelCase            | `userId`, `isLoggedIn` |
 | Page-internal element               | `x-<route>-page`     | `<x-posts-page>`       |
 
-## `mado.config.json` in one screen
+## Vite config
 
-```jsonc
-{
-  "dev": {
-    "port": 5173,
-    "proxy": { "/api": "http://localhost:3000" }   // dev → backend
-  },
-  "build": {
-    "out": "out",
-    "dist": "dist",
-    "publicDir": "public"
+App/dev/build settings live in `vite.config.ts`.
+
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado()],
+  css: {
+    transformer: "lightningcss",
   },
-  "bake": {
-    "entry": "src/routes.ts",
-    "template": "index.html",
-    "baseUrl": "https://example.com"
+  server: {
+    proxy: { "/api": "http://localhost:3000" },
   },
-  "bundle": {
-    "splitting": true,
-    "compress": ["gz", "br"]
-  }
-}
+});
 ```
 
-Precedence: built-in defaults < `mado.config.json` < CLI flags
-(< legacy env vars). All keys are optional.
+The default starter opts into Vite's Lightning CSS transformer. CSS
+minification is already handled by Vite; the explicit transformer keeps
+prefixing and modern CSS lowering in Vite instead of in Mado.
+
+`mado bake` uses conventions by default: `src/app.routes.ts` first,
+then `src/routes.ts`, `index.html` as the template, and `out/` as output.
+Use CLI flags (`--entry`, `--template`, `--out`, `--base-url`) for the few
+values that are specific to prerendering.
 
 ## What does NOT go in `src/`
 
-- ❌ Build tool configs (webpack, rollup, vite) — we don't have any.
-- ❌ `.env` files — read env in `src/lib/config.ts` from `import.meta.env` /
+- ❌ Extra build tool configs — use `vite.config.ts` with `mado()` when needed.
+- ❌ `.env` files — read env in `src/shared/lib/config.ts` from `import.meta.env` /
   `process.env` and import that one module everywhere.
 - ❌ Tests mixed with code — put them in `test/`.
-- ❌ `examples/` folder — the framework repository has examples, your app
-  does not need one.
+- ❌ `examples/` folder — keep large demos outside the app repo.

package/docs/en/03-static-bake.md

@@ -40,7 +40,7 @@ The `npm run bake` command traverses all `page` entries with `bake`, generates H
 ## Example
 
 ```ts
-// src/pages/product.ts
+// src/modules/<module>/pages/product.ts
 import { page, component, html } from "@madojs/mado";
 import { findProduct, products, type Product } from "../lib/products.js";
 
@@ -84,7 +84,7 @@ export default page<{ slug: string }, Product | undefined>({
 ```
 
 ```ts
-// src/routes.ts
+// src/app.routes.ts
 import { routes, type RoutesMap } from "@madojs/mado";
 
 // Export BOTH default (RouterApi for runtime) AND manifest (for the bake script).
@@ -100,8 +100,7 @@ export default routes(manifest, { titleSuffix: " · MyShop" });
 ## Running
 
 ```bash
-npm install -D linkedom esbuild
-npm run build
+npm install -D linkedom vite
 npm run bake
 ```
 
@@ -144,7 +143,7 @@ out/
     {"slug":"mado-mug","name":"Mado Mug","price":12,"..."}
   </script>
 
-  <script type="module" src="/dist/examples/main.js"></script>
+  <script type="module" src="/assets/index-HASH.js"></script>
 </body>
 ```
 
@@ -174,7 +173,7 @@ export const allPosts = () =>
 ```
 
 ```ts
-// src/pages/blog-post.ts
+// src/modules/<module>/pages/blog-post.ts
 import { page, html } from "@madojs/mado";
 import { allPosts } from "../lib/posts.js";
 

package/docs/en/05-why-mado.md

@@ -36,11 +36,11 @@ If your case does not fall into the last point — Mado is most likely not the b
 | Size           | ~6 KB                                                          | ~16 KB                                                 |
 | Age / support  | ~10 years, Google                                              | 6 months, single author                                |
 | Reactivity     | `@property` decorators + manual `requestUpdate`                | signals (`signal`/`computed`/`effect`) out of the box  |
-| Router         | none, you need to find one (`@lit-labs/router`, etc)           | included: `routes()` + nested + prefetch + sync-cache  |
+| Router         | none, you need to find one (`@lit-labs/router`, etc)           | included: `routes()` + layout groups + prefetch        |
 | Data fetching  | none, you need to assemble it                                  | `resource()` + `mutation()` + glob invalidation        |
 | Forms          | none                                                           | `useForm()` with HTML-like constraints                 |
 | SEO / static   | complex (`@lit-labs/ssr`)                                      | `bake` (linkedom) + edge-prerender                     |
-| Build          | needs esbuild/rollup/webpack                                   | `tsc` is enough                                        |
+| Build          | needs framework-specific build plugins                         | Vite transport + native runtime                         |
 | Code style     | classes + decorators                                           | functions + tagged templates                           |
 | Ecosystem      | real (Shoelace, Material Web, etc.)                            | none                                                   |
 | When to choose | writing a design system / Web Components library for embedding | writing a full application, want everything in one box |
@@ -60,14 +60,14 @@ If your case does not fall into the last point — Mado is most likely not the b
 | Reactivity      | signals (same class of ideas)                               | signals                                              |
 | Templates       | JSX (compiled to reactive expressions)                      | tagged template `html\`\``                           |
 | Component model | functions, Solid virtual nodes                              | Web Components                                       |
-| Build           | Vite + babel-plugin-solid required                          | `tsc` only                                           |
+| Build           | Vite + babel-plugin-solid required                          | Vite for dev/build, no runtime dependencies          |
 | Router          | `@solidjs/router`                                           | included                                             |
 | Data            | `createResource`                                            | `resource()`                                         |
 | SSR             | seriously supported (SolidStart)                            | intentionally none                                   |
 | Ecosystem       | growing, ~50 packages                                       | none                                                 |
-| When to choose  | need top performance + JSX + willing to configure the build | want to run without a build / minimal infrastructure |
+| When to choose  | need top performance + JSX + willing to configure the build | want browser-native runtime with simple tooling      |
 
-**Honest pitch:** _"Solid is technically faster and more mature. But Solid requires Vite + a babel plugin. Mado requires nothing but `tsc` — it's 'open VS Code, F5, and work'. If that difference isn't critical — go with Solid."_
+**Honest pitch:** _"Solid is technically faster and more mature. Mado is smaller in concept: browser-native runtime, Web Components, tagged templates, and Vite doing the boring dev/build work. If you want JSX and a larger ecosystem, go with Solid."_
 
 ---
 
@@ -162,7 +162,7 @@ I won't dwell on this for long, because React is in a **different weight class**
 
 Not size, not performance, not signals — everything has better competitors.
 
-> **"Open the source and read it in an evening. ~3500 lines, 12 modules. If something breaks — you don't go to an issue with 3000 comments. You go to `src/router.ts` and read 500 lines."**
+> **"Open the source and read it in an evening. ~3500 lines, small modules. If something breaks — you don't go to an issue with 3000 comments. You go to `src/router/` and read the code."**
 
 This is called **ownership** — you own the code, rather than depending on someone else's.
 

package/docs/en/06-for-backenders.md

@@ -14,7 +14,7 @@ Mado is structured **like an HTTP server**. Seriously:
 | ----------------------------------- | ---------------------------------------------- |
 | HTTP router (chi, axum, mux)        | `routes()` — path manifest                     |
 | Handler `func(req, resp)`           | `page({ view: (ctx) => html\`...\` })`         |
-| Middleware                          | `layout` in `nested()` (wraps the handler)     |
+| Middleware                          | `layout()` route group (wraps the handler)     |
 | Template engine (Jinja, Handlebars) | `html\`\`` tagged template                     |
 | HTTP client with cache              | `resource()` — fetch + cache + invalidation    |
 | Reactive variable / atom            | `signal()` — reactive getter                   |
@@ -61,7 +61,7 @@ http.ListenAndServe(":8080", r)
 ### Mado — the same thing
 
 ```ts
-// src/routes.ts
+// src/app.routes.ts
 import { routes } from "@madojs/mado";
 
 export default routes({
@@ -71,7 +71,7 @@ export default routes({
 ```
 
 ```ts
-// src/pages/home.ts
+// src/modules/<module>/pages/home.ts
 import { page, html } from "@madojs/mado";
 export default page({
   view: () => html`<h1>Hello</h1>`,
@@ -79,7 +79,7 @@ export default page({
 ```
 
 ```ts
-// src/pages/user.ts
+// src/modules/<module>/pages/user.ts
 import { page, html } from "@madojs/mado";
 export default page<{ id: string }>({
   view: ({ params }) => html`<h1>User ${params.id}</h1>`,
@@ -266,7 +266,7 @@ This is like `context.WithValue` / `ctx.Value` in Go, but reactive.
 If you're used to server-side rendering for SEO, in Mado this is solved differently: **prerender at build time**.
 
 ```ts
-// src/pages/product.ts
+// src/modules/<module>/pages/product.ts
 export default page({
   bake: {
     paths: () => api.allProductSlugs(), // build-time fetch
@@ -369,37 +369,33 @@ export default page({
 ```
 
 ```ts
-// src/routes.ts
-import { routes, nested } from "@madojs/mado";
+// src/app.routes.ts
+import { layout, routes } from "@madojs/mado";
 
 export default routes({
   "/login": () => import("./pages/login.js"),
 
-  "/app/*": nested({
+  "/app": layout({
     layout: () => import("./layouts/auth-layout.js"),
     routes: {
-      dashboard: () => import("./pages/dashboard.js"),
-      users: () => import("./pages/users.js"),
+      "/dashboard": () => import("./pages/dashboard.js"),
+      "/users": () => import("./pages/users.js"),
     },
   }),
 });
 ```
 
-### Global API client (like a singleton in Go)
+### Shared HTTP client (like a small transport package in Go)
 
 ```ts
-// src/lib/api.ts
-export class ApiClient {
-  constructor(private base: string) {}
-  get<T>(path: string): Promise<T> {
-    return fetch(this.base + path).then((r) => r.json());
-  }
-}
-
-export const api = new ApiClient("/api");
+// src/shared/http/http-client.ts
+export const httpClient = {
+  get: <T>(path: string): Promise<T> =>
+    fetch(path).then((r) => r.json() as Promise<T>),
+};
 ```
 
-Used directly via `import { api } from '...'` or through `createContext` for testability.
+Module connectors build on this transport and map DTOs to domain types.
 
 ---
 
@@ -442,6 +438,6 @@ Everything else — standard browser + TypeScript.
 - **[`01-routing.md`](./01-routing.md)** — the router in detail.
 - **[`02-project-layout.md`](./02-project-layout.md)** — project structure.
 - **[`03-static-bake.md`](./03-static-bake.md)** — SEO without SSR.
-- **[`examples/showcase/`](../../examples/showcase/)** — full example (landing + admin).
+- **External `madojs-examples` workspace** — full demos (landing + admin).
 
 If something is unclear — open an issue, or just open the source. It really is readable in an evening.