@swissjs/swite 0.3.1 → 0.3.3

package/docs/architecture/build-pipeline.md

@@ -0,0 +1,97 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Build Pipeline
+
+`SwiteBuilder` (`src/build-engine/builder.ts`) handles production builds. It is invoked by `swite build` with a fixed entry point of `src/index.ui` and output directory of `dist/`.
+
+---
+
+## Overview
+
+The build runs three sequential phases inside a try/finally block. The temporary directory `.swite-build/` is always removed when the build finishes, whether it succeeded or failed.
+
+```
+swite build
+  └── SwiteBuilder.build()
+        ├── 1. cleanOutputDir()       — rm -rf dist/, mkdir dist/
+        ├── 2. compileSwissFiles()    — @swissjs/compiler → .tsx in .swite-build/
+        ├── 3. bundle()               — esbuild bundles from .swite-build/
+        └── 4. copyPublicAssets()     — cp -r public/ dist/
+```
+
+---
+
+## Phase 1: Compile Swiss files
+
+`compileSwissFiles` traverses `src/` and every workspace dependency's `src/` directory.
+
+For each `.ui` or `.uix` file:
+
+1. `UiCompiler.compileAsync(source, filePath)` — transforms SwissJS component syntax to TypeScript/JSX.
+2. Relative `.ui`/`.uix` imports in the compiled output are rewritten to `.tsx` (esbuild needs `.tsx` for JSX, not `.ui`).
+3. If the compiled output ends with `export { Foo }`, a `export default Foo` line is appended so default imports resolve at bundle time.
+4. Written to `.swite-build/<relative-path>.tsx`.
+
+For each `.ts` file, `.ui`/`.uix` imports in `from` clauses are rewritten to `.tsx`, then the file is copied as-is.
+
+CSS files are copied verbatim so that any CSS import stubs in the bundle phase can resolve.
+
+---
+
+## Phase 2: Bundle with esbuild
+
+esbuild is invoked with:
+
+```typescript
+{
+  bundle: true,
+  format: 'esm',
+  target: 'es2020',
+  minify: true,
+  sourcemap: false,
+  splitting: true,   // ESM code splitting
+  metafile: true,
+  platform: 'node',
+}
+```
+
+Three plugins are registered (see [CLI / build](../cli/build.md) for descriptions). Node built-in modules are marked external. The `absWorkingDir` is set to the workspace root (or app root if no workspace is detected) so esbuild resolves node_modules correctly.
+
+---
+
+## Phase 3: Copy public assets
+
+`public/` is copied recursively to `dist/`. If `public/` does not exist, this phase is skipped silently.
+
+---
+
+## Workspace dependency discovery
+
+`discoverWorkspaceDependencies()` reads the app's `package.json` and collects all `workspace:*` entries from `dependencies`, `devDependencies`, and `peerDependencies`. It also scans source files for `@scope/pkg` import patterns to catch transitive workspace imports not listed in `package.json`.
+
+For each candidate package name, it searches these directories under the workspace root:
+
+```
+lib/<pkgName>
+packages/<pkgName>
+packages/runtime/<pkgName>
+packages/plugins/<pkgName>
+packages/domain/<pkgName>
+```
+
+A match requires the directory to have a `package.json` whose `name` field matches the expected package name, and a `src/` subdirectory.
+
+---
+
+## Workspace resolver plugin
+
+The `workspace-resolver` esbuild plugin handles `@scope/pkg` imports during bundling. It maps each import to the compiled `.tsx` files in `.swite-build/` by:
+
+1. Finding the matching workspace dependency from the discovery step.
+2. Reading the package's `package.json` exports field to resolve the subpath.
+3. Converting the export path from `./src/Foo.uix` to `.swite-build/<depRelPath>/src/Foo.tsx`.
+4. Falling back to `src/index.js` if exports resolution fails.

package/docs/architecture/dev-server.md

