explore(ui): Bun as Vite replacement — dev, build, and HMR [#715]

[viniciusdacal]

Summary

• Validates Bun 1.3.9 as a replacement for Vite in the @vertz/ui dev and build pipeline
• Implements a complete HMR story: CSS sidecar hot-swap (Phase 6) + JS Fast Refresh component remount (Phase 7)
• Seven exploration phases tested against the task-manager example app — recommendation upgraded to "Go"

What's in the exploration

Phase	Result	Highlights
1. Bun plugin for Vertz compiler	✅ Full parity	onLoad maps cleanly to Vite's transform
2. Client-only dev server	✅ Working	4x faster startup (200ms vs 800ms)
3. CSS validation	✅ Full parity	Runtime css() + static extraction identical
4. SSR dev server	✅ Working	Two-pass rendering, query pre-fetch, nav SSE
5. Production build	✅ Fast	15-25x faster (193ms vs 3-5s)
6. CSS sidecar HMR	✅ Working	Real .css files + Bun's built-in <link> swap
7. JS Fast Refresh	✅ Working	Component-level remount without page reload

Fast Refresh architecture (Phase 7)

Three-layer system: compiler plugin injects component wrappers → browser runtime tracks live instances → Bun's targeted HMR triggers re-evaluation.

Key design decisions:

• globalThis API — runtime exposes functions on globalThis[Symbol.for('vertz:fast-refresh')] instead of ES imports, preventing HMR propagation through @vertz/ui/dist chunks
• Stable context registry — createContext() gets a __stableId param (injected by plugin) for identity preservation across re-evaluations
• Always-dirty on re-eval — Bun only re-evaluates changed files, so if __$refreshReg fires, the file DID change
• performingRefresh guard — prevents duplicate instance tracking during re-mount

Package changes (non-exploration)

• packages/ui/src/component/context.ts — createContext() accepts optional __stableId for HMR context registry
• packages/ui/src/internals.ts — exports getContextScope/setContextScope for the runtime
• examples/task-manager/src/index.ts — import.meta.hot.accept() for HMR entry point

Test plan

• All quality gates pass (lint, typecheck, test, build)
• CSS HMR verified: style changes hot-swap without page reload
• JS Fast Refresh verified: consecutive component edits apply without reload
• Context-dependent components (SettingsPage with useSettings()) re-mount correctly
• Window state (__HMR_MARKER) survives across multiple edits
• Review FINDINGS.md for completeness

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/ui/src/component/context.ts	81.25%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[viniciusdacal]

Adversarial Review: Bun as Vite Replacement

Summary

The implementation is solid overall with thoughtful architecture. The Fast Refresh runtime design (globalThis-based API to avoid import graph pollution) is clever. However, I found several issues that should be addressed before merging.

---

Critical Issues

1. Major: Code Injection Risk in Stable ID Generation

File: packages/bun-plugin/src/context-stable-ids.ts

const stableId = `${relFilePath}::${varName}`;
// ...
source.appendLeft(closeParenPos, `undefined, '${stableId}'`);

Problem: If relFilePath contains a single quote (') or backslash, the generated code breaks or enables injection. Example: file path app's/views.tsx would generate invalid JS.

Fix: Escape special characters in stableId before string interpolation:

const escapedPath = relFilePath.replace(/['\\]/g, '\\$&');
const stableId = `${escapedPath}::${varName}`;

---

2. Major: Memory Leak in HMR Registry

File: packages/bun-plugin/src/fast-refresh-runtime.ts

The registry and dirty modules are stored on globalThis but never cleaned up:

• registry.delete(moduleId) is never called
• dirtyModules.delete(moduleId) is never called

Problem: Over time with many HMR cycles and page navigations, these maps grow unbounded.

Fix: Add cleanup when elements are detached or provide a __$refreshClear(moduleId) function.

---

3. Major: Stale Context Scope Preserved After Re-mount

File: packages/bun-plugin/src/fast-refresh-runtime.ts

updatedInstances.push({
  element: newElement,
  args,
  cleanups: newCleanups,
  contextScope,  // ← This is the OLD contextScope!
  signals: newSignals,
});

Problem: After re-mounting, the code stores the OLD contextScope from the instance. The NEW context scope (captured during factory re-execution) is lost. Subsequent re-mounts will use stale context.

Fix: Capture the new context after factory execution:

const newContextScope = getContextScope();
updatedInstances.push({
  // ...
  contextScope: newContextScope,
});

---

4. Major: Lost Cleanups on Factory Error

File: packages/bun-plugin/src/fast-refresh-runtime.ts

const newCleanups = pushScope();
const prevScope = setContextScope(contextScope);

let newElement: HTMLElement;
let newSignals: SignalRef[];
try {
  startSignalCollection();
  newElement = factory(...args);
  newSignals = stopSignalCollection() as SignalRef[];
} catch (err) {
  stopSignalCollection();
  popScope();  // ← Pops the scope
  setContextScope(prevScope);
  // newCleanups are LOST! Not run, not forwarded
  // ...
}

Problem: If the factory throws, newCleanups (created by pushScope()) are abandoned. If these cleanups contain important teardown logic (e.g., event listener removal), they won't run.

Fix: Run or forward newCleanups even on error:

} catch (err) {
  stopSignalCollection();
  runCleanups(newCleanups);  // Run the new cleanups before popping
  popScope();
  setContextScope(prevScope);
  // ...
}

---

Moderate Issues

5. Minor: Unbalanced Signal Collection Stack

File: packages/ui/src/runtime/signal.ts

startSignalCollection() and stopSignalCollection() use a simple array stack with no validation:

export function stopSignalCollection(): Signal<unknown>[] {
  return signalCollectorStack.pop() ?? [];
}

Problem: If stopSignalCollection() is called without matching startSignalCollection(), the stack becomes imbalanced. This could happen with:

• Exception between start/stop
• Incorrect usage in future code

Fix: Add validation or use a safer pattern.

---

6. Minor: No Error Handling in Plugin

File: packages/bun-plugin/src/plugin.ts

The build.onLoad callback has no try/catch.

Problem: If any step fails (CSS extraction, compilation, file write), the error bubbles up and crashes the dev server with no useful message.

Fix: Wrap in try/catch and return a meaningful error response.

---

7. Minor: Duplicate import.meta.hot.accept()

File: packages/bun-plugin/src/plugin.ts AND packages/bun-plugin/src/fast-refresh-runtime.ts

The plugin injects import.meta.hot.accept() AND the runtime calls it. While this works (idempotent), it's redundant.

---

8. Nit: Module ID Not Escaped in Codegen

File: packages/bun-plugin/src/fast-refresh-codegen.ts

Same injection risk as #1 if moduleId contains special chars.

---

Missing Tests

The signal tests are comprehensive. Missing coverage for:

1. HMR runtime registry - register, track, perform cycles
2. Context stable IDs - injectContextStableIds edge cases
3. Plugin error paths - malformed input, missing files
4. Factory error recovery - verify old instance preserved

---

Good Decisions to Acknowledge

1. globalThis-based API - Excellent solution to avoid Bun HMR propagating through @vertz/ui chunks
2. Context registry on globalThis - Smart way to preserve context identity across re-evaluations
3. performingRefresh flag - Prevents duplicate instance tracking elegantly
4. Signal collection for state - Feasibility shown for follow-up implementation
5. CSS sidecar approach - Clean separation, leverages Bun's native CSS HMR

---

Severity Summary

Issue	Severity	Type
Code injection in stable ID	Critical	Security
Memory leak in registry	Major	Memory
Stale context scope	Major	Correctness
Lost cleanups on error	Major	Resource leak
Unbalanced signal stack	Minor	Robustness
No plugin error handling	Minor	Debugging
Duplicate accept() call	Minor	Cleanup
Module ID injection	Minor	Security

---

Recommendation

Address the 4 Major/Critical issues before merging. The architecture is sound and the approach is well-researched (7 phases!). These are fixes in the implementation, not the design.

[viniciusdacal]

GLM Adversarial Review

I've reviewed PR #719 with a focus on finding issues the first reviewer may have missed. Here are my findings:

---

🚨 Critical Issues

1. ts-morph Version Mismatch (Severity: High)

Location: packages/bun-plugin/package.json

The bun-plugin declares ts-morph@^25.0.0 but the root package.json and exploration files use ts-morph@^27.0.2. This creates:

• Duplicate installations in node_modules
• Potential API incompatibilities between versions
• Increased bundle size from deduplication

Recommendation: Use ^27.0.2 to match root, or document why ^25 is required.

---

2. @vertz/ui-compiler Missing Subpath Exports (Severity: High)

Location: packages/ui-compiler/package.json

The bun-plugin imports individual modules directly:

import { ComponentAnalyzer } from '@vertz/ui-compiler/src/analyzers/component-analyzer';
import { compile } from '@vertz/ui-compiler/src/compiler';

But @vertz/ui-compiler only exports "./": "./dist/index.js". These subpath imports will fail at runtime because:

• The source paths (src/analyzers/) don't exist in the built package
• Only dist/index.js is published

Recommendation: Add subpath exports to @vertz/ui-compiler/package.json.

---

3. No Tests for bun-plugin (Severity: High)

Location: packages/bun-plugin/package.json

The test script is a no-op:

"test": "echo 'No tests — browser runtime tested via exploration app'"

This is concerning because:

• No unit tests for CSS extraction logic
• No tests for Fast Refresh codegen
• No tests for context stable ID injection
• The "exploration app" is manual testing, not automated regression protection

Recommendation: Add unit tests before merging, at minimum covering:

• CSS sidecar file generation
• Fast Refresh wrapper injection
• Context stable ID parsing

---

⚠️ Medium Issues

4. SSR: globalThis Leakage Risk (Severity: Medium)

Location: packages/bun-plugin/src/fast-refresh-runtime.ts, packages/ui/src/runtime/signal.ts

The Fast Refresh runtime uses globalThis[Symbol.for('vertz:fast-refresh')] and globalThis['__VERTZ_CTX_REG__'].

Problem: In serverless SSR environments (Cloudflare Workers, Vercel Edge), globalThis persists across requests within the same isolate. This could cause:

• Context registry pollution between requests
• Signal collector stack bleeding between requests
• Memory leaks from accumulating registry entries

Mitigation needed: Add SSR detection and skip globalThis registration during SSR, or implement cleanup in the SSR adapter.

---

5. Signal Collection - Missing Cleanup on Scope Exit (Severity: Medium)

Location: packages/ui/src/runtime/signal.ts

The signalCollectorStack uses push/pop but has no bounds checking:

export function stopSignalCollection(): Signal<unknown>[] {
  return signalCollectorStack.pop() ?? [];
}

If stopSignalCollection() is called without a matching startSignalCollection(), it silently returns an empty array. This could mask bugs where the wrapper code doesn't properly pair calls.

Recommendation: Add an assertion or warning when stack is empty.

---

6. Missing Test Coverage: Signal Collection (Severity: Medium)

The new startSignalCollection/stopSignalCollection functions have tests in signal.test.ts, but no tests verify:

• They work correctly within domEffect/lifecycleEffect
• Nested collections don't interfere with each other
• They properly integrate with the Fast Refresh wrapper

---

📝 Low Priority / Documentation

7. FINDINGS.md - Bundle Size Justification (Severity: Low)

Location: explorations/bun-fullstack/FINDINGS.md

The doc states:

Bun's minifier is less aggressive than Terser

This is speculation. A better analysis would profile:

• Which specific optimizations differ
• Whether this can be tuned via Bun config
• Actual gzip-compressed sizes (not just "CDN handles it")

---

✅ What Looks Good

1. Architecture: The globalThis[Symbol.for('vertz:fast-refresh')] approach is sound for HMR isolation - avoids import graph pollution.

2. Context Stability: The __stableId approach with filePath::varName format is robust for most cases.

3. Backward Compatibility: The __stableId parameter to createContext() is optional with a default, so existing code is unaffected.

4. Signal Changes: The collector stack is minimal and mirrors the disposal pattern. No perf regression expected for non-HMR usage.

5. Exploration Documentation: The FINDINGS.md is comprehensive and honest about limitations (bundle size, SSR gaps).

---

Summary

Severity	Count
High	3
Medium	3
Low	1

Verdict: The PR needs work before merge. The missing subpath exports and missing tests are blockers. The SSR globalThis concern should be addressed with SSR detection before production use.