@gomani/runtime

The tiny client runtime of Gomani: a fine-grained reactive DOM renderer and on-demand island hydration.

Loaded once per page — and only when the page actually has islands — this is the single shared cost every island chunk reuses. There is no global startup pass ("resumability-lite"): start() only wires cheap triggers, and an island's chunk is fetched and rendered only when its strategy fires. Interactive cost is decoupled from app size (P3).

start() — boot island hydration

Put this once on any page that has islands. It scans for <gomani-island> markers (emitted by @gomani/core's renderToString) and wires each one's load trigger.

import { start } from '@gomani/runtime';

start(); // reads island name→URL from <script type="application/json" id="gomani-islands">

Each island wakes on its own strategy — load, idle, visible (default), interaction, or media — then its chunk is imported and the component is mounted into the marker, replacing the server HTML with a live, reactive render seeded from the marker's serialized props. Already-hydrated islands are skipped, so start() is safe to call more than once.

start({
  root: document, // where to scan (default document)
  manifest: { counter: '/islands/counter.js' }, // name → chunk URL (else read from the DOM)
  loader: (name) => import(urlFor(name)), // override how a chunk is fetched
});

mount() — reactive DOM rendering

The renderer islands use internally, exported for advanced/manual mounting. No virtual DOM, no diffing: a signal used as a child or attribute is bound to exactly one text node or attribute, so an update touches only that node.

import { mount } from '@gomani/runtime';
import { signal } from '@gomani/signals';

const count = signal(0);
const dispose = mount(
  <button onClick={() => count.value++}>{count}</button>,
  document.getElementById('app')!,
);
// dispose() tears down every effect and event listener.

License

MIT © Venancio Gomani / Kwacha Kulture.