@@ -0,0 +1,87 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Dev Server
+
+`SwiteServer` (in `src/dev-engine/server.ts`) is the Express application that handles all incoming requests during development.
+
+---
+
+## Startup sequence
+
+When `server.start()` is called:
+
+1. **Symlink registry** — Scans `node_modules` directories at the app root, one level up from the app root, the workspace root (if detected), and the co-located framework monorepo root. Registers every symlink target so that absolute filesystem paths obtained via `fs.realpath()` can later be mapped back to browser-relative URLs.
+
+2. **Middleware setup** — Calls `setupMiddleware()`, which registers the full middleware chain (see below) and initializes the file router, import map, and env variable loading.
+
+3. **HMR** — Calls `hmr.initialize()` (port probe and WebSocket server creation) then `hmr.start()` (chokidar watcher).
+
+4. **HTTP listen** — Binds to the configured port. When `host` is `"localhost"`, SWITE binds to `0.0.0.0` so both `::1` and `127.0.0.1` respond.
+
+---
+
+## Workspace root detection
+
+`SwiteServer.findWorkspaceRoot(startDir)` walks up the directory tree, up to six levels, looking for:
+
+- A `pnpm-workspace.yaml` file, or
+- A `package.json` with a `workspaces` field
+
+If found, that directory is the workspace root. The workspace root is used to locate `node_modules`, workspace packages, and the import map.
+
+`SwiteConfig.rootDir` can be set to override auto-detection.
+
+---
+
+## Middleware chain
+
+The middleware is registered in a fixed order that Express processes top-to-bottom:
+
+| Priority | Path | Handler |
+|----------|------|---------|
+| 1 | all | File router + HMR routes |
+| 2 | `/packages` | TypeScript and JavaScript handler (workspace source files) |
+| 3 | `/src` | `.ui`, `.uix`, `.ts`, `.js`, `.mjs`, static (CSS, images) |
+| 4 | `/lib` | `.ui`, `.uix` source files (pre-static guard) |
+| 5 | all | `.ui`/`.uix` MIME-type guard |
+| 6 | `/.skltn/modules.css` | Returns 204 (CSS not bundled in dev) |
+| 7 | static | `public/`, `node_modules/`, `lib/`, `libraries/`, `modules/` |
+| 8 | all | General source-file transformation for all other paths |
+| 9 | all | SPA fallback — serves `public/index.html` for HTML-accepting requests |
+
+The SPA fallback refuses to serve HTML for paths under `/src/`, `/swiss-packages/`, and `/lib/` — those return 404 if they reach the fallback, preventing MIME mismatch errors.
+
+---
+
+## File handlers
+
+Each file type has a dedicated handler class that extends `BaseHandler`:
+
+| Handler | Extension(s) | Behaviour |
+|---------|-------------|-----------|
+| `UIHandler` | `.ui` | Compiles via `UiCompiler`, strips TypeScript via esbuild, fixes swiss-lib paths, inlines `import.meta.env`, strips CSS imports, rewrites bare imports |
+| `UIXHandler` | `.uix` | Same pipeline as UIHandler |
+| `TSHandler` | `.ts` | esbuild TypeScript strip, inlines env, rewrites imports. Falls back to `.ui` or `.uix` if the `.ts` file does not exist |
+| `JSHandler` | `.js` | Rewrites imports. Falls back to `.ts`, `.ui`, `.uix` if `.js` does not exist |
+| `MJSHandler` | `.mjs` | Rewrites imports. Falls back to `.js` handler |
+| `NodeModuleHandler` | `/node_modules/…` | Walks up the directory tree to find the package. Serves without import rewriting. Falls back to jsDelivr CDN redirect if not found locally |
+
+All handlers check an in-memory compilation cache before compiling. Cached entries are keyed by file path and invalidated when the file's mtime changes.
+
+---
+
+## Static file serving
+
+`setupStaticFiles` registers `express.static` for:
+
+- `public/` at the root URL
+- `node_modules/` at `/node_modules/` (app root and workspace root)
+- `lib/` at `/lib/` (resolved by walking up from app root looking for a directory that has both `pnpm-workspace.yaml` and `lib/`)
+- `libraries/` at `/libraries/` (workspace root, legacy)
+- `modules/` at `/modules/` (workspace root, CSS and assets only)
+
+Source files (`.ui`, `.uix`, `.ts`, `.js`, `.mjs`) are excluded from `express.static` by a guard middleware registered before each static mount. This ensures they always go through the compiler pipeline.

