Controller Tooling & HMR
RadiantController registration is intentionally stable by default.
That stability matters because controller identifiers are global and controller runtimes may already have live instances attached to DOM nodes by the time another module evaluates.
Default Contract
The default registry contract is:
@controller(...)uses first-registration-wins semanticsregisterController(...)keeps the original class for an identifier- a later registration does not mutate already-connected instances
That is the safe runtime contract for application code.
It prevents accidental double imports, repeated side-effect evaluation, or duplicate bundle edges from silently swapping controller behavior underneath a live page.
Explicit Mutation Path
When tooling really does need mutation, the registry exposes separate opt-in APIs through @ecopages/radiant/controller-registry.
Use these APIs deliberately:
replaceController(identifier, ControllerClass)replaces the registered class and reconnects matching live hostsenableControllerReplacementForHmr()switches decorator-driven registration into replacement mode for the current runtime
Vite sets import.meta.hot in development, so a Vite app can gate the opt-in on it:
import { enableControllerReplacementForHmr } from '@ecopages/radiant/controller-registry';
if (import.meta.hot) {
enableControllerReplacementForHmr();
}That helper is intentionally named for tooling. It is not meant as normal application setup.
Ecopages
Under ecopages dev, import.meta.hot is never set, so the guard above never fires and controller replacement stays off. Ecopages also exposes no public development flag for browser code, so you gate the call yourself. Import the helper from a browser entry that you only load in development, and call it before the controller modules evaluate:
import { enableControllerReplacementForHmr } from '@ecopages/radiant/controller-registry';
enableControllerReplacementForHmr();Replacement mode only changes what happens when a controller module is evaluated a second time, which happens when Ecopages re-imports a changed module. It does not stop the page from re-rendering:
- When the saved module is the active page module, Ecopages asks the router to reload the current page. The browser router morphs the body and replaces custom-element hosts, so each host gets
disconnectedCallbackand thenconnectedCallback. - That replacement can reset controller state whether controller replacement is on or off.
Treat controller state as disposable during ecopages dev.
Docs-App Integration
This docs app re-exports enableControllerReplacementForHmr from apps/docs/src/utils/radiant-browser-runtime.ts, but it does not call it. The shared browser shell does not enable replacement, so docs pages use the default registration contract.
Shared Runtime Integration
The Ecopages JSX browser-runtime bootstrap only installs the Radiant hydrator:
import { installRadiantHydrator } from '@ecopages/radiant/client/hydrator';
installRadiantHydrator();It does not import enableControllerReplacementForHmr(). An application that wants replacement under ecopages dev adds the call itself, as in the Ecopages section above.
Design Debt To Keep Visible
The global browser bootstrap belongs to the JSX plugin, while controller registration belongs to the Radiant runtime. Until the bootstrap has an extension point for Radiant setup, each application owns its development-only opt-in.
That is better than making @controller(...) mutating by default.
Recommendation
Use this rule:
- application runtime: keep default registration semantics
- tooling and HMR: opt into explicit replacement
- framework integration: call the opt-in from the highest development-only browser entry you control
For this repo today, that highest shared bootstrap is the base layout script.
For Ecopages JSX generally, the right eventual destination is the plugin runtime bundle service.