Architecture: Mounting & CellUI Shield

The mount function is the bridge between CellUI's pure-function components and the actual browser DOM.

Basic Mounting

To start a CellUI application, you must call mount() and pass it a selector (or HTML Element) and a function that returns your Root component's view.

import { mount } from '@cmj/cellui';
import { App } from './App';

// Mount asynchronously onto the #app element
mount('#app', () => App());

1. Asynchronous Layout (Non-Blocking)

CellUI is designed for extreme performance. When you call mount(), it does not evaluate your component immediately on the main thread.

Instead, it queues the render on the browser's requestIdleCallback(). This means CellUI waits until the browser has finished critical painting and layout tasks before injecting the UI, guaranteeing an ultra-fast Time-to-Interactive (TTI) score for your users.

2. Atomic DOM Swaps

Once the browser is idle, CellUI executes your App() function entirely in memory using a lightweight DocumentFragment.

When the fragment is ready, CellUI uses element.replaceChildren() to Atomically Swap the new application into the container. This prevents layout thrashing and ensures the user never sees a half-rendered application.

🛡️ CellUI Shield (Error Boundaries)

If your root component throws a synchronous JavaScript error during initialization, it usually results in a fatal "White Screen of Death" for the user.

CellUI prevents this natively using CellUI.Shield.

mount() automatically wraps the initial render in a try/catch block. If an error is caught:

  1. CellUI.Shield.panic is triggered.
  2. CellUI intercepts the crash and replaces the white screen with a graceful "Fallback UI" displaying the error message.
  3. A telemetry event (cellui:panic) is dispatched to the window so you can log the failure to your crash reporting service (like Sentry or Datadog).
// Example: Catching a CellUI crash in your analytics script
window.addEventListener('cellui:panic', (e) => {
  const { error, target } = e.detail;
  Sentry.captureException(error);
});

🧹 The "Kill Switch" (Unmounting)

Sometimes you need to completely destroy a CellUI application (e.g., when running Unit Tests, or if you are using CellUI as a micro-frontend inside another framework like React or Vue).

Because mount is asynchronous, it returns a Promise that resolves to a cleanup "Kill Switch" function.

Calling this function invokes CellUI.dispose(), instantly emptying the DOM and garbage collecting all signals.

import { mount } from '@cmj/cellui';

// Await the mount to get the kill switch
const unmount = await mount('#app', () => App());

// Later, perhaps when the user navigates away:
unmount(); 
// The DOM is now empty and all memory is freed!