package/docs/architecture/hmr.md

@@ -0,0 +1,78 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# HMR
+
+`HMREngine` (`src/dev-engine/hmr/hmr.ts`) manages the WebSocket server and file watcher that power hot module replacement.
+
+---
+
+## WebSocket server
+
+The WebSocket server is created by the `ws` package. The default port is 24678. On initialization, SWITE checks whether that port is available by attempting to bind a temporary TCP server. If the port is occupied, `findFreePort()` asks the OS for an available port by binding to port 0 and reading the assigned port back.
+
+All connected browser clients are tracked in a `Set<WebSocket>`. When a client disconnects, it is removed from the set.
+
+The HMR client script is served at `/__swite_hmr_client` as plain JavaScript. The actual WebSocket port is embedded into this script at server startup so the browser client connects to the correct port even when it differs from 24678.
+
+---
+
+## File watcher
+
+`HMREngine.start()` creates a chokidar watcher on the project root with these options:
+
+- Ignored: `node_modules/`, `.git/`, `dist/`
+- `ignoreInitial: true` — no events are fired for files that exist at startup
+- `awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 100 }` — waits for the file to stop changing before firing, which prevents partial-write events
+
+On each `change` event, SWITE determines the update type from the file extension and broadcasts a message to all connected clients.
+
+---
+
+## Update type classification
+
+| File extension | Update type | Browser action |
+|---------------|-------------|----------------|
+| `.css`, `.scss`, `.sass` | `style` | Cache-busts `href` on all `<link rel="stylesheet">` elements by appending `?t={timestamp}` |
+| `.js`, `.ts` in `components/` or `pages/` | `hot` | Re-imports the module and calls `instance.update(newModule)` on registered component instances |
+| Everything else | `reload` | `window.location.reload()` |
+
+---
+
+## Broadcast message format
+
+```json
+{
+  "type": "update",
+  "path": "/absolute/path/to/changed/file",
+  "updateType": "hot | reload | style",
+  "timestamp": 1716211234567
+}
+```
+
+Messages are sent only to clients whose `readyState` is `WebSocket.OPEN`. Clients in any other state are skipped.
+
+---
+
+## HMR client
+
+`buildHmrClientScript(port)` (`src/dev-engine/hmr/hmr-client-template.ts`) returns the browser-side JavaScript as a string with the port number substituted at runtime.
+
+The client:
+
+1. Opens a WebSocket connection to `ws://{hostname}:{port}`.
+2. On `message`, dispatches to `updateStyles()`, the hot-update path, or `window.location.reload()`.
+3. Maintains a `moduleGraph` map (module name → dependents) and a `hotModules` map (module name → module object) for the hot path.
+4. On hot update: removes the module from `window.__swiss_modules__`, re-imports it with a cache-busting `?t={timestamp}` suffix, and calls `instance.update(newModule)` on each registered instance in `window.__swiss_instances__`.
+5. If the hot update throws, falls back to `window.location.reload()`.
+
+`window.__swiss_modules__` and `window.__swiss_instances__` are initialized to empty objects if not already present. The SwissJS runtime populates `__swiss_instances__` with component instance arrays keyed by component name.
+
+---
+
+## notifyChange
+
+`HMREngine.notifyChange(filePath)` is a programmatic interface for triggering HMR broadcasts without a file system event. It is available for use by other server-side logic (such as the file router) that needs to signal a module change.

package/docs/architecture/import-rewriting.md

