feat(node): add createNodeApp hotReload option + template/demo migration (#147)

* feat(node): integrate createNodeApp hotReload lifecycle API

* chore(repo): apply biome formatting for package manifests

Author: RtlZeroMemory

CHANGELOG.md

@@ -12,6 +12,7 @@ The format is based on Keep a Changelog and the project follows Semantic Version
 - `@rezi-ui/bench` — comprehensive benchmark suite (Rezi native vs Ink-on-Rezi vs Ink)
 - Benchmark results and performance documentation
 - Hot State-Preserving Reload (HSR): `App.replaceView(...)`/`App.replaceRoutes(...)` in core and `createHotStateReload(...)` in `@rezi-ui/node` for in-process widget view and route-table hot swapping during development
+- `@rezi-ui/node` `createNodeApp(...)` now supports first-class `hotReload` wiring (auto lifecycle start/stop + `app.hotReload` controller) and route passthrough (`routes`, `initialRoute`)
 - Code-editor syntax tokenizer utilities in `@rezi-ui/core`: `tokenizeCodeEditorLine(...)`, `tokenizeCodeEditorLineWithCustom(...)`, `normalizeCodeEditorTokens(...)`, language presets (`typescript`, `javascript`, `json`, `go`, `rust`, `c`, `cpp`/`c++`, `csharp`/`c#`, `java`, `python`, `bash`)
 - Widget composition API (`defineWidget` with hooks)
 - Page router route guards (`guard`) and nested route trees (`children`) with `context.outlet` rendering
@@ -31,6 +32,7 @@ The format is based on Keep a Changelog and the project follows Semantic Version
 - Documentation expanded with 90+ pages covering all features
 - README updated with performance data, JSX support, Zireael engine reference
 - ROADMAP updated to reflect current project state
+- HSR demos and `create-rezi` templates now use `createNodeApp({ hotReload: ... })` instead of manual controller lifecycle wiring
 - Input widgets now include local undo/redo history (`Ctrl+Z`, `Ctrl+Shift+Z`, `Ctrl+Y`) with 300ms typing-grouping
 - Virtual-list routing and scroll math now consume measured-height caches when estimate mode is active, improving End/Page navigation and wheel behavior for variable-height content
 

docs/backend/node.md

@@ -32,9 +32,12 @@ knobs aligned:
 
 Development hot reload:
 
-- `createHotStateReload(...)` watches source files and hot-swaps either:
+- `createNodeApp({ hotReload: ... })` watches source files and hot-swaps either:
   - widget views via `app.replaceView(...)`, or
   - route tables via `app.replaceRoutes(...)` for route-managed apps.
+- lifecycle is automatic: watcher starts/stops with `app.start()/stop()/run()`.
+- `app.hotReload` exposes manual `reloadNow()` when needed.
+- low-level `createHotStateReload(...)` remains available for advanced manual wiring.
 - Raw draw mode remains excluded.
 
 Execution mode details:

docs/dev/contributing.md

@@ -42,7 +42,7 @@ node --test packages/core/src/app/__tests__/widgetRenderer.integration.test.ts
 
 ## HSR Change Checklist
 
-If your change touches `app.view`, route integration, reconciliation identity, or `createHotStateReload`:
+If your change touches `app.view`, route integration, reconciliation identity, `createNodeApp({ hotReload })`, or `createHotStateReload`:
 
 - add app runtime tests for `app.replaceView(...)` / `app.replaceRoutes(...)` behavior
 - verify widget local state survives reload with stable ids/keys

docs/dev/testing.md

@@ -109,7 +109,7 @@ Integration tests cover:
 
 ### Hot State-Preserving Reload (HSR) Tests
 
-When changing `app.replaceView(...)`, `app.replaceRoutes(...)`, or `createHotStateReload(...)`, include:
+When changing `app.replaceView(...)`, `app.replaceRoutes(...)`, `createNodeApp({ hotReload })`, or `createHotStateReload(...)`, include:
 
 - successful runtime widget-view swap test (`replaceView` while `Running`)
 - successful runtime route-table swap test (`replaceRoutes` while `Running` in route mode)

docs/getting-started/create-rezi.md

@@ -89,7 +89,7 @@ Each template includes example tests for reducer logic, widget rendering, and ke
 `npm run dev` / `bun run dev`:
 
 - dev script runs `tsx src/main.ts --hsr`
-- source changes hot-swap via:
+- source changes hot-swap through `createNodeApp({ hotReload: ... })` via:
   - `app.replaceView(...)` in widget-view templates (`minimal`, `dashboard`)
   - `app.replaceRoutes(...)` in route-managed template (`cli-tool`)
 - app state, focus, and stable widget local state are preserved across edits

docs/guide/lifecycle-and-updates.md

@@ -72,32 +72,34 @@ When a new view function is applied, Rezi keeps:
 
 ```ts
 import { ui } from "@rezi-ui/core";
-import { createNodeApp, createHotStateReload } from "@rezi-ui/node";
-
-const app = createNodeApp({ initialState: { count: 0 } });
-app.view((state) => ui.text(`count=${String(state.count)}`));
+import { createNodeApp } from "@rezi-ui/node";
 
-const hsr = createHotStateReload({
-  app,
-  viewModule: new URL("./screens/main-screen.ts", import.meta.url),
-  moduleRoot: new URL("./src", import.meta.url),
+const app = createNodeApp({
+  initialState: { count: 0 },
+  hotReload: {
+    viewModule: new URL("./screens/main-screen.ts", import.meta.url),
+    moduleRoot: new URL("./src", import.meta.url),
+  },
 });
-
-await hsr.start();
-await app.start();
+app.view((state) => ui.text(`count=${String(state.count)}`));
+await app.run();
 ```
 
 Route-managed apps can hot-swap route tables instead:
 
 ```ts
-const hsr = createHotStateReload({
-  app,
-  routesModule: new URL("./screens/index.ts", import.meta.url),
-  moduleRoot: new URL("./src", import.meta.url),
-  resolveRoutes: (moduleNs) => {
-    const routes = (moduleNs as { routes?: unknown }).routes;
-    if (!Array.isArray(routes)) throw new Error("Expected `routes` array export");
-    return routes;
+const app = createNodeApp({
+  initialState,
+  routes,
+  initialRoute: "home",
+  hotReload: {
+    routesModule: new URL("./screens/index.ts", import.meta.url),
+    moduleRoot: new URL("./src", import.meta.url),
+    resolveRoutes: (moduleNs) => {
+      const routesExport = (moduleNs as { routes?: unknown }).routes;
+      if (!Array.isArray(routesExport)) throw new Error("Expected `routes` array export");
+      return routesExport;
+    },
   },
 });
 ```

docs/packages/create-rezi.md

@@ -60,7 +60,7 @@ For full template descriptions and highlights, use: [Getting Started -> Create R
 Template dev workflow notes:
 
 - `minimal`, `dashboard`, and `cli-tool` templates run `tsx src/main.ts --hsr` for `npm run dev` / `bun run dev`.
-- This enables in-process hot state-preserving reload through `@rezi-ui/node` `createHotStateReload(...)`.
+- This enables in-process hot state-preserving reload through `@rezi-ui/node` `createNodeApp({ hotReload: ... })`.
 
 ## Options
 

docs/packages/node.md

@@ -54,43 +54,49 @@ lockstep:
 
 ## Hot State-Preserving Reload (HSR)
 
-`@rezi-ui/node` ships `createHotStateReload(...)` for development-time widget-view
-or route-table swaps.
+`createNodeApp(...)` has first-class HSR wiring through `hotReload`.
 
 ```ts
 import { ui } from "@rezi-ui/core";
-import { createHotStateReload, createNodeApp } from "@rezi-ui/node";
-
-const app = createNodeApp({ initialState: { count: 0 } });
-app.view((state) => ui.text(`count=${String(state.count)}`));
+import { createNodeApp } from "@rezi-ui/node";
 
-const hsr = createHotStateReload({
-  app,
-  viewModule: new URL("./screens/main-screen.ts", import.meta.url),
-  moduleRoot: new URL("./src", import.meta.url),
+const app = createNodeApp({
+  initialState: { count: 0 },
+  hotReload: {
+    viewModule: new URL("./screens/main-screen.ts", import.meta.url),
+    moduleRoot: new URL("./src", import.meta.url),
+  },
 });
 
-await hsr.start();
-await app.start();
+app.view((state) => ui.text(`count=${String(state.count)}`));
+await app.run(); // starts/stops hot reload watcher with app lifecycle
 ```
 
-Route-managed apps use `routesModule` + `app.replaceRoutes(...)`:
+Route-managed apps use `routesModule`:
 
 ```ts
-const hsr = createHotStateReload({
-  app,
-  routesModule: new URL("./screens/index.ts", import.meta.url),
-  moduleRoot: new URL("./src", import.meta.url),
-  resolveRoutes: (moduleNs) => {
-    const routes = (moduleNs as { routes?: unknown }).routes;
-    if (!Array.isArray(routes)) {
-      throw new Error("Expected `routes` array export");
-    }
-    return routes;
+const app = createNodeApp({
+  initialState: { count: 0 },
+  routes,
+  initialRoute: "home",
+  hotReload: {
+    routesModule: new URL("./screens/index.ts", import.meta.url),
+    moduleRoot: new URL("./src", import.meta.url),
+    resolveRoutes: (moduleNs) => {
+      const routesExport = (moduleNs as { routes?: unknown }).routes;
+      if (!Array.isArray(routesExport)) {
+        throw new Error("Expected `routes` array export");
+      }
+      return routesExport;
+    },
   },
 });
 ```
 
+`app.hotReload` exposes the controller (`reloadNow()`, `isRunning()`) when you need
+manual trigger points. For advanced/custom lifecycle control, low-level
+`createHotStateReload(...)` remains available.
+
 What this does:
 
 - watches source paths for changes
@@ -106,7 +112,7 @@ What stays intact across reload:
 Current scope:
 
 - widget-mode apps (`app.view`/`app.replaceView`)
-- route-managed apps (`createApp({ routes, initialRoute })` + `app.replaceRoutes`)
+- route-managed apps (`createNodeApp({ routes, initialRoute })` + `app.replaceRoutes`)
 - not raw draw mode
 
 ## `NO_COLOR` behavior

packages/core/package.json

@@ -104,12 +104,7 @@
       "default": "./dist/widgets/index.js"
     }
   },
-  "files": [
-    "dist/",
-    "README.md",
-    "!dist/**/__tests__/**",
-    "!dist/**/__e2e__/**"
-  ],
+  "files": ["dist/", "README.md", "!dist/**/__tests__/**", "!dist/**/__e2e__/**"],
   "engines": {
     "node": ">=18",
     "bun": ">=1.3.0"

packages/create-rezi/package.json

@@ -16,13 +16,7 @@
   "bin": {
     "create-rezi": "dist/index.js"
   },
-  "files": [
-    "dist/",
-    "templates/",
-    "README.md",
-    "!dist/**/__tests__/**",
-    "!dist/**/__e2e__/**"
-  ],
+  "files": ["dist/", "templates/", "README.md", "!dist/**/__tests__/**", "!dist/**/__e2e__/**"],
   "engines": {
     "node": ">=18",
     "bun": ">=1.3.0"