@swissjs/swite 0.3.5 → 0.4.2

package/docs/architecture/import-rewriting.md

@@ -1,101 +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.
+<!--
+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

@@ -1,16 +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
+<!--
+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

@@ -1,93 +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 |
+<!--
+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

@@ -1,92 +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.
+<!--
+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.