@@ -0,0 +1,101 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Import Rewriting
+
+The browser cannot fetch bare module specifiers like `@swissjs/core` or `react`. SWITE rewrites every bare import in compiled source to an absolute browser URL before serving.
+
+---
+
+## How it works
+
+`rewriteImports` (`src/resolution/rewriting/import-rewriter.ts`) is called by every file handler after compilation. It uses `es-module-lexer` to find all imports in the code, then applies a collect-and-replace strategy:
+
+1. Parse the code with `es-module-lexer` to get the position of every import specifier.
+2. For each specifier, determine the quoted span in the original string (including the surrounding quote characters).
+3. Collect each replacement as `{ start, end, text }` in original-string coordinates.
+4. Sort replacements by descending start position.
+5. Apply replacements right-to-left, so that each substitution does not shift the positions of specifiers to its left.
+
+This approach eliminates the offset-tracking errors that arise when applying replacements left-to-right.
+
+---
+
+## What is rewritten
+
+Only bare module specifiers (those not starting with `.` or `/`) are passed to `ModuleResolver.resolve`. Relative and absolute path imports are left unchanged.
+
+CSS imports are skipped entirely — they are not ES modules.
+
+---
+
+## Variable references are not rewritten
+
+SWITE only rewrites **string literal** specifiers. Variable references in dynamic imports are left unchanged.
+
+```javascript
+// This WILL be rewritten — string literal
+const mod = await import('@swissjs/router');
+
+// This will NOT be rewritten — variable reference
+const mod = await import(def.componentUrl);
+```
+
+`es-module-lexer` identifies only string literals in import positions. Variable references do not appear as import specifiers in the lexer output.
+
+`ModuleResolver.resolve` also guards against variable-like specifiers: a specifier containing `.` but not starting with `@` (e.g. `def.componentUrl`) is returned unchanged with a warning log rather than being resolved as a module path.
+
+### Required pattern for runtime-determined paths
+
+When the import target is a runtime value, assign it to a simple local variable first:
+
+```typescript
+// Correct
+const url = def.componentUrl;
+const mod = await import(url);
+
+// Avoid — property access may pass the lexer differently across compiler versions
+const mod = await import(def.componentUrl);
+```
+
+---
+
+## Extension fixup
+
+The `@swissjs/compiler` occasionally emits `.js` or `.tsx` extensions in relative import paths for files that exist on disk as `.ui` or `.uix`. Before collecting replacements, `rewriteImports` checks each relative import ending in `.js` or `.tsx`: if the corresponding `.ui` or `.uix` file exists on disk, the extension is corrected.
+
+The correction depends on the importer context:
+
+- If the importer is a file in `swiss-packages/` or `lib/`, the extension is rewritten to `.ts`.
+- If the importer is a `.ui` or `.uix` file, the extension is rewritten to `.ui` or `.uix` based on which file exists on disk.
+- Otherwise `.ts`.
+
+A regex fallback pass applies the same logic for any `.js`/`.tsx` relative imports the lexer may have missed.
+
+---
+
+## Safety net
+
+After the primary lexer pass, `rewriteImports` scans the result with a regex for any remaining bare scoped imports (`@scope/pkg/…`). If any are found, they are rewritten using the CDN fallback or `/node_modules/` URL. This catches cases where the lexer silently failed to parse a particular import form.
+
+---
+
+## Debugging bare imports
+
+If compiled output still contains bare imports after rewriting, SWITE logs:
+
+```
+[SWITE] import-rewriter: CRITICAL — bare import "@scope/pkg" still present after rewriting
+```
+
+Each handler also checks its final output and logs any remaining bare imports:
+
+```
+[.ui] Bare imports still present after rewriting: /src/MyComponent.ui
+[.ui] Unresolved import: @scope/pkg
+```
+
+The `/__swite_diagnose?url=<path>` endpoint fetches any URL the server serves and reports whether bare imports are present in the response, along with the first ten import specifiers found.

package/docs/architecture/index.md

@@ -0,0 +1,16 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Architecture
+
+Internal design of SWITE.
+
+- [Dev server](./dev-server.md) — SwiteServer, workspace root detection, middleware chain, file handlers
+- [Import resolution](./resolution.md) — ModuleResolver, bare-import resolution, workspace packages, CDN fallback, import map
+- [Import rewriting](./import-rewriting.md) — how module specifiers in compiled output are rewritten to browser URLs
+- [Build pipeline](./build-pipeline.md) — SwiteBuilder, esbuild integration, `.ui`/`.uix` compilation
+- [HMR](./hmr.md) — WebSocket server, chokidar watcher, client injection, file-change-to-reload flow
+- [Python integration](./python-integration.md) — Python service lifecycle, health polling, proxy adapter, production mode

package/docs/architecture/python-integration.md

