@swissjs/swite 0.3.5 → 0.4.2

package/dist/kernel/package-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-registry.d.ts","sourceRoot":"","sources":["../../src/kernel/package-registry.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,GAAG,CAAC;CAClB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAgB;IAEjC;;OAEG;IACG,aAAa,CACjB,aAAa,EAAE,MAAM,EACrB,eAAe,GAAE,MAAM,EAAO,GAC7B,OAAO,CAAC,IAAI,CAAC;IAwChB;;OAEG;YACW,aAAa;IAmF3B;;OAEG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAIpD;;OAEG;IACH,cAAc,IAAI,WAAW,EAAE;IAI/B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAW7B;;OAEG;IACH,eAAe,IAAI,MAAM;CAG1B;AAKD,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD"}
+{"version":3,"file":"package-registry.d.ts","sourceRoot":"","sources":["../../src/kernel/package-registry.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,GAAG,CAAC;CAClB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAgB;IAEjC;;OAEG;IACG,aAAa,CACjB,aAAa,EAAE,MAAM,EACrB,eAAe,GAAE,MAAM,EAAO,GAC7B,OAAO,CAAC,IAAI,CAAC;IAwChB;;OAEG;YACW,aAAa;IAmF3B;;OAEG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAIpD;;OAEG;IACH,cAAc,IAAI,WAAW,EAAE;IAI/B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAW7B;;OAEG;IACH,eAAe,IAAI,MAAM;CAG1B;AAKD,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/kernel/package-registry.js

@@ -157,3 +157,11 @@ export function getPackageRegistry() {
     }
     return registryInstance;
 }
+/**
+ * Reset the package registry singleton. For use in tests only.
+ * Call before creating a ModuleResolver to prevent the previous scan state
+ * from leaking between tests.
+ */
+export function resetPackageRegistry() {
+    registryInstance = null;
+}

package/dist/kernel/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/kernel/workspace.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgD5E"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/kernel/workspace.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8C5E"}

package/dist/kernel/workspace.js

@@ -10,29 +10,31 @@ import path from "node:path";
  * Updated: Now also checks for lib/ directory to ensure we find the correct SWS root
  */
 export async function findWorkspaceRoot(root) {
+    const debug = process.env["SWITE_DEBUG"] === "1";
     let current = root;
-    for (let i = 0; i < 10; i++) { // Increased from 5 to 10 to go higher up
+    for (let i = 0; i < 10; i++) {
         const workspaceFile = path.join(current, "pnpm-workspace.yaml");
         const packageJson = path.join(current, "package.json");
         const libDir = path.join(current, "lib");
         try {
             await fs.access(workspaceFile);
-            // Accept root if it has lib/ (SWS with lib/) or packages/ (SWS with packages/ at root)
             const packagesDir = path.join(current, "packages");
             try {
                 await fs.access(libDir);
-                console.log(`[workspace] Found workspace root with lib/: ${current}`);
+                if (debug)
+                    console.log(`[workspace] Found workspace root with lib/: ${current}`);
                 return current;
             }
             catch {
                 try {
                     await fs.access(packagesDir);
-                    console.log(`[workspace] Found workspace root with packages/: ${current}`);
+                    if (debug)
+                        console.log(`[workspace] Found workspace root with packages/: ${current}`);
                     return current;
                 }
                 catch {
-                    // Workspace file exists but no lib/ or packages/, continue searching up
-                    console.log(`[workspace] Found workspace file at ${current} but no lib/ or packages/, continuing search...`);
+                    if (debug)
+                        console.log(`[workspace] Found workspace file at ${current} but no lib/ or packages/, continuing search...`);
                 }
             }
         }
@@ -40,10 +42,10 @@ export async function findWorkspaceRoot(root) {
             try {
                 const pkgJson = JSON.parse(await fs.readFile(packageJson, "utf-8"));
                 if (pkgJson?.workspaces) {
-                    // Also check for lib/ when package.json has workspaces
                     try {
                         await fs.access(libDir);
-                        console.log(`[workspace] Found workspace root with lib/ (via package.json): ${current}`);
+                        if (debug)
+                            console.log(`[workspace] Found workspace root with lib/ (via package.json): ${current}`);
                         return current;
                     }
                     catch {
@@ -60,6 +62,7 @@ export async function findWorkspaceRoot(root) {
             break;
         current = parent;
     }
-    console.warn(`[workspace] No workspace root found starting from: ${root}`);
+    if (debug)
+        console.warn(`[workspace] No workspace root found starting from: ${root}`);
     return null;
 }

package/docs/architecture/build-pipeline.md

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

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

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