bimba-cli 0.7.8 → 0.7.10

package/INTERNALS.md

@@ -0,0 +1,300 @@
+# Bimba Internals: How Imba Rendering Works and How Bimba HMR Hooks Into It
+
+Technical reference for debugging and extending bimba's dev server (`serve.js`).
+
+---
+
+## 1. How Imba Compiles Tags to JS
+
+Imba source:
+```imba
+tag my-popup
+    name = ''
+
+    def mount
+        name = 'hello'
+
+    <self @click.self=(emit('close'))>
+        <div.dialog>
+            <span.title> "Settings"
+            if condition
+                <img src=url>
+            else
+                <span.placeholder> "?"
+            <button @click=save> "Save"
+```
+
+Compiled JS (simplified):
+```js
+import { Component, defineTag, createElement, createComponent, ... } from 'imba';
+const $beforeReconcile$ = Symbol.for('#beforeReconcile');
+const $afterVisit$ = Symbol.for('#afterVisit');
+const $placeChild$ = Symbol.for('#placeChild');
+const $$up$ = Symbol.for('##up');
+
+// Anonymous Symbols — one per DOM slot in the render tree.
+// These are the RENDER CACHE KEYS.
+var $7 = Symbol(), $11 = Symbol(), $13 = Symbol(), $19 = Symbol(), $24 = Symbol(), ...;
+let c$0 = Symbol(); // class identity symbol
+
+class MyPopupComponent extends Component {
+    [__init__$]($$ = null) {
+        super[__init__$](...arguments);
+        this.name = ($$ && $$.name !== undefined) ? $$.name : '';
+    }
+
+    mount() { this.name = 'hello'; }
+
+    render() {
+        var $4, $5, $6, $8 = this._ns_ || '', $9, $18, ...;
+        $4 = this;                          // $4 = the element itself
+        $4[$beforeReconcile$]();
+
+        // ── "First render" check ──
+        // $7 is a Symbol. this[$7] is stored on the INSTANCE.
+        // First render: this[$7] is undefined → $5=0 (CREATE mode)
+        // Re-render:   this[$7] === 1        → $5=1 (REUSE mode)
+        ($5=$6=1, $4[$7] === 1) || ($5=$6=0, $4[$7] = 1);
+
+        // ── Static children: created only on first render ($5=0) ──
+        $5 || ($4.on$('click', {self: true, ...}));
+        $5 || ($9 = createElement('div', $4, `dialog ${$8}`, null));
+        //       ↑ createElement appends $9 as child of $4
+
+        // ── Cached children: checked on every render ──
+        ($10 = $4[$11]) || ($4[$11] = $10 = createElement('span', $9, ...));
+        //  ↑ try cache          ↑ miss → create and cache
+
+        // ── Conditional blocks ──
+        $18 = null;
+        if (this.condition) {
+            ($20=$21=1, $18=$4[$19]) || ($20=$21=0, $4[$19]=$18=createElement('img',...));
+        } else {
+            ($25=$26=1, $18=$4[$24]) || ($25=$26=0, $4[$24]=$18=createElement('span',...));
+        }
+        // placeChild manages which branch is in the DOM
+        ($4[$30] = $16[$placeChild$]($18, 0, $4[$30]));
+
+        $4[$afterReconcile$]($6);
+        return $4;
+    }
+
+    // Static block runs at class definition time
+    static {
+        register$(this, c$0, 'my-popup', 2);    // → calls customElements.define
+        defineTag('my-popup', this, {cssns: 'z1abc_xy', cssid: 'z1abc-xy'});
+    }
+}
+
+// CSS is registered as a global stylesheet
+imba_styles.register('z1abc', "...");
+```
+
+### Key points
+
+| Concept | Details |
+|---------|---------|
+| **Render cache** | Each DOM node is cached on the element instance under an anonymous `Symbol()` key. `this[$sym] \|\| (this[$sym] = createElement(...))`. |
+| **Create vs Reuse** | `this[$7] === 1` is the master flag. `$5=0` = first render (create all), `$5=1` = re-render (reuse cached). |
+| **Static children** | Guarded by `$5 \|\| (...)` — created only on first render, never recreated. |
+| **Conditional children** | Each branch has its own cache slot (`$19` for `if`, `$24` for `else`). `$placeChild$` swaps them in/out. |
+| **CSS namespace** | `_ns_` on prototype (e.g. `"z1abc_xy "`). Used as className prefix. Hash changes when CSS content changes. |
+| **Tag registration** | `register$` → `customElements.define()`. `defineTag` → sets `_ns_`, `cssid`, registers in Imba's internal tag registry (`J[name]`, `xh[name]`). |
+| **Lifecycle** | `__init__$` (property defaults), `connectedCallback` (DOM attachment), `mount` (post-connect, user code), `render` (DOM creation/update). |
+
+### Imba runtime functions
+
+| Function | What it does |
+|----------|-------------|
+| `createElement(tag, parent, className, text)` | `document.createElement` + `parent[appendChild$](el)`. For plain HTML elements. |
+| `createComponent(name, parent, className, text)` | Same but for custom elements. If `name` is a string, uses `document.createElement(name)`. |
+| `imba_styles.register(id, css)` | Injects/updates a `<style>` element in `<head>`. Idempotent by `id`. |
+| `defineTag(name, klass, opts)` | Registers tag in Imba's internal registry. Sets `_ns_`, `cssid`, `flags$ns` on prototype. |
+| `register$(klass, symbol, name, flags)` | Sets up class metadata (`__meta__$`), calls `customElements.define`. |
+| `imba.commit()` | Schedules a render tick via `requestAnimationFrame`. All scheduled components re-render. |
+| `$beforeReconcile$` | Called at start of render. Clears internal child tracking state. |
+| `$afterReconcile$` | Called at end of render. Finalizes child list. |
+| `$placeChild$(child, type, prev)` | Manages conditional/dynamic child placement. Inserts/removes/replaces nodes. |
+| `$afterVisit$(flag)` | Post-render hook on a component child. Triggers its own render if needed. |
+
+---
+
+## 2. The Problem Bimba Solves
+
+Browsers have no built-in HMR for custom elements:
+- `customElements.define(name, class)` can only be called ONCE per tag name
+- Re-importing a module creates fresh `Symbol()` instances — old cache keys become orphans
+- Without intervention, re-importing causes full duplication of DOM children
+
+---
+
+## 3. How Bimba's HMR Works
+
+### 3.1 Symbol Stabilization (server-side)
+
+**Problem:** Each `var $7 = Symbol()` creates a unique symbol. Re-importing the module creates a NEW `$7` symbol. Existing elements have DOM cached under the OLD `$7`. The new render method looks up `this[NEW_$7]` — not found → creates duplicate DOM.
+
+**Solution:** Rewrite `Symbol()` calls to use a persistent global cache:
+
+```
+$7 = Symbol()
+  ↓
+$7 = (__bsyms__["$7"] ||= Symbol())
+```
+
+Where `__bsyms__` is keyed by absolute file path:
+```js
+const __bsyms__ = ((globalThis.__bimba_syms ||= {})["/abs/path/to/file.imba"] ||= {});
+```
+
+First load: creates symbols, stores in cache.
+HMR reload: reuses same symbols from cache → render finds cached DOM → REUSE mode.
+
+**Critical:** The file path key MUST be normalized (absolute via `path.resolve`). Different string representations of the same file (e.g., `./src/foo.imba` vs `src/foo.imba`) produce different cache keys → different symbols → duplication. This was the root cause of the v0.7.8 fix.
+
+### 3.2 Slot Stability Detection
+
+If the user adds/removes template elements, the number of `Symbol()` declarations changes. Variable names shift (`$7` now means a different DOM slot). Even with stable symbols, the SEMANTICS change.
+
+Detection: count `Symbol()` calls per file. Compare to previous compilation:
+- Same count → `slots: 'stable'` → safe for in-place HMR
+- Different count → `slots: 'shifted'` → must do destructive HMR
+
+### 3.3 Prototype Patching (browser-side)
+
+`customElements.define` is hooked:
+
+```
+First call (page load):  register normally, save class in _classes map
+Repeat calls (HMR):      _patchClass(originalClass, newClass)
+```
+
+`_patchClass` copies ALL own property descriptors (string + symbol keys) from the new class prototype to the original class prototype, skipping `constructor`. Also copies static properties (skipping `length`, `name`, `prototype`, `caller`, `arguments`).
+
+Effect: all existing element instances immediately get new methods via the prototype chain. No need to recreate elements.
+
+### 3.4 CSS Namespace Sync
+
+When CSS changes, Imba generates a new hash → new `_ns_` (e.g., `"z1abc_xy "` → `"z9def_gh "`). The issue:
+
+1. `register$` → `customElements.define` → bimba's hook → `_patchClass` runs
+2. `defineTag` runs AFTER `register$` — sets `_ns_` on the NEW class prototype
+3. But `_patchClass` already ran, so the OLD prototype still has the old `_ns_`
+
+Solution: after `import()` completes, sync `_ns_` manually:
+```js
+oldCls.prototype._ns_ = newCls.prototype._ns_;
+```
+
+Then patch `className` on ALL custom elements in the DOM, replacing old hash parts with new ones.
+
+### 3.5 Always-Destructive HMR
+
+> **History:** Earlier versions (≤0.7.8) had two paths — "stable" (in-place
+> prototype patching + `imba.commit()`) and "shifted" (destructive wipe +
+> re-render). The stable path was meant to preserve DOM state (inputs, focus,
+> popups) when only CSS or logic changed without adding/removing template
+> elements. However, it fundamentally didn't work: imba's reconciliation uses
+> slot-tracking symbols (`this[$sym] === 1`) to skip re-creating elements on
+> re-render. Even when `_patchClass` installs a new `render()` method, calling
+> `render()` (or `imba.commit()`) does nothing — the slot check says "already
+> created" and skips `createElement`. Static text, attributes, and other
+> arguments baked into `createElement` calls never update.
+>
+> Since 0.7.9, bimba always takes the destructive path.
+
+The `slots` field is still computed and broadcast (for potential future use),
+but the client ignores it. Every HMR update does:
+
+1. `_patchClass` updates prototype (during import)
+2. `_ns_` is synced
+3. For each instance of each affected tag:
+   - Save instance properties (`Object.keys(el)`)
+   - Call `disconnectedCallback` on all descendant custom elements
+   - Delete all anonymous Symbol properties (render cache) — skip `Symbol.for(...)` ones
+   - `innerHTML = ''` — wipe DOM
+   - Restore instance properties
+   - `el.render()` — rebuild DOM from scratch with new render method
+   - `el.connectedCallback()`, `el.mount()` — re-initialize
+4. `imba.commit()` for final sync
+
+**Trade-off:** Input focus, scroll position, and popup state are lost on every
+edit. This is acceptable because correctness beats convenience — a "stable"
+update that silently ignores the change is far more confusing than losing
+transient UI state.
+
+### 3.6 Body-level Deduplication
+
+Some modules call `imba.mount(<app-root>)` at top level. Re-importing the module would create a second root element. After each HMR import, bimba checks for new body children with the same tag name as existing ones and removes duplicates.
+
+---
+
+## 4. Server Architecture
+
+```
+serve.js
+├── HMR Client (injected as <script> into HTML)
+│   ├── customElements.define hook
+│   ├── _patchClass / _copyDescriptors
+│   ├── _doUpdate (stable/shifted paths)
+│   ├── WebSocket connection
+│   └── Error overlay
+│
+├── Symbol Stabilization
+│   ├── stabilizeSymbols(js, absPath)
+│   └── Slot count tracking (_prevSlots)
+│
+├── Compiler
+│   ├── compileFile(filepath) — compile + stabilize + cache
+│   ├── _compileCache (abs path → {mtime, result})
+│   └── _prevJs (abs path → js string, for change detection)
+│
+├── Import Graph
+│   ├── extractImports(js, absPath) — scan for .imba imports
+│   ├── updateImportGraph(from, deps) — maintain bidirectional graph
+│   └── _imports / _importers maps
+│
+├── File Watcher
+│   └── watch(srcDir) → compile → broadcast update via WebSocket
+│
+├── HTTP Server
+│   ├── / → HTML with injected import map + HMR client
+│   ├── *.imba → compile on demand → serve as JS
+│   ├── *.css → wrap as JS module (style injection)
+│   ├── /node_modules/* → resolve entry, compile .imba, wrap CJS
+│   └── Static files (htmlDir, then root)
+│
+├── Import Map (minimal, browser-side)
+│   └── bare specifier → /node_modules/pkg/ prefix mapping
+│
+└── Node Modules Resolution (server-side)
+    ├── resolveEntry(pkg.json) — exports/module/browser/main
+    ├── wrapCJS(code) — detect CJS, wrap as ESM
+    └── Extension fallback (.imba → .js → .mjs)
+```
+
+---
+
+## 5. Common Pitfalls and Debugging
+
+### Symptom: Elements duplicate on first edit, not on second
+**Cause:** Symbol cache key mismatch between initial load and HMR. Check that `stabilizeSymbols` receives the same file path from both the HTTP handler and the file watcher. Must use `path.resolve()` for normalization.
+
+### Symptom: CSS changes don't apply after HMR
+**Cause:** `_ns_` not synced. Check the `_nsPatches` logic — `defineTag` sets `_ns_` AFTER `register$`, so `_patchClass` misses it. The post-import sync block must handle this.
+
+### Symptom: Methods don't update after HMR
+**Cause:** `_patchClass` might not be running. Check that `customElements.get(name)` returns the existing class. Verify the hook on `customElements.define` is active.
+
+### Symptom: State lost on edit (inputs clear, popups close)
+**Cause:** Taking the shifted path when stable would suffice. Check slot count — adding a comment or whitespace shouldn't change `Symbol()` count. If it does, the stabilization regex might be too broad/narrow.
+
+### Symptom: 500 errors on node_modules subpaths
+**Cause:** `serveResolved` trying `.imba` extension without existence check. The `.imba` path calls `compileFile()` which throws on non-existent files.
+
+### Debugging approach
+Add to HMR client `_doUpdate`:
+```js
+console.log('[bimba]', file, 'slots=' + slots, 'tags:', collected);
+```
+Check `globalThis.__bimba_syms` in browser console — keys should be absolute paths, values should be objects with `$7`, `$11`, etc. If you see two entries for the same file with different path formats, that's the symbol mismatch bug.

package/README.md

@@ -56,6 +56,8 @@ Duplicate root elements (caused by `imba.mount()` running again on re-import) ar
 
 **Smart HMR:** bimba detects whether a change affects the template structure (adding/removing elements) or just CSS/logic. CSS-only and logic-only changes patch prototypes in place without wiping innerHTML — preserving input focus, scroll position, and open popups. Template-structural changes do a full wipe-and-rerender to ensure correctness.
 
+For a deep dive into how Imba compiles tags, how the render cache works, and how bimba hooks into it — see [INTERNALS.md](INTERNALS.md).
+
 **HTML setup:** add a `data-entrypoint` attribute to the script tag that loads your bundle. The dev server will replace it with your `.imba` entrypoint and inject the importmap above it:
 
 ```html
@@ -80,7 +82,7 @@ Static files are resolved relative to the HTML file's directory first, then from
 
 To compile and bundle your source code from .imba to .js:
 ```bash
-bunx bimba src/index.imba --outdir public/js --minify
+bunx bimba src/index.imba --outdir public/js
 ```
 
 With watch:
@@ -98,7 +100,7 @@ bunx bimba src/index.imba --outdir public/js --watch --clearcache
 
 `--clearcache` — delete the cache directory on exit (Ctrl+C). Works only in watch mode.
 
-`--minify` — minify the output JS. Enabled by default in bundle mode.
+`--no-minify` — disable minification. Bundle mode minifies by default.
 
 `--sourcemap <inline|external|none>` — how to include source maps in the output (default: `none`).
 

package/index.js

@@ -14,7 +14,7 @@ let entrypoint = ''
 
 try {
     const { values, positionals } = parseArgs({
-        args: Bun.argv,
+        args: Bun.argv.slice(2),
         options: {
             watch: { type: 'boolean' },
             outdir: { type: 'string' },
@@ -29,11 +29,12 @@ try {
             port: { type: 'string' },
             html: { type: 'string' },
         },
+        allowNegative: true,
         strict: true,
         allowPositionals: true,
     });
     flags = values;
-    entrypoint = Bun.argv[2];
+    entrypoint = positionals[0] || '';
 }
 catch (error) {
     if (error instanceof Error)
@@ -43,16 +44,21 @@ catch (error) {
     process.exit(0);
 }
 
-// Ensure bunfig.toml exists and contains the required preload line
-const bunfigPath = path.join(process.cwd(), 'bunfig.toml');
-const preloadLine = 'preload = ["bimba-cli/plugin.js"]';
-if (!fs.existsSync(bunfigPath)) {
-    fs.writeFileSync(bunfigPath, preloadLine + '\n');
-} else {
-    const content = fs.readFileSync(bunfigPath, 'utf8');
-    if (!content.includes(preloadLine)) {
-        fs.appendFileSync(bunfigPath, (content.endsWith('\n') ? '' : '\n') + preloadLine + '\n');
+function ensureBunfigPreload() {
+    const bunfigPath = path.join(process.cwd(), 'bunfig.toml');
+    const preloadLine = 'preload = ["bimba-cli/plugin.js"]';
+
+    if (!fs.existsSync(bunfigPath)) {
+        console.log(theme.action("note: ") + theme.filename("bunfig.toml was not found, so bimba left it unchanged."));
+        console.log(theme.action("      ") + `Add ${theme.flags(preloadLine)} manually if you want Bun to preload the plugin.`);
+        return;
     }
+
+    const content = fs.readFileSync(bunfigPath, 'utf8');
+    if (content.includes(preloadLine)) return;
+
+    console.log(theme.action("note: ") + theme.filename("bunfig.toml already exists, so bimba did not edit it automatically."));
+    console.log(theme.action("      ") + `Add ${theme.flags(preloadLine)} manually if you want Bun to preload the plugin.`);
 }
 
 // help: more on bun building params here: https://bun.sh/docs/bundler
@@ -62,7 +68,7 @@ if(flags.help) {
     console.log("For example like this: "+theme.filedir('bimba file.imba --outdir public'));
     console.log("");
     console.log("   "+theme.flags('--outdir <folder>')+"                     Compile imba files to the specified folder");
-    console.log("   "+theme.flags('--minify')+"                              Minify compiled .js files");
+    console.log("   "+theme.flags('--no-minify')+"                           Disable minification for compiled .js files");
     console.log("   "+theme.flags('--sourcemap <inline|external|none>')+"    How should sourcemap files be included in the .js");
     console.log("   "+theme.flags('--target <browser|node>')+"               Target platform for both Imba compiler and Bun bundler");
     console.log("   "+theme.flags('--external <package>')+"                Exclude package from bundle (repeatable, e.g. --external ws --external node-pty)");
@@ -88,6 +94,7 @@ if (flags.serve) {
         console.log("");
         process.exit(1);
     }
+    ensureBunfigPreload();
     serve(entrypoint, { port: parseInt(flags.port) || 5200, html: flags.html });
 }
 // no entrypoint or outdir
@@ -100,7 +107,9 @@ else if(!entrypoint || !flags.outdir) {
 }
 // build
 else {
-    bundle();
+    ensureBunfigPreload();
+    const success = await bundle();
+    if (!success && !flags.watch) process.exit(1);
     watch(bundle);
 }
 
@@ -126,7 +135,7 @@ async function bundle() {
 
     if (!fs.existsSync(entrypoint)) {
         console.log(theme.failure('Error.') + ` The specified entrypoint does not exist: ${theme.filedir(entrypoint)}`);
-        process.exit(0);
+        return false;
     }
 
     stats.failed = 0
@@ -150,7 +159,7 @@ async function bundle() {
             outdir: flags.outdir,
             target: buildTarget,
             sourcemap: flags.sourcemap || 'none',
-            minify: true,
+            minify: flags.minify ?? true,
             splitting: flags.splitting || false,
             plugins: [imbaPlugin]
         };
@@ -182,6 +191,8 @@ async function bundle() {
                 console.log(log);
             }
         }
+
+        return result.success && !stats.failed && !stats.errors;
     }
     catch(error) {
         console.log(theme.folder("──────────────────────────────────────────────────────────────────────"));
@@ -189,8 +200,9 @@ async function bundle() {
         console.log(error)
         console.log(theme.folder("──────────────────────────────────────────────────────────────────────"));
         console.log(theme.failure(" Failure ") + theme.filename(' Bun found an error in the compiled JS file'))
+        return false;
     }
     finally {
         bundling = false;
     };
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bimba-cli",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/HeapVoid/bimba.git"
@@ -19,4 +19,4 @@
   "devDependencies": {
     "imba": "latest"
   }
-}
+}

package/serve.js

@@ -1,6 +1,6 @@
-import { serve as bunServe } from 'bun'
+import { serve as bunServe, Glob } from 'bun'
 import * as compiler from 'imba/compiler'
-import { watch, existsSync } from 'fs'
+import { watch, existsSync, statSync } from 'fs'
 import path from 'path'
 import { theme } from './utils.js'
 import { printerr } from './plugin.js'
@@ -137,28 +137,27 @@ const hmrClient = `
 		}
 
 		// Destructive HMR: wipe inner DOM and re-render each collected tag.
-		// Skip when slots === 'stable' — template structure unchanged (CSS-only
-		// or logic-only edit that didn't add/remove elements), so wiping innerHTML
-		// would destroy DOM state (inputs, focus, popups) for nothing.
-		// _patchClass already ran above, so methods are up-to-date either way.
-		if (slots !== 'stable') {
-			for (const tag of collected) {
-				const els = document.querySelectorAll(tag);
-				els.forEach(el => {
-					const state = {};
-					for (const k of Object.keys(el)) state[k] = el[k];
-					_disconnectDescendants(el);
-					for (const sym of Object.getOwnPropertySymbols(el)) {
-						if (Symbol.keyFor(sym) !== undefined) continue;
-						try { delete el[sym]; } catch(_) {}
-					}
-					el.innerHTML = '';
-					Object.assign(el, state);
-					try { el.render && el.render(); } catch(e) { console.error('[bimba] render error:', e); }
-					try { el.connectedCallback && el.connectedCallback(); } catch(_) {}
-					try { el.mount && el.mount(); } catch(_) {}
-				});
-			}
+		// Always destructive regardless of slots value. Imba's reconciliation
+		// uses slot-tracking symbols (this[$sym] === 1) to skip re-creating
+		// elements on re-render. Even "stable" edits (static text, attributes)
+		// won't apply unless we clear those symbols and force a fresh render.
+		// _patchClass already ran above, so the new render() method is in place.
+		for (const tag of collected) {
+			const els = document.querySelectorAll(tag);
+			els.forEach(el => {
+				const state = {};
+				for (const k of Object.keys(el)) state[k] = el[k];
+				_disconnectDescendants(el);
+				for (const sym of Object.getOwnPropertySymbols(el)) {
+					if (Symbol.keyFor(sym) !== undefined) continue;
+					try { delete el[sym]; } catch(_) {}
+				}
+				el.innerHTML = '';
+				Object.assign(el, state);
+				try { el.render && el.render(); } catch(e) { console.error('[bimba] render error:', e); }
+				try { el.connectedCallback && el.connectedCallback(); } catch(_) {}
+				try { el.mount && el.mount(); } catch(_) {}
+			});
 		}
 
 		if (typeof imba !== 'undefined') imba.commit();
@@ -257,57 +256,6 @@ const _compileCache = new Map()  // filepath → { mtime, result }
 const _prevJs = new Map()  // filepath → compiled js — for change detection
 const _prevSlots = new Map()  // filepath → previous symbol slot count
 
-// ─── Import dependency graph ──────────────────────────────────────────────────
-//
-// When a non-tag module (utility functions, constants, shared state) is edited,
-// the existing class-prototype patching does nothing for the modules that
-// imported it — they hold their own captured references. To make those
-// updates flow into the UI, we track who imports whom and, on every change,
-// re-broadcast updates for the transitive importer set. The client's existing
-// HMR queue then re-imports each in turn; their top-level code reruns, picks
-// up the new symbols, and any tag re-registrations patch instances in place.
-//
-// Keys are absolute, normalized paths (path.resolve). Edges are added during
-// compilation by scanning the produced JS for relative .imba imports.
-
-const _imports = new Map()    // absFile → Set<absFile> (what it imports)
-const _importers = new Map()  // absFile → Set<absFile> (who imports it)
-
-function extractImports(js, fromAbs) {
-	const dir = path.dirname(fromAbs)
-	const out = new Set()
-	const re = /(?:^|[\s;])(?:import|from)\s*['"]([^'"]+)['"]/g
-	let m
-	while ((m = re.exec(js))) {
-		const spec = m[1]
-		if (!spec.startsWith('.') && !spec.startsWith('/')) continue
-		if (!spec.endsWith('.imba')) continue
-		const resolved = spec.startsWith('/')
-			? path.resolve('.' + spec)
-			: path.resolve(dir, spec)
-		out.add(resolved)
-	}
-	return out
-}
-
-function updateImportGraph(fromAbs, newDeps) {
-	const old = _imports.get(fromAbs)
-	if (old) {
-		for (const d of old) {
-			if (newDeps.has(d)) continue
-			const set = _importers.get(d)
-			if (set) { set.delete(fromAbs); if (!set.size) _importers.delete(d) }
-		}
-	}
-	for (const d of newDeps) {
-		let set = _importers.get(d)
-		if (!set) { set = new Set(); _importers.set(d, set) }
-		set.add(fromAbs)
-	}
-	_imports.set(fromAbs, newDeps)
-}
-
-
 // Imba compiles tag render-cache slots as anonymous local Symbols at module top
 // level: `var $4 = Symbol(), $11 = Symbol(), ...; let c$0 = Symbol();`. Each
 // re-import of the file creates fresh Symbol objects, so old slot data on live
@@ -374,7 +322,6 @@ async function compileFile(filepath) {
 		const prev = _prevSlots.get(abs)
 		result.slots = (prev === undefined || prev === slotCount) ? 'stable' : 'shifted'
 		_prevSlots.set(abs, slotCount)
-		updateImportGraph(abs, extractImports(js, abs))
 	}
 
 	// Bake errors as an own property so caching/spreading preserves them.
@@ -409,69 +356,306 @@ async function readPkgJson(pkgDir) {
 	}
 }
 
-// Wrap a CommonJS file as an ESM module so the browser can import it.
-// Detects CJS by checking for `module.exports` or top-level `exports.` usage.
-function wrapCJS(code) {
-	if (!code.includes('module.exports') && !code.includes('exports.')) return null
-	// Already has ESM syntax — don't wrap (dual-format files)
-	if (/^\s*(export\s|import\s)/m.test(code)) return null
-	return `var module = { exports: {} }, exports = module.exports;\n${code}\nexport default module.exports;\nexport { module };`
+function toPosix(filepath) {
+	return filepath.replaceAll('\\', '/')
+}
+
+function toBrowserPath(filepath) {
+	return '/' + toPosix(path.relative(process.cwd(), path.resolve(filepath)))
 }
 
-// Resolve the ESM entry point for an npm package.
-// Priority: exports["."].import → exports["."].default → module → main
-function resolveEntry(depPkg) {
-	const exp = depPkg.exports;
-	if (exp) {
-		// exports: "./index.js" (string shorthand)
-		if (typeof exp === 'string') return exp;
-		// exports: { ".": { "import": "...", "default": "..." } }
-		const dot = exp['.'];
-		if (dot) {
-			if (typeof dot === 'string') return dot;
-			if (dot.import) return dot.import;
-			if (dot.default) return dot.default;
+function parsePackageSpecifier(specifier) {
+	if (specifier.startsWith('@')) {
+		const parts = specifier.split('/')
+		return {
+			name: parts.slice(0, 2).join('/'),
+			subpath: parts.slice(2).join('/'),
 		}
-		// exports: { "import": "...", "default": "..." } (no "." wrapper)
-		if (exp.import) return exp.import;
-		if (exp.default) return exp.default;
 	}
-	// Fallback to legacy fields
-	return depPkg.module || depPkg.browser || depPkg.main;
+
+	const [name, ...rest] = specifier.split('/')
+	return { name, subpath: rest.join('/') }
 }
 
-// Build an ES import map from package.json dependencies.
-// The import map is intentionally simple — it just maps bare specifiers
-// to /node_modules/ URLs. All the smart resolution (conditional exports,
-// CJS→ESM, entry points, extensions) happens on the server side.
-async function buildImportMap() {
-	const imports = {
-		'imba/runtime': 'https://esm.sh/imba/runtime',
-		'imba': 'https://esm.sh/imba',
-	};
+function isConditionMap(value) {
+	return !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(key => !key.startsWith('.'))
+}
+
+function pickExportTarget(value) {
+	if (!value) return null
+	if (typeof value === 'string') return value
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			const resolved = pickExportTarget(item)
+			if (resolved) return resolved
+		}
+		return null
+	}
+	if (!isConditionMap(value)) return null
+
+	for (const key of ['browser', 'import', 'default', 'module']) {
+		const resolved = pickExportTarget(value[key])
+		if (resolved) return resolved
+	}
+
+	for (const nested of Object.values(value)) {
+		const resolved = pickExportTarget(nested)
+		if (resolved) return resolved
+	}
+
+	return null
+}
+
+function resolveExportTarget(exportsField, subpath = '') {
+	if (!exportsField) return null
+	const exportKey = subpath ? `./${subpath}` : '.'
+
+	if (typeof exportsField === 'string' || Array.isArray(exportsField) || isConditionMap(exportsField)) {
+		return exportKey === '.' ? pickExportTarget(exportsField) : null
+	}
+
+	const exact = exportsField[exportKey]
+	if (exact) return pickExportTarget(exact)
+
+	let bestMatch = null
+	for (const [key, value] of Object.entries(exportsField)) {
+		if (!key.startsWith('./') || !key.includes('*')) continue
+
+		const [prefix, suffix] = key.split('*')
+		if (!exportKey.startsWith(prefix) || !exportKey.endsWith(suffix)) continue
+
+		const matched = exportKey.slice(prefix.length, exportKey.length - suffix.length)
+		const target = pickExportTarget(value)
+		if (!target) continue
+
+		const score = prefix.length + suffix.length
+		if (!bestMatch || score > bestMatch.score) {
+			bestMatch = { matched, target, score }
+		}
+	}
+
+	return bestMatch ? bestMatch.target.replaceAll('*', bestMatch.matched) : null
+}
+
+function resolvePackageTarget(depPkg, subpath = '') {
+	if (subpath) {
+		const exported = resolveExportTarget(depPkg.exports, subpath)
+		if (exported) return exported
+		if (depPkg.exports) return null
+		return './' + subpath
+	}
+
+	const exported = resolveExportTarget(depPkg.exports)
+	if (exported) return exported
+	if (typeof depPkg.browser === 'string') return depPkg.browser
+	return depPkg.module || depPkg.main || null
+}
+
+function resolveFileCandidate(filepath) {
+	const candidates = [
+		filepath,
+		filepath + '.js',
+		filepath + '.mjs',
+		filepath + '.cjs',
+		filepath + '.imba',
+		filepath + '.css',
+		path.join(filepath, 'index.js'),
+		path.join(filepath, 'index.mjs'),
+		path.join(filepath, 'index.cjs'),
+		path.join(filepath, 'index.imba'),
+	]
+
+	for (const candidate of candidates) {
+		if (!existsSync(candidate)) continue
+		try {
+			if (statSync(candidate).isFile()) return candidate
+		} catch (_) {
+			// ignore vanished files and continue resolving
+		}
+	}
+
+	return null
+}
+
+async function resolvePackageFile(specifier) {
+	const { name, subpath } = parsePackageSpecifier(specifier)
+	if (!name) return null
+
+	const pkgDir = path.join(process.cwd(), 'node_modules', name)
+	const depPkg = await readPkgJson(pkgDir)
+	if (!depPkg) return null
+
+	const target = resolvePackageTarget(depPkg, subpath)
+	if (!target) return null
+
+	const candidate = resolveFileCandidate(path.resolve(pkgDir, target))
+	return candidate ? path.resolve(candidate) : null
+}
+
+async function resolveNodeModulesRequest(pathname) {
+	const specifier = pathname.replace(/^\/node_modules\//, '')
+	if (!specifier) return null
+
+	const direct = resolveFileCandidate(path.join(process.cwd(), 'node_modules', specifier))
+	if (direct) return path.resolve(direct)
+
+	return resolvePackageFile(specifier)
+}
+
+function exportSpecifiers(name, exportsField) {
+	if (!exportsField || typeof exportsField === 'string' || Array.isArray(exportsField) || isConditionMap(exportsField)) {
+		return []
+	}
+
+	return Object.entries(exportsField)
+		.filter(([key]) => key.startsWith('./') && key !== '.')
+		.map(([key, value]) => ({ key, value }))
+}
+
+async function expandPatternExport(name, pkgDir, key, value) {
+	const target = pickExportTarget(value)
+	if (!target || !key.includes('*') || !target.includes('*')) return {}
+
+	const specPattern = key.slice(2)
+	const [specPrefix, specSuffix] = specPattern.split('*')
+	const normalizedTarget = target.replace(/^\.\//, '')
+	const [targetPrefix, targetSuffix] = normalizedTarget.split('*')
+	const glob = new Glob(normalizedTarget)
+	const mappings = {}
+
+	for await (const file of glob.scan(pkgDir)) {
+		const rel = toPosix(file)
+		if (!rel.startsWith(targetPrefix) || !rel.endsWith(targetSuffix)) continue
+
+		const matched = rel.slice(targetPrefix.length, rel.length - targetSuffix.length)
+		const specifier = `${name}/${specPrefix}${matched}${specSuffix}`.replace(/\/+/g, '/')
+		mappings[specifier] = '/' + toPosix(path.join('node_modules', name, rel))
+	}
+
+	return mappings
+}
+
+async function buildGeneratedImportMap() {
+	const imports = {}
+	const visited = new Set()
+	const queue = []
+
 	try {
-		const pkg = JSON.parse(await Bun.file('./package.json').text());
-		for (const [name] of Object.entries(pkg.dependencies || {})) {
-			if (name === 'imba') continue;
-			imports[name] = `/node_modules/${name}/`;
-			imports[name + '/'] = `/node_modules/${name}/`;
+		const pkg = JSON.parse(await Bun.file('./package.json').text())
+		for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+			queue.push(...Object.keys(pkg[field] || {}))
 		}
 	} catch(_) { /* no package.json */ }
 
-	return `\t\t<script type="importmap">\n\t\t\t${JSON.stringify({ imports }, null, '\t\t\t\t')}\n\t\t</script>`;
+	while (queue.length) {
+		const name = queue.shift()
+		if (!name || visited.has(name)) continue
+		visited.add(name)
+
+		const pkgDir = path.join(process.cwd(), 'node_modules', name)
+		const depPkg = await readPkgJson(pkgDir)
+		if (!depPkg) continue
+
+		const entryFile = await resolvePackageFile(name)
+		if (entryFile) imports[name] = toBrowserPath(entryFile)
+
+		if (depPkg.exports) {
+			for (const { key, value } of exportSpecifiers(name, depPkg.exports)) {
+				if (key.includes('*')) {
+					Object.assign(imports, await expandPatternExport(name, pkgDir, key, value))
+					continue
+				}
+
+				const specifier = `${name}/${key.slice(2)}`
+				const file = await resolvePackageFile(specifier)
+				if (file) imports[specifier] = toBrowserPath(file)
+			}
+		} else {
+			imports[name + '/'] = '/' + toPosix(path.join('node_modules', name)) + '/'
+		}
+
+		for (const field of ['dependencies', 'peerDependencies', 'optionalDependencies']) {
+			queue.push(...Object.keys(depPkg[field] || {}))
+		}
+	}
+
+	if (!imports['imba']) imports['imba'] = 'https://esm.sh/imba'
+	if (!imports['imba/runtime']) imports['imba/runtime'] = 'https://esm.sh/imba/runtime'
+
+	return { imports }
+}
+
+function extractUserImportMap(html) {
+	const merged = { imports: {}, scopes: {} }
+
+	html = html.replace(/<script\s+type=["']importmap["'][^>]*>([\s\S]*?)<\/script>/gi, (_match, json) => {
+		try {
+			const parsed = JSON.parse(json)
+			Object.assign(merged.imports, parsed.imports || {})
+			for (const [scope, specifiers] of Object.entries(parsed.scopes || {})) {
+				merged.scopes[scope] = { ...(merged.scopes[scope] || {}), ...specifiers }
+			}
+		} catch (_) {
+			// ignore invalid import maps and keep serving the page
+		}
+		return ''
+	})
+
+	if (!Object.keys(merged.scopes).length) delete merged.scopes
+	return { html, importMap: merged }
+}
+
+function mergeImportMaps(generated, user) {
+	const merged = {
+		imports: { ...(generated.imports || {}), ...(user.imports || {}) },
+	}
+
+	const scopeKeys = new Set([
+		...Object.keys(generated.scopes || {}),
+		...Object.keys(user.scopes || {}),
+	])
+
+	if (scopeKeys.size) {
+		merged.scopes = {}
+		for (const key of scopeKeys) {
+			merged.scopes[key] = {
+				...((generated.scopes || {})[key] || {}),
+				...((user.scopes || {})[key] || {}),
+			}
+		}
+	}
+
+	return merged
+}
+
+function renderImportMapTag(importMap) {
+	return `\t\t<script type="importmap">\n\t\t\t${JSON.stringify(importMap, null, '\t\t\t\t')}\n\t\t</script>`
+}
+
+// Wrap a CommonJS file as an ESM module so the browser can import it.
+// Detects CJS by checking for `module.exports` or top-level `exports.` usage.
+function wrapCJS(code) {
+	if (!code.includes('module.exports') && !code.includes('exports.')) return null
+	// Already has ESM syntax — don't wrap (dual-format files)
+	if (/^\s*(export\s|import\s)/m.test(code)) return null
+	return `var module = { exports: {} }, exports = module.exports;\n${code}\nexport default module.exports;\nexport { module };`
 }
 
 // Rewrite production HTML for the dev server:
-// strips existing importmap + data-entrypoint script, injects importmap +
+// strips existing importmap + data-entrypoint script, injects merged importmap +
 // entrypoint module + HMR client before </head>.
-function transformHtml(html, entrypoint, importMapTag) {
-	html = html.replace(/<script\s+type=["']importmap["'][^>]*>[\s\S]*?<\/script>/gi, '');
-	html = html.replace(/<script([^>]*)\bdata-entrypoint\b([^>]*)><\/script>/gi, '');
-	const entryUrl = '/' + entrypoint.replace(/^\.\//, '').replaceAll('\\', '/');
+function transformHtml(html, entrypoint, generatedImportMap) {
+	const extracted = extractUserImportMap(html)
+	html = extracted.html
+	html = html.replace(/<script([^>]*)\bdata-entrypoint\b([^>]*)><\/script>/gi, '')
+
+	const entryUrl = '/' + entrypoint.replace(/^\.\//, '').replaceAll('\\', '/')
+	const importMapTag = renderImportMapTag(mergeImportMaps(generatedImportMap, extracted.importMap))
+
 	html = html.replace('</head>',
 		`${importMapTag}\n\t\t<script type='module' src='${entryUrl}'></script>\n${hmrClient}\n\t</head>`
-	);
-	return html;
+	)
+	return html
 }
 
 // ─── Dev server ───────────────────────────────────────────────────────────────
@@ -482,7 +666,7 @@ export function serve(entrypoint, flags) {
 	const htmlDir  = path.dirname(htmlPath)
 	const srcDir   = path.dirname(entrypoint)
 	const sockets  = new Set()
-	let importMapTag = null
+	let generatedImportMap = null
 
 	// ── Status line (prints current compile result, fades out on success) ──────
 
@@ -602,15 +786,15 @@ export function serve(entrypoint, flags) {
 				if (server.upgrade(req)) return undefined
 			}
 
-			// HTML: index or any .html file
-			if (pathname === '/' || pathname.endsWith('.html')) {
-				const htmlFile = pathname === '/' ? htmlPath : '.' + pathname
-				let html = await Bun.file(htmlFile).text()
-				if (!importMapTag) importMapTag = await buildImportMap()
-				return new Response(transformHtml(html, entrypoint, importMapTag), {
-					headers: { 'Content-Type': 'text/html' },
-				})
-			}
+				// HTML: index or any .html file
+				if (pathname === '/' || pathname.endsWith('.html')) {
+					const htmlFile = pathname === '/' ? htmlPath : '.' + pathname
+					let html = await Bun.file(htmlFile).text()
+					if (!generatedImportMap) generatedImportMap = await buildGeneratedImportMap()
+					return new Response(transformHtml(html, entrypoint, generatedImportMap), {
+						headers: { 'Content-Type': 'text/html' },
+					})
+				}
 
 			// Imba files: compile on demand and serve as JS
 			if (pathname.endsWith('.imba')) {
@@ -654,15 +838,14 @@ export function serve(entrypoint, flags) {
 				}
 			}
 
-			// node_modules: entry point resolution, .imba compilation, CJS→ESM wrapping.
-			// The import map just maps bare specifiers to /node_modules/pkg/ URLs.
-			// All smart resolution happens here at request time.
-			if (pathname.startsWith('/node_modules/')) {
-				const filepath = '.' + pathname
-
-				// Serve a resolved file: compile .imba, wrap CJS as ESM, pass ESM through
-				const serveResolved = async (filePath) => {
-					if (filePath.endsWith('.imba')) {
+				// node_modules: entry point resolution, .imba compilation, CJS→ESM wrapping.
+				// The import map points to concrete module URLs when possible, but we
+				// still resolve package-style /node_modules/pkg[/subpath] requests here
+				// so user-defined import maps and manual URLs keep working.
+				if (pathname.startsWith('/node_modules/')) {
+					// Serve a resolved file: compile .imba, wrap CJS as ESM, pass ESM through
+					const serveResolved = async (filePath) => {
+						if (filePath.endsWith('.imba')) {
 						const f = Bun.file(filePath)
 						if (!(await f.exists())) return null
 						const out = await compileFile(filePath)
@@ -672,41 +855,14 @@ export function serve(entrypoint, flags) {
 					const f = Bun.file(filePath)
 					if (!(await f.exists())) return null
 					const code = await f.text()
-					const wrapped = wrapCJS(code)
-					return new Response(wrapped || code, { headers: { 'Content-Type': 'application/javascript' } })
-				}
-
-				// Resolve entry point for root package requests (/node_modules/pkg/ or /node_modules/pkg)
-				const parts = pathname.slice(1).split('/')  // ['node_modules', 'pkg', ...]
-				const isScoped = parts[1]?.startsWith('@')
-				const pkgParts = isScoped ? 3 : 2  // node_modules/@scope/pkg or node_modules/pkg
-				const subParts = parts.slice(pkgParts)
-				const isRootRequest = subParts.length === 0 || (subParts.length === 1 && subParts[0] === '')
-
-				if (isRootRequest) {
-					const pkgDir = './' + parts.slice(0, pkgParts).join('/')
-					const depPkg = await readPkgJson(pkgDir)
-					if (depPkg) {
-						const entry = resolveEntry(depPkg)
-						if (entry) {
-							const resp = await serveResolved(path.join(pkgDir, entry))
-							if (resp) return resp
-						}
+						const wrapped = wrapCJS(code)
+						return new Response(wrapped || code, { headers: { 'Content-Type': 'application/javascript' } })
 					}
-				}
-
-				// Subpath: try the exact path, then with extensions
-				const resp = await serveResolved(filepath)
-				if (resp) return resp
 
-				// Extensionless: try .imba, .js, .mjs
-				if (!filepath.includes('.', filepath.lastIndexOf('/') + 1)) {
-					for (const ext of ['.imba', '.js', '.mjs']) {
-						const resp = await serveResolved(filepath + ext)
-						if (resp) return resp
-					}
+					const resolved = await resolveNodeModulesRequest(pathname)
+					const resp = resolved ? await serveResolved(resolved) : null
+					if (resp) return resp
 				}
-			}
 
 			// Static files: check htmlDir first (for assets relative to HTML), then root
 			const inHtmlDir = Bun.file(path.join(htmlDir, pathname))
@@ -732,13 +888,13 @@ export function serve(entrypoint, flags) {
 			}
 
 			// SPA fallback for extension-less paths
-			if (!lastSegment.includes('.')) {
-				let html = await Bun.file(htmlPath).text()
-				if (!importMapTag) importMapTag = await buildImportMap()
-				return new Response(transformHtml(html, entrypoint, importMapTag), {
-					headers: { 'Content-Type': 'text/html' },
-				})
-			}
+				if (!lastSegment.includes('.')) {
+					let html = await Bun.file(htmlPath).text()
+					if (!generatedImportMap) generatedImportMap = await buildGeneratedImportMap()
+					return new Response(transformHtml(html, entrypoint, generatedImportMap), {
+						headers: { 'Content-Type': 'text/html' },
+					})
+				}
 
 			return new Response('Not Found', { status: 404 })
 		},