@@ -0,0 +1,93 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Python Integration
+
+SWITE supports a co-located Python backend service. The integration has two parts: lifecycle management during development and a proxy adapter used by application code to forward requests.
+
+---
+
+## Dev lifecycle
+
+`startPythonDevService(config, projectRoot)` (`src/dev-engine/pythonDevManager.ts`) is called by `swite dev` when `services.python.autoStart` is `true`.
+
+### Process spawning
+
+```
+python3 {config.entry}     (python on Windows)
+```
+
+The process is spawned with:
+- `stdio: ['ignore', 'pipe', 'pipe']` — stdin is closed; stdout and stderr are piped
+- Environment: current process environment merged with `config.env`, plus `PORT={config.port}`
+
+Stdout and stderr are read line-buffered and printed to Node's stdout with `[python]` prefixes.
+
+### Health polling
+
+After spawning, `pollHealth(url)` polls `http://localhost:{port}{config.healthCheck}` every 500 ms. The request uses a 1-second `AbortSignal` timeout per attempt. When the response is `ok`, polling stops and the Node server proceeds.
+
+After five attempts the poll interval grows exponentially (doubling with each attempt) up to a maximum of 3 seconds per attempt. The total deadline is 15 seconds. If the deadline passes, SWITE calls `stopPythonDevService()` and throws.
+
+### Shutdown
+
+`stopPythonDevService()` sends `SIGTERM` to the child process. It is registered on both `SIGINT` (Ctrl-C) and the Node `exit` event so the Python process is always cleaned up.
+
+---
+
+## initPythonProxy
+
+`initPythonProxy(config)` stores the `PythonServiceConfig` in module-level state. It is called immediately after `startPythonDevService` resolves, so `proxyToPython` can derive the base URL from the config's port before `PYTHON_SERVICE_URL` is set.
+
+---
+
+## proxyToPython
+
+`proxyToPython<T>(options)` (`src/adapters/proxy/proxyToPython.ts`) is the adapter application code uses to forward requests to the Python service.
+
+### Base URL resolution
+
+| Condition | Base URL |
+|-----------|----------|
+| `PYTHON_SERVICE_URL` env var is set | `PYTHON_SERVICE_URL` (trailing slash stripped) |
+| Not set, dev mode, config initialized | `http://localhost:{config.port}` |
+| Not set, production mode | throws immediately |
+
+### Request
+
+Every call injects the `X-Internal-Token` header with the value of `INTERNAL_API_TOKEN` (empty string if not set). When `options.body` is provided, `Content-Type: application/json` is added and the body is serialized with `JSON.stringify`.
+
+Non-2xx responses throw `SwiteProxyError` with the HTTP status, a description, and the parsed response body.
+
+### Options
+
+```typescript
+interface ProxyOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;       // e.g. '/api/orders'
+  body?: unknown;     // JSON-serializable
+  headers?: Record<string, string>;
+}
+```
+
+---
+
+## Production mode
+
+`setProductionMode()` is called by `swite start` before the server starts. In production mode:
+
+- The localhost fallback is disabled. If `PYTHON_SERVICE_URL` is not set, `proxyToPython` throws `"PYTHON_SERVICE_URL is required in production mode but is not set."` rather than attempting a localhost connection.
+- The Python process is never spawned. The `services.python` config is read only to emit the startup warning if `PYTHON_SERVICE_URL` is absent.
+
+---
+
+## Environment variable summary
+
+| Variable | Used by | Description |
+|----------|---------|-------------|
+| `PYTHON_SERVICE_URL` | `proxyToPython` | Base URL of the Python service. Required in production. Overrides localhost fallback in dev. |
+| `INTERNAL_API_TOKEN` | `proxyToPython` | Value of the `X-Internal-Token` header on every proxy request |
+| `PORT` | Python process | Set automatically to `config.port` by SWITE when spawning the Python process |

package/docs/architecture/resolution.md

