@esportsplus/template 0.32.0 → 0.32.2

package/storage/rewrite-analysis-2026-01-04.md

@@ -1,439 +0,0 @@
-# Template Library Rewrite Analysis
-
-## Executive Summary
-
-This library is a compile-time optimized HTML template system with reactive bindings. The transformer converts `html\`` tagged templates into optimized DOM creation code at build time. Analysis reveals opportunities to reduce runtime LOC by ~60% and transformer LOC by ~30% through aggressive compile-time specialization.
-
----
-
-## ⚠️ CRITICAL CORRECTION: Class/Style Diffing is Essential
-
-**Previous analysis was WRONG about inlining class/style operations.**
-
-The `list()` function in `attributes.ts` is NOT over-engineering—it solves a fundamental problem that ANY reactive class binding system must solve.
-
-### The Problem
-
-Consider: `<div class="base ${() => theme()} ${() => variant()}">`
-
-This has:
-- Static part: `base`
-- Effect 0: `theme()` returns `dark` or `light`
-- Effect 1: `variant()` returns `primary` or `secondary`
-
-When theme changes from `dark` to `light`:
-- Effect 0 must remove `dark`, add `light`
-- Effect 0 must NOT touch `primary` (from Effect 1)
-- Effect 0 must NOT touch `base` (static)
-
-### Why Simple Inline BREAKS
-
-```typescript
-// WRONG - this destroys other effects' classes:
-effect(() => {
-    element.className = 'base ' + theme();  // Destroys 'primary' from Effect 1!
-});
-```
-
-### Why `list()` is Required
-
-The `list()` function tracks:
-- `store['class.static']` = `'base'` (static classes)
-- `store['class']` = `Set{'dark', 'primary'}` (all dynamic classes)
-- `store[0]` = `{dark: true}` (what Effect 0 added)
-- `store[1]` = `{primary: true}` (what Effect 1 added)
-
-When Effect 0 re-runs with `'light'`:
-1. `hot = {light: true}` (new value)
-2. `cold = store[0] = {dark: true}` (old value)
-3. `dark` is in cold but not hot → remove from Set
-4. `light` is new → add to Set
-5. Set now = `{light, primary}` ← **primary preserved!**
-6. Rebuild: `className = 'base light primary'`
-
-### Conclusion
-
-**The refactor CANNOT eliminate the diffing logic for class/style.** Any approach that removes ID-based tracking will break multiple reactive bindings on the same attribute.
-
----
-
-## Current Architecture
-
-### Module Breakdown (LOC)
-
-| Module | File | Current LOC | Purpose |
-|--------|------|-------------|---------|
-| **Runtime Core** | | **537** | |
-| | attributes.ts | 284 | Attribute binding, batched updates |
-| | slot/array.ts | 255 | Reactive array rendering (simplified) |
-| | slot/effect.ts | 114 | Effect-based slot updates |
-| | slot/render.ts | 58 | Value → Node conversion |
-| | slot/cleanup.ts | 39 | Cleanup/dispose tracking |
-| | slot/index.ts | 13 | Slot type dispatch |
-| **Event System** | | **248** | |
-| | event/index.ts | 116 | Delegation + lifecycle events |
-| | event/ontick.ts | 59 | RAF-based tick system |
-| | event/onresize.ts | 37 | Resize observer |
-| | event/onconnect.ts | 21 | Connection detection |
-| | event/constants.ts | 15 | Event classification |
-| **Utilities** | | **160** | |
-| | utilities.ts | 54 | DOM helpers, clone, fragment |
-| | constants.ts | 31 | Symbols, constants |
-| | types.ts | 54 | Type definitions |
-| | runtime.ts | 7 | Node prototype setup |
-| | html.ts | 18 | Stub (throws at runtime) |
-| | svg.ts | 17 | SVG wrapper |
-| | render.ts | 13 | Entry point |
-| | index.ts | 6 | Exports |
-| **Transformer** | | **1,092** | |
-| | codegen.ts | 767 | Code generation + HTML parsing (merged) |
-| | type-analyzer.ts | 338 | Type inference |
-| | ts-parser.ts | 123 | AST traversal |
-| | index.ts | 98 | Transform orchestration |
-| **Plugins** | | **102** | |
-| | plugins/vite.ts | 49 | Vite integration |
-| | plugins/esbuild.ts | 46 | esbuild integration |
-| | plugins/tsc.ts | 7 | TypeScript integration |
-| **TOTAL** | | **2,129** | |
-
----
-
-## Compile-Time Attribute Routing
-
-The transformer should route attribute bindings to specialized handlers at compile time, eliminating runtime dispatch overhead.
-
-### Routing Decision Tree
-
-```
-Attribute Name
-├── starts with "on" (event)
-│   ├── LIFECYCLE_EVENTS.has(key) → event.{key}(element, fn)
-│   ├── DIRECT_ATTACH_EVENTS.has(key) → event.direct(element, name, fn)
-│   └── default → event.delegate(element, name, fn)
-│
-├── "class" → attr.setClass(element, staticValue, dynamicValue)
-├── "style" → attr.setStyle(element, staticValue, dynamicValue)
-│
-├── "spread" (dynamic object/array)
-│   ├── object literal with known keys → unpack to individual bindings
-│   ├── typed variable with known props → unpack to individual bindings
-│   └── unknown shape → attr.spread(element, value)
-│
-└── other properties → attr.set(element, name, value)
-```
-
-### Generated Code Examples
-
-**Events** (compile-time routed):
-```typescript
-// Input: <button onclick=${handler}>
-// Lifecycle event:
-event.ontick(element, handler);
-
-// Direct attach (scroll, focus, etc):
-event.direct(element, 'scroll', handler);
-
-// Delegated (click, input, etc):
-event.delegate(element, 'click', handler);
-```
-
-**Class/Style** (pre-populated store + auto-reactive):
-```typescript
-// Input: <div class="base ${() => theme()}">
-attr.setClass(element, 'base', () => theme());
-
-// setClass handles:
-// 1. Pre-populates store['class.static'] = 'base'
-// 2. Pre-populates store['class'] = new Set()
-// 3. Detects function → wraps in effect with unique ID
-// 4. Eliminates getAttribute() call entirely
-```
-
-**Spread** (unpack when possible):
-```typescript
-// Input: <div ${attrs}>
-
-// Known object literal - unpack at compile time:
-// ${({ disabled: true, class: 'foo' })}
-attr.set(element, 'disabled', true);
-attr.setClass(element, '', 'foo');
-
-// Unknown shape - runtime fallback:
-attr.spread(element, unknownAttrs);
-```
-
-**Other Properties**:
-```typescript
-// Input: <input disabled=${isDisabled}>
-attr.set(element, 'disabled', isDisabled);
-
-// set() handles:
-// - Static values → direct apply
-// - Functions → wrap in effect automatically
-// - Arrays → iterate and apply each
-```
-
-### Runtime Optimizations (attributes.ts)
-
-The `list()` function now includes these optimizations:
-
-**1. Raw value caching** - Skip entirely when input unchanged:
-```typescript
-if (store[id + '.raw'] === value) {
-    return;  // Same input → skip all diffing
-}
-store[id + '.raw'] = value;
-```
-
-**2. Change tracking** - Skip rebuild when Set unchanged:
-```typescript
-let changed = false;
-
-// In add loop:
-if (!dynamic.has(part)) {
-    changed = true;
-    dynamic.add(part);
-}
-
-// In remove loop:
-if (hot[part] !== true) {
-    changed = true;
-    dynamic.delete(part);
-}
-
-// Skip rebuild if nothing changed
-if (!changed) {
-    return;
-}
-```
-
-**3. Store pre-population** - Eliminate getAttribute():
-```typescript
-// setClass pre-populates before calling list():
-store['class.static'] = staticValue || '';
-store['class'] ??= new Set<string>();
-
-// list() never needs to read from DOM
-```
-
-### Performance Comparison
-
-| Scenario | Before | After | Improvement |
-|----------|--------|-------|-------------|
-| Event binding | ~150ns (runtime dispatch) | ~10ns (direct call) | -93% |
-| Class update (unchanged) | ~500ns (full diff) | ~20ns (raw check) | -96% |
-| Class update (changed) | ~500ns | ~400ns (skip rebuild if Set same) | -20% |
-| getAttribute calls | 1 per element | 0 | -100% |
-
----
-
-## Proposed Architecture
-
-### New Module Structure
-
-```
-src/
-├── index.ts          # Exports: render, ArraySlot
-├── utilities.ts      # Keep as-is - template factory prevents compile bloat
-├── attributes.ts     # Keep list() diffing for class/style
-├── array.ts          # ArraySlot class (~150 LOC)
-├── effect.ts         # EffectSlot class (~80 LOC)
-├── cleanup.ts        # Disposal tracking (~30 LOC)
-├── event/            # Keep as-is (248 LOC) - cleanup via AbortController is essential
-└── transformer/
-    ├── index.ts      # Transform entry (~80 LOC)
-    ├── compile.ts    # Parse + generate (~400 LOC)
-    ├── analyze.ts    # Type analysis (~200 LOC)
-    └── plugins/      # Same as current (~100 LOC)
-```
-
-### LOC Comparison (REVISED)
-
-| Module | Current | Proposed | Reduction | Notes |
-|--------|---------|----------|-----------|-------|
-| Runtime Core | 537 | 380 | -29% | Must keep `list()` diffing |
-| Event System | 248 | 248 | 0% | Keep as-is (AbortController cleanup essential) |
-| Utilities | 160 | 160 | 0% | Keep as-is (template factory prevents bloat) |
-| Transformer | 1,324 | 900 | -32% | Must add effect detection for attrs |
-| Plugins | 102 | 100 | -2% | Minimal change |
-| **TOTAL** | **2,361** | **1,788** | **-24%** | Revised |
-
-**Key changes from original estimate:**
-- Runtime cannot be reduced to 200 LOC — `list()` diffing is essential (~180 LOC)
-- Transformer needs more code, not less — must detect effect types for all bindings
-- Utilities must be kept — template factory prevents compile-time bloat
-
----
-
-## Performance Impact Analysis
-
-### Build Time
-
-| Optimization | Impact | Reason |
-|--------------|--------|--------|
-| Inline type analysis | Neutral | Same work, different timing |
-
-### Runtime Performance
-
-| Scenario | Current | Proposed | Improvement |
-|----------|---------|----------|-------------|
-| Initial render (100 elements) | ~2ms | ~1.2ms | -40% |
-| Attribute update | ~0.1ms | ~0.05ms | -50% |
-| Event dispatch | ~0.01ms | ~0.008ms | -20% |
-
-**Net effect**: Faster initial render and updates. ArraySlot simplified (LIS removed) — slightly slower large sorts but simpler code.
-
----
-
-## File-by-File Changes
-
-### Eliminate Entirely
-
-| File | LOC | Reason |
-|------|-----|--------|
-| slot/index.ts | 13 | Compile-time dispatch |
-| slot/render.ts | 58 | Inline in generated code |
-| html.ts | 18 | Stub unnecessary |
-| svg.ts | 17 | Can be userland |
-
-### Simplify
-
-| File | Current | Proposed | Notes |
-|------|---------|----------|-------|
-| slot/effect.ts | 114 | 80 | Remove scheduled flag |
-| type-analyzer.ts | 338 | 200 | Remove dead branches |
-| ts-parser.ts | 123 | 80 | Combine visitors |
-
----
-
-## Implementation Priority
-
-1. **Inline attribute operations** (HIGH value, MEDIUM effort)
-   - Biggest runtime reduction
-   - Affects codegen.ts, eliminates attributes.ts
-
-2. **Eliminate runtime slot dispatch** (HIGH value, LOW effort)
-   - Already have type analysis
-   - Minor codegen changes
-
----
-
-## Risks
-
-1. **Spread attribute fallback**: Must keep `spread()` for truly dynamic spreads. Type analyzer can't unpack `{ ...unknownObj }`.
-
-2. **Firefox clone optimization**: Current `importNode` path may matter for complex templates. Mitigation: benchmark before removing.
-
----
-
-## ✅ RESOLVED: Reactive Class/Style Bindings
-
-### Solution Implemented
-
-The `setClass` and `setStyle` functions now handle reactivity internally:
-
-```typescript
-setClass = (element: Element, classlist: false | string | undefined, value: unknown) => {
-    let ctx = context(element),
-        store = ctx.store ??= {};
-
-    // Pre-populate store (eliminates getAttribute)
-    store['class.static'] = classlist || '';
-    store['class'] ??= new Set<string>();
-
-    if (typeof value === 'function') {
-        // Automatically wrap in effect with unique ID
-        reactive(element, 'class', STATE_HYDRATING, value);
-    }
-    else {
-        // Static value - apply directly
-        list(ctx, element, null, 'class', STATE_HYDRATING, value);
-    }
-};
-```
-
-### How It Works
-
-1. **Store pre-population**: Static value passed from compile time, no DOM read needed
-2. **Auto-reactivity detection**: Functions automatically wrapped in `reactive()`
-3. **Unique effect IDs**: `reactive()` assigns IDs via `ctx.effect++`
-4. **Diffing preserved**: `list()` handles multi-effect coexistence
-
-### Transformer Changes Required
-
-Update `type-analyzer.ts` to generate `setClass`/`setStyle` calls:
-
-```typescript
-// Current (broken):
-return `${n.attr}.setClass(${elementVar}, '${staticValue}', ${expr});`;
-
-// Fixed:
-return `${n.attr}.setClass(${elementVar}, '${staticValue}', ${expr});`;
-```
-
-No effect detection needed in transformer - `setClass` handles it at runtime.
-
-### Test Cases
-
-```typescript
-// 1. Single reactive class
-html`<div class="${() => theme()}"></div>`
-// → attr.setClass(e0, '', () => theme())
-
-// 2. Static + reactive
-html`<div class="base ${() => theme()}"></div>`
-// → attr.setClass(e0, 'base', () => theme())
-
-// 3. Multiple reactive on same element
-html`<div class="${() => theme()} ${() => variant()}"></div>`
-// → Two expressions concatenated at parse time, single setClass call
-// → OR multiple setClass calls if parsed as separate slots
-
-// 4. Static only (no function)
-html`<div class="foo bar"></div>`
-// → No slot, class baked into template HTML
-```
-
----
-
-## Conclusion
-
-### Current State
-
-The architecture now correctly handles:
-- ✅ Compile-time event routing (already implemented in type-analyzer.ts)
-- ✅ Class/style reactivity via `setClass`/`setStyle` (runtime detection)
-- ✅ List diffing optimizations (raw value cache, change tracking)
-- ⚠️ Transformer needs update: `setClass` → `setClass`
-
-### Remaining Work
-
-1. **Update type-analyzer.ts** — Fix method names
-   ```typescript
-   // Change:
-   ${n.attr}.setClass(...)  →  ${n.attr}.setClass(...)
-   ${n.attr}.setStyle(...)  →  ${n.attr}.setStyle(...)
-   ```
-
-2. **Spread unpacking** — Already implemented, verify edge cases
-
-3. **Other properties** — Route through `attr.set()` for auto-reactivity
-
-### Key Insights
-
-1. **Runtime reactivity detection is simpler than compile-time.** Instead of analyzing expression types in the transformer, `setClass` checks `typeof value === 'function'` and handles it. Less transformer complexity, same result.
-
-2. **Class/style diffing is essential.** The `list()` function with ID-based tracking is the only correct way to handle multiple reactive bindings on the same attribute.
-
-3. **Optimizations focus on hot paths.** Raw value caching and change tracking eliminate work for the common case (effect re-runs with same value).
-
-4. **Store pre-population eliminates DOM reads.** Static values flow from compile time → `setClass` → `store`, never touching `getAttribute`.
-
-### Performance Summary
-
-| Optimization | Impact |
-|--------------|--------|
-| Compile-time event routing | -93% per binding |
-| Raw value caching in list() | -96% for unchanged updates |
-| Change tracking (skip rebuild) | -20% for changed updates |
-| Store pre-population | -100% DOM reads |