Hot reload
This is the existential bet of the project. If the edit loop stays at a multi-second/minute rebuild-and-relaunch, nobody leaves the web, and the rest of Auro does not matter.
Target: edit to see in under 500 ms, with app state preserved.
The target and observable contract are fixed; the mechanism is under revision with prototype evidence. Normative dev-loop contract, staging, and acceptance are drafted in spec 0004.
Contract
- Default today:
auro devrebuilds and relaunches the app process (Phase 0). A saved change to a visible relaunch measured ~60 s on the development machine (relink dominates, 2026-11-15). This is not hot reload. - Hot reload goal: a warm, view-only change becomes visible in under 500 ms with opted-in state preserved, without closing the window.
- Honesty rule: a process restart is never presented as hot reload. A failed build keeps the previous UI active. A reload or patch that cannot be applied safely falls back to a state-preserving restart only when state can be restored, and the outcome is labelled explicitly.
Slice 0 finding (2026-11-16)
ADR 0005 (superseded) assumed a cdylib compiled UI
swapped by the host via libloading. A Slice 0 viability spike
(spec 0004, Linux x86_64, Wayland/niri, rustc 1.99.1, debug,
gpui = "=0.2.2", libloading = "0.8.9") found that mechanism infeasible for GPUI view/render
code on the current stack:
dlopen/dlclosemechanics work for isolated C-ABI symbol calls, but mounting GPUI views from a separately loaded library into a host-owned GPUI application is incompatible with GPUI 0.2.2’s type/instance model (Window::replace_root<E: Render>generic root,AnyView/Entity<V>downcast and hostAppentity storage, thread-local element arena,TypeIdidentity, upstream GPUI rlib-only).- A realistic GPUI-view
cdylib(trivial view change, 429 MB debug artifact) warm-relinked in ~171 s wall / 2m50s cargo in the spike run, far outside the < 500 ms budget.
cdylib/libloading swap for GPUI view code is rejected unless new evidence resolves mount,
type/instance identity, unload safety, and measured performance.
Option 1 consolidation (2026-11-16, prototype evidence)
Follow-up throwaway prototypes (Linux x86_64, Wayland/niri, rustc 1.99.1/cargo 1.99.1, debug
debug = 0, warm dx serve --hot-patch, gpui = "=0.2.2", subsecond 0.7.10,
dioxus-devtools 0.7.10, dx 0.7.10, not integrated into auro crates/CLI) evaluated same-process
function-level hot-patching of the tip crate:
- Mechanism exercised: explicit stable
subsecond::HotFn::current(...)boundaries in reloadable view code,dioxus_devtools::connect_subsecond()/devserver patch application, host-owned GPUIApplication/window/event loop and entity state (ticker-updated counter, stable host string) kept in the same process/type universe. - Minimal-case results: plain Rust
HotFnpatch observed at ~125 ms (rev=0→rev=1, counter continued). GPUI 0.2.2 app warm view edits measured ~271-450 ms save-to-first-new-render with host state preserved (s1: median 371.5 ms, N=10, values 438/409/371/422/372/406/339/343/350/300; s6: median 346 ms, N=20, 20/20 stable). Helper/layout/style changes, coordinated transient struct layout changes, multi-module tip-crate edits (functionally applied), build/syntax-error recovery, and non-dx instrumented run were demonstrated. - Constraints observed: patchable code is tip-crate code reached via hot boundaries (changes
outside boundary or init-captured async work not retroactive, e.g.
Renderimpl outsideHotFnand running ticker future unchanged). Tip-crate statics/render-local counters reset on patch (host entity state preserved).thread_local!used in a patched path can fail patch generation (R_X86_64_TPOFF32/-shared) while the app stays alive on previous code.dx/target-dir isolation and build artifact contention require care. - Status: evidenced experimental candidate for the in-process direction on Linux x86_64/GPUI
0.2.2 in minimal conditions; not a D6 claim for representative Auro scaffolds/apps, not
integrated into
auro dev, and not proven across platforms/profiles. - Windows plain prototype follow-up (2026-11-16, WinBoat guest, not integrated): the same
non-GPUI tip-crate
HotFnmechanism was validated on Windows 11 Pro 10.0.26200.0 x64 (rustc/cargo 1.99.0 MSVC,dx/subsecond/dioxus-devtools0.7.10) withdx serve --hot-patch --interactive false --platform desktop, a clean target, and external logs. Build completed in 30.66 s and 3/3 warmsrc\main.rshot-patches applied in 484/504/499 ms with monotonic counter continuityrev=0 1..361 -> rev=1 421..781 -> rev=2 841..1261 -> rev=3 1321..1741in the same process (ERR_LEN=0,plain-proofwin-20261116152539.*), demonstrating mechanism viability on Windows x86_64 for this minimal plain case only (not a D6 benchmark). Caveats: corrupted reused target (libdeps-62094602.a: unknown file type), inconclusive hidden/background runs, and watcher noise from in-project verbose log redirection. - Windows advanced front/back follow-up (2026-11-16, WinBoat guest, plain non-GPUI, not
integrated): a second tip crate rendered through
HotFn::current(render_frontend)with host-owned state (session,items,backend_ticks) and an init-captured backend thread. View edits applied in 590 ms (ui0→ui1) and 523 ms (ui1→ui2with added radius/padding/icon) whilesession=s5500,items4→36 andbackend_ticks8→72 stayed continuous in the same process. A source change to the backend interval (500→1500 ms) was hot-patched (527 ms) but the running task keptactive_interval_ms=500; restarting with the changed source produced a new process (session=s9516,init_backend_ms=1500) and a 1500 ms tick cadence (adv-fix-20261116161242.*,adv-fix-restart-20261116161242.*,ERR_LEN=0). This is the observed hot-boundary versus init-captured split for this mechanism, not a Tauri backend-process comparison. - Windows GPUI 0.2.2 follow-up (2026-11-16, WinBoat guest, not integrated): the GPUI prototype
built in 181 s (23.9 MB exe) and rendered when launched into the active interactive console
session via a scheduled task (
/RU pdl /IT): 206[hot_view]renders,counter0→204,stable=host-owned-statepreserved, no panic. The same exe launched from SSH/session 0 panicked withCreating DirectX renderer→Creating DirectX resources→0x887A0022(DXGI_ERROR_NOT_CURRENTLY_AVAILABLE), as diddx serve --hot-patchfrom that context after a 199.20 s build. Adx serve --hot-patchrun in the interactive session itself (scheduled task,SESSION=1, cleantarget-gpui-hot3) built in 473.85 s, rendered (label=v0,counter0→43), applied its first patch (Hot-patching: src\main.rs took 1453ms,[patch_applied] t_ms=5760) and then died withthread 'main' has overflowed its stack/exit code: 0xc000041dbefore anylabel=v1render (gpui-hot3-20261116-170828.*). Follow-up isolation on the same guest: the jump table itself is sound (runtime dump:entries=746,aslr_ref=0xcab0/new_base=0xcb10as RVAs, exe exportingmainat RVA0xcab0), the crash reproduces with a 16 MiB main-thread stack (/STACK:16777216, PE-verified), a leafHotFn(fn(u64) -> u64) patched twice in one process without crashing (bumped=1050at counter 50,bumped=2193at counter 193), and a framework-freeViewDataboundary reloaded UI values twice (1324 ms,1084 ms) withdata=v1→data=v2, 120/187 renders after each,counter4→175,stablepreserved, no crash — visually confirmed by a QMP screenshot of the same window (gpui-hot7-20261116-175144.*). The Windows patch DLL is 89,600 bytes with onlymainexported and no GPUI/imports from the exe, so the observed limit is consistent with the patch unit not carrying the framework. Windows GPUI render works in an interactive session; view-code hot patching is blocked, framework-free hot boundaries work.
Integrated hot mode (2026-11-18)
[dev] hot = true now runs a usable loop rather than a patch that needed a click to appear:
- Repaint on commit. The devserver applies a patch without touching GPUI's frame; the app kept
the previous frame, and the patched boundary only ran on the next interaction. On Linux this made
a patch look applied (
Hot-patching ... took, handler fired) with no visible change; this is also the mechanism behind the earlier Windows "boundary never ran" observation.auro::hot::installnow registers a subsecond handler that bumps a revision and printsauro:trace hot_patch <n>;App::try_runpolls it (16 ms) on the main thread and callscx.notify(root_entity)for every open window, so the next frame runs the patched boundary. - Measured render.
auro::hot::hot/hot_withprintauro:trace hot_render <n>on the first call after a patch. A view that validates the frame first (the generated one does) callshot_frameandrenderedonly after the frame is accepted, so a rejected frame does not produce a render marker.auro devcombines its own save timestamp, the devserver'sHot-patching ... tookline and this marker into one JSON line per edit (save_to_patch_ms,patch_to_render_ms,save_to_render_ms,patch_took_ms). - Change classification. A save under
data/srcis a hot boundary edit. A save inui,types, the bin, a dependency, a manifest or the profile is labelledoutside the hot boundary;auro devrestarts the devserver and app, restores the snapshot and labels the outcomerestarted (state restored|reset), never as a reload. The previous app stays visible while the replacement builds; a failed host rebuild keeps that UI running and is reported, and boundary build errors also keep the previous UI. This makes the documented reload unit visible and gives host-code changes the documented fallback instead of a silent no-op. - Boundary is the reloadable unit.
view_data() -> HotDatareturns plain data; element and layout code inRenderis host-stable. Only functions reached throughhot/hot_withconsult the jump table, so a patch ofrenderalone does not change the running UI;auro devrestarts the devserver/app for that host-code save. The scaffold prints the boundary's returned value per revision so a boundary reload is visible. - Dev profile. Scaffolded
Cargo.tomldefines[profile.desktop-dev]withinherits = "dev",debug = 0,incremental = false. The Dioxus CLI uses that adhoc profile fordx serve;debug_assertionsremain on, which subsecond requires. DWARF dominated the relink (3.3 s → ~0.5 s save-to-render on the demo), and disabling the incremental session was faster and steadier for the one-file ThinLink rebuild. - Crate boundary. The scaffold is a four-crate workspace:
types(ViewData+ fixedHotData),data(the boundary),ui(Render, window, element tree, snapshot/autosave) and a thin bin.uidoes not depend ondata, sodxrecompiles the changed boundary crate and the bin, not GPUI or the view. The patch library falls from roughly the size of the app to ~12 KB, and the measured Linux median fell from 521 ms to 368 ms (N=12, 325-394). A plan struct boundary without the fixed-frame check measured 288 ms; the guard costs ~80 ms and is kept because it rejects a patch built against a changed data layout instead of letting the old host read it. - Apply containment.
auro::hotopens the devserver connection itself. A patch that fails to load is caught (error or loader panic), reported, and the previous jump table keeps running; the listener stays open for the next edit. The dev loop labels itpatch rejected by the app, never as a reload. A committed patch wakes the main thread through a watch channel instead of a 16 ms poll, so patch-to-render is 1-26 ms and an idle app does not wake twice a frame.
Linux measurement, earlier single-crate scaffold (niri/Wayland, x86_64, 12 CPUs, rustc 1.99.1,
gpui 0.2.2, dx/subsecond/dioxus-devtools 0.7.10, warm dependency cache, boundary-only edits):
save-to-render 473/488/519/521/521/522/528/539/548/567/572 ms (median 521 ms, min 473, max 572,
N=11); patch-to-render 8-24 ms; same pid and host state across patches. With incremental = true
the same app measured median 650.5 ms (N=10, 547-1722).
Linux measurement, four-crate scaffold (2026-11-18): save-to-render
393/371/385/370/366/339/357/370/394/350/325/366 ms (median 368 ms, min 325, max 394, N=12),
patch-to-render 1-26 ms, patch_took 268-325 ms, same pid/window/host state. The host was under
load average ~16 from an unrelated workspace test build for the series, so the numbers are
conservative for this machine. A type error kept the previous UI and the fixing edit applied in
270 ms (simple-frame series). A schema change applied as a patch was rejected by the running view
and left the previous values on screen.
Platform status (2026-11-18)
- Linux: measured above; four-crate scaffold median 368 ms (N=12), integrated loop, state continuity, build-failure recovery, apply containment, schema rejection, graceful exit and Ctrl-C cleanup verified (niri/Wayland).
- Windows: integrated loop verified in the WinBoat guest (interactive console session 1, MSVC
1.99.0): first patch after launch 2806 ms save-to-render, five steady-state patches
1823/1505/1375/1237/1282 ms (median 1375), patch-to-render 8-38 ms; same pid and ticking host
state across patches, a type error kept the previous UI live, the fix reloaded in 1696 ms, and
closing the window exited the dev loop with code 0. A four-crate re-test (simple boundary)
measured 873/1872/1735/1229/1168/961/820/2359/921 ms (N=9, median 1168, patch-to-render 3-13 ms)
with the same pid/window/state: better, still above 500 ms. The guarded
HotDatatemplate then measured 851/765/768/880/813/897/816/752/768 ms (N=9, median 813, min 752, max 897; patch-to-render 2-16 ms) throughauro dev, same pid/window, patch DLL 14,848 bytes. Defender exclusions for the app and repo left four steady patches at 719-735 ms (one 1293 ms outlier);incremental = truemeasured 830/848/799/819 ms steady (N=4);codegen-units = 1measured 810/748/769/738/719 ms (N=5, median 748). The remaining gap is MSVC compile/link, not repaint, the incremental session or codegen-unit count.dx servemust run inside the interactive session (a session-0 run fails before render with DirectX0x887A0022). Defender exclusions for the project/cargo/rustup directories are recommended, but in this run they left four steady patches at 719-735 ms (one 1293 ms outlier), not enough to reach the target.rust-lldlinked a plain cargo build but dx 0.7.10 rejected the hot patch withMissing linker args for fat link; its fat-link interception requires the default linker, so lld is not a usable lever./OPT:REFplus/OPT:ICFmeasured a 767 ms median save-to-render (N=4), no gain. Aui/src/lib.rssave restarted the devserver/app in 5.91 s with a new pid and restored snapshot; a followingdataedit patched in 910 ms, and a syntax error kept the previous app and printedhost rebuild failed; previous UI still running. The data boundary is the reloadable unit; Windows cannot patch element-returning code. - macOS: no local Apple host, but a manual workflow (
Hot reload macOS benchmark) measured the guarded scaffold on a sharedmacos-26-arm64runner with the prebuilt dx 0.7.10: six warm-up edits then twelve measured, save-to-render 536/520/444/625/1071/598/481/507/439/512/462/372 ms (N=12, median 509.5, min 372, max 1071; patch-to-render 2-17 ms), same process/window. A first cold run measured median 515 (N=12, 431-715). The runner is noisy and the median is slightly above target; five of twelve warm edits were under 500. A second six-warmup run measured a 837.0 ms median (N=12, p95 2096, 583-2096) and passed the host-restart check. A third, with the previous app kept alive during the rebuild, measured 956.0 ms (N=12, p95 1563, 775-1563) and also passed restart. A twelve-warmup run measured 748.5 ms, so extra warm-up does not remove the variance; the three six-warmup runs span 509.5-956.0 ms and the target is not claimed met. Local hardware, signing and hardened-runtime behaviour remain open.
The < 500 ms reference case is met on Linux (median 368 ms), not on Windows (median 813 ms), and is above the target on a shared macOS runner (509.5 ms median; a second run measured 837.0 ms). It is reported per platform, never as a single global claim.
| Platform | Hot mode | Save-to-render (warm) | Evidence |
|---|---|---|---|
| Linux x86_64, niri/Wayland | Opt-in, verified | 368 ms median, N=12 (p95 394, 325-394) | Four-crate scaffold, desktop-dev, boundary edits, same pid/window/state |
| Windows 11 x86_64, MSVC | Opt-in, verified in interactive session | 813 ms median, N=9 (p95 897, 752-897) | Guarded four-crate scaffold, auro dev trace, same pid/window; still above target (a plain-boundary series measured 1168 ms) |
macOS arm64 (macos-26-arm64 runner) | Opt-in, measured in CI | 509.5 / 837.0 / 956.0 ms medians, three runs, N=12 after 6 warm-up (p95 1071/2096/1563) | Shared GitHub runner; host restart and snapshot restore verified; no local Apple hardware, signing or hardened-runtime test |
The host-code restart path is verified on Linux, Windows and macOS CI. macOS local hardware, signing and hardened-runtime behaviour remain unverified.
Mechanism and layout
Per ADR 0008, the mechanism keeps one GPUI
Application/window/event loop and reloads updated UI code in the same process and type universe.
The implemented mechanism is subsecond/dx function-level patching of an explicit HotFn
boundary, with host-owned GPUI state and a versioned snapshot. The generated layout makes the
reloadable unit a small workspace crate (data) that the view crate (ui) does not depend on,
which keeps GPUI out of the patch and brings the Linux warm-edit median under 500 ms. The boundary
returns a fixed HotData frame so a changed data layout is rejected rather than misinterpreted.
The layout and fixed-frame decision is recorded in
ADR 0022; the contract, measurements and
remaining platform limits are in spec 0004.
State preservation
Regardless of mechanism, reloadable state that opts in is captured as a versioned,
serde-compatible snapshot owned by the host before apply or before a state-preserving restart, and
restored after success. State that cannot be restored (incompatible version/key, non-serialisable
resource, or explicit reset) must be reported, never silently replaced. Tip-crate statics and other
patch-unit-local state must not be treated as preserved across an in-process patch.
Fallback
When a change is not safely reloadable in-process (host/bootstrap/toolchain/config changes, failed compatibility/apply/patch generation, or mechanism limitations), the fallback is a state-preserving process restart: persist snapshot, restart, restore. Slower, but it preserves context and is labelled honestly.
Constraints this imposes on application code
- Reloadable UI logic must cross explicit, stable hot boundaries; code outside those boundaries (or already captured in running futures/callbacks/init state) must not be assumed to update in place.
- Views and reloadable state must be reconstructible from host-owned snapshots/state.
- Reloadable tasks, subscriptions, and callbacks must be cancellable or invalidatable before replaced code can run.
- Preserved state must live on the host-stable side or in snapshotable form; tip-crate/patch-unit statics, thread-locals, and layout-incompatible values need reset or migration handling.
- Entity/view handles and callbacks must not be stored in global/static locations that outlive the reload unit or prevent safe invalidation.
- On Windows/MSVC (
dx/subsecond0.7.10,gpui 0.2.2) the patched unit cannot construct GPUI elements: an element-returning hot boundary applies and then overflows the main thread's stack. The unit must return framework-free data (ViewData-style) that host-stable code turns into elements; view-code hot reload there is unproven. - Only calls that go through
HotFnconsult the jump table. A function the framework calls directly (theRenderimpl, element construction) is compiled into the patch but not invoked through the jump table, so editing it leaves the running UI unchanged. The scaffold keeps the element tree outside the boundary for exactly this reason. - Hot patching requires a build with
debug_assertionsenabled:HotFn::try_callcalls the local function directly in release builds, so the jump table is bypassed and code changes silently do not apply. - The boundary's return type must keep a fixed layout: the running host was compiled against the old
one. The scaffold uses
types::HotData, a fixed#[repr(C)]frame with a schema number; changeViewDataand its encoder, bumpSCHEMA, and never re-lay-outHotData. - The patch loader keeps each applied library mapped for the life of the process (unloading live patched code is unsafe). A ~12 KB patch keeps a long session bounded; an app-sized patch would grow the process by hundreds of MB per apply.
- A patch that cannot be loaded must not kill the listener.
auro::hothandlesapply_patcherrors and loader panics and keeps the previous jump table; the next edit can still apply. - A patched boundary must be pure data so a panic can be contained. The generated view wraps
hot_frameincatch_unwind, reports a rejected frame and keeps the previous values; removing a panic applied in 327 ms in the same process.
Open problems
- Hot mode is integrated behind
[dev] hot = true; open: change classification for edits outside the boundary (currently a patched, unchanged boundary), forced fallback restart, and a headless reload fixture. - Project/layout/build strategy: the four-crate
data/ui/types/bin shape is implemented and documented, including migration for older scaffolds; the author contract for larger reloadable units is open. Edits outsidedatarestart the devserver/app and restore the snapshot. - Snapshot format/versioning, incompatible-change classification, and state migration/reset policy.
- Representative D6 measurements on Auro apps/scaffolds (cold/warm, debug/release, more hardware and Windows/macOS coverage); Linux, Windows and macOS each have one scaffold series.
- Debugging, symbols, breakpoints, and backtraces through the chosen reload mechanism.
- Full view-code hot reload on Windows (element-returning hot boundaries crash after apply; the implemented layout keeps elements host-stable), macOS feasibility, signing/entitlements (a hardened-runtime dylib would be refused), debugger behavior, and CI verification beyond compiling the feature.