@@ -0,0 +1,92 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# Import Resolution
+
+SWITE resolves every bare module specifier to a browser-accessible URL before serving compiled source. This page describes the full resolution pipeline.
+
+---
+
+## ModuleResolver
+
+`ModuleResolver` (`src/resolution/resolver.ts`) is the central resolution object. Each `SwiteServer` creates one instance per app root. It is injected into all file handlers and the import rewriter.
+
+`ModuleResolver.resolve(specifier, importer)` returns a URL string. Specifiers fall into four categories:
+
+1. **Import map hit** — If a pre-generated `.swite/import-map.json` is loaded and the specifier appears in its `imports` map, that URL is returned immediately without further resolution.
+2. **Bare import** — Starts with a letter or `@`. Delegated to `resolveBareImport`.
+3. **Absolute path** — Starts with `/`. Returned as-is.
+4. **Relative import** — Starts with `.`. Resolved relative to the importer's directory on disk, then converted to a URL via `toUrl`.
+
+### Variable reference detection
+
+Before delegating to `resolveBareImport`, the resolver checks whether the specifier looks like a variable reference rather than a module path. Specifiers containing a `.` but not starting with `@` (e.g. `def.componentUrl`) are returned unchanged with a warning. Specifiers that do not match the pattern `^[@a-zA-Z][a-zA-Z0-9_/@-]*(\.(js|ts|ui|uix|mjs|cjs|jsx|tsx))?$` are also returned unchanged.
+
+---
+
+## Bare import resolution
+
+`resolveBareImport` (`src/resolution/bare-import-resolver.ts`) resolves a bare specifier by searching for the package's `package.json` in multiple `node_modules` locations:
+
+1. `<appRoot>/node_modules/<pkg>`
+2. `<parentOfAppRoot>/node_modules/<pkg>`
+3. `<workspaceRoot>/node_modules/<pkg>`
+4. `<frameworkMonorepo>/node_modules/<pkg>`
+
+If a `package.json` is found, the resolver reads the `exports` field (preferring the `import` condition), or falls back to `module` then `main`. In development, if the resolved path is inside a `dist/` directory, the resolver attempts to substitute `src/` and `.ts` extension and serves from source.
+
+---
+
+## Workspace package resolution
+
+When a package is not found in any `node_modules`, `resolveWorkspacePackage` (`src/resolution/workspace-package-resolver.ts`) is called. It uses `PackageRegistry` (a process-wide singleton) to scan the workspace for `package.json` files. The registry recursively scans up to 15 directory levels deep, skipping `node_modules`, `dist`, `.git`, and `.swite`.
+
+If the package is still not found, the registry calls `rescan()` in case the package was added after the initial scan.
+
+---
+
+## toUrl: converting filesystem paths to browser URLs
+
+`toUrl` (`src/resolution/url-resolver.ts`) converts an absolute filesystem path to a browser-relative URL. The resolution order is:
+
+1. **Symlink registry** — Looks up the path in the startup-built registry. If the path (or its `fs.realpath` equivalent) is within a registered symlink target, the corresponding `/node_modules/<pkg>` URL prefix is returned.
+2. **node_modules path** — If the normalized path contains `/node_modules/`, the substring from `/node_modules/` onward is used as the URL.
+3. **Workspace path** — If the path is inside the workspace root, the relative path from the workspace root is used.
+4. **App root path** — If the path is inside the app root, the relative path from the app root is used.
+5. **Framework monorepo packages** — If the path is inside the co-located framework monorepo's `packages/` directory, it is served under `/swiss-packages/`.
+
+---
+
+## CDN fallback
+
+`shouldUseCdnFallback` (`src/resolution/cdn/cdn-fallback.ts`) determines whether a package may be redirected to jsDelivr when not found locally:
+
+- Unscoped packages (e.g. `react`, `reflect-metadata`) always allow CDN fallback.
+- Scoped packages (e.g. `@swissjs/core`) do not allow CDN fallback by default, since they may be private.
+- Scoped packages can be opted in by setting `SWITE_CDN_FALLBACK_SCOPES` to a comma-separated list of scopes (e.g. `@types,@tanstack`).
+
+CDN fallback URLs use the form `https://cdn.jsdelivr.net/npm/{pkg}/+esm`, which serves an ESM build.
+
+---
+
+## Import map
+
+At dev server startup, `setupMiddleware` attempts to load `.swite/import-map.json`. If it exists, `ModuleResolver.setImportMap()` is called and the import map becomes the fast path for all bare import resolutions.
+
+The import map is generated by `generateImportMap` (`src/internal/generate-import-map.ts`), which:
+
+1. Uses `PackageRegistry` to discover all workspace packages.
+2. Calls `resolver.resolve(pkg.name, "")` for each package.
+3. Also resolves common subpaths: `/components`, `/tokens`, `/context`, `/shell`, `/jsx-runtime`, `/jsx-dev-runtime`.
+4. Saves the result as `{ version, generated, imports: { "@pkg/name": "/url" } }`.
+
+The import map is also injected into `public/index.html` by the SPA fallback handler. If HTML already contains a `<script type="importmap">`, SWITE merges the generated entries in, with existing HTML entries taking priority.
+
+---
+
+## Path fixup
+
+`fixSwissLibPaths` (`src/resolution/path/path-fixup.ts`) is applied to every compiled output before import rewriting. It rewrites `/swiss-lib/packages/` to `/swiss-packages/` and `/swiss-lib/` to `/swiss-packages/`. This corrects paths emitted by older versions of `@swissjs/compiler` that referenced a previous directory structure.

package/docs/cli/build.md

@@ -0,0 +1,78 @@
+<!--
+Copyright (c) 2024 Themba Mzumara
+SWITE - SWISS Development Server
+Licensed under the MIT License.
+-->
+
+# swite build
+
+Compiles the application for production.
+
+```bash
+swite build
+```
+
+---
+
+## What it does
+
+`swite build` runs `SwiteBuilder` with a fixed configuration derived from the project root:
+
+| Parameter | Value |
+|-----------|-------|
+| Entry point | `<root>/src/index.ui` |
+| Output directory | `<root>/dist` |
+| Format | ESM |
+| Target | `es2020` |
+| Minify | `true` |
+| Sourcemap | `false` |
+
+These defaults are not yet configurable via `swiss.config.ts`; the builder reads config only for future extensibility.
+
+---
+
+## Build pipeline
+
+The build runs in three phases:
+
+### Phase 1: Compile Swiss files
+
+All `.ui` and `.uix` files in `src/` are passed through `@swissjs/compiler` (`UiCompiler.compileAsync`), which outputs TypeScript/JSX. The resulting code is written to a temporary `.swite-build/` directory as `.tsx` files. Plain `.ts` files are copied as-is, with `.ui`/`.uix` import references rewritten to `.tsx`. CSS files are copied verbatim.
+
+Workspace dependencies declared as `workspace:*` in `package.json` are discovered and compiled into the same temp directory, preserving the workspace directory structure so esbuild can resolve cross-package imports.
+
+### Phase 2: Bundle with esbuild
+
+esbuild is invoked with `bundle: true`, targeting the compiled entry point in `.swite-build/`. Three custom plugins are active:
+
+- `js-tsx-fallback` — redirects `.js` import resolutions to `.tsx` when the `.tsx` file exists in the temp directory (handles UiCompiler emitting `.js` references)
+- `css-stub` — stubs all `.css` imports with `export {}` so they do not block the bundle
+- `workspace-resolver` — resolves `@scope/pkg` imports to compiled files in `.swite-build/`, using `package.json` exports fields and falling back to `src/index.js`
+
+Node built-in modules (`fs`, `path`, `os`, etc., including `node:` prefixed forms) are marked external.
+
+### Phase 3: Copy public assets
+
+The contents of `public/` are copied verbatim to `dist/`.
+
+---
+
+## Output
+
+`dist/` contains the bundled JavaScript (one or more chunks for ESM splitting), copied public assets, and any CSS files the build chose to emit. The `.swite-build/` temporary directory is removed regardless of whether the build succeeded or failed.
+
+Build stats (file count and sizes) are printed to stdout after a successful bundle.
+
+---
+
+## Workspace dependencies
+
+The builder scans `package.json` `dependencies`, `devDependencies`, and `peerDependencies` for `workspace:*` entries and also scans source files for `@scope/pkg` import patterns to discover transitive workspace dependencies. For each discovered package, it looks in these directories under the workspace root (in order):
+
+```
+lib/<pkgName>
+packages/<pkgName>
+packages/runtime/<pkgName>
+packages/plugins/<pkgName>
+packages/domain/<pkgName>
+```