Hot module reload - HMR

[RandiJay96]

[RandiJay96]

Phase 1 — Prep & Mode Switching

• Add mode flag (development / production) to ViteClientBundleBuilder.
• Add conditional logic to call _bundle_with_vite() (production) or _start_dev_workflow() (development).
• Implement _start_dev_workflow() with initial bootstrap steps:
  • Module pre-compilation
  • Dependency resolution
  • Babel compilation
  • Asset copying
• Generate development-specific Vite config:
  • Set root = build/
  • Enable @vitejs/plugin-react
  • Set build.sourcemap = true
  • Inject user vite.server config

Phase 2 — Running the Dev Server

• Start Vite Dev Server inside _start_dev_workflow() (API or subprocess).
• Confirm app loads at configured port with basic live reload.
• Implement JacCompilerWatcher:
  • Watch **/*.jac and **/*.css
  • Log changed file paths
  • Run concurrently with Vite

Phase 3 — HMR Feedback Loop

• Implement targeted JS recompilation on .jac change:
  • Recompile only the changed file
  • Write output .js to matching path in build/
  • Verify Vite reloads updated file
• Implement asset HMR:
  • Copy only changed CSS/image assets into build/
  • Verify CSS changes apply instantly in the browser
• Verify React Fast Refresh:
  • Component updates without losing state

Phase 4 — Refinement

• Implement dependency graph invalidation:
  • Recompile dependent modules when a shared .jac file changes
• Add cleanup and error handling:
  • Clean compiled/ directory on start and exit
  • Log compilation errors without crashing the watcher

[musab-mah-7]

Design Decisions & Conclusions for HMR

The HMR integration requires making several key design decisions and adopting a new architecture.
Since your core server must remain clean and only support the current production mode and the new development mode, the decisions revolve around mode-switching and process delegation.

---

#	Design Decision / Trade-Off	Conclusion	Rationale / New Behavior
1	Execution Mode Control	Introduce a mode flag (development / production).	The entire pipeline (compilation, serving, asset links) depends on this flag.
2	Frontend Asset Server	Delegate all static serving to Vite Dev Server in development.	Core server must not serve /static/client.js during dev for native ESM + HMR.
3	HTML Script Source	Conditionally change <script src="..."> in render_page.	Dev: http://0.0.0.0:{dev_port}/main.js (module). Prod: /static/client.js?hash=....
4	Jac Code Watching	Create a separate concurrent process: Jac Compiler Watcher.	Core server must not block; watcher handles .jac ➝ .js updates into build/.
5	Compilation Strategy	Use minimal/incremental compilation in the watcher.	Only changed files are recompiled for instant HMR; full builds are too slow.
6	API Server Asset Role	Disable static asset serving in dev mode.	Prevents conflicts with Vite and removes expensive dev-time ensure_bundle().
7	Build Output Usage	Vite Dev Server uses the build/ directory as its root.	Ensures Vite sees the Jac-to-JS transpiled output needed for HMR.
8	React Integration	Use @vitejs/plugin-react (Fast Refresh).	Handles state-preserving React refresh; Jac core only needs correct Vite config.

---