bimba-cli 0.7.8 → 0.7.9

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bimba-cli",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/HeapVoid/bimba.git"

package/serve.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();