@xuda/core
The dependency-free reactive engine the platform, the compiler and the demo apps all mount on.
@xuda/core is the Xuda reactive engine (signals, scheduler, keyed list diff, reactive renderer,
router) as a dependency-free ESM package. It reads and writes no globals on import: no func, no
SESSION_OBJ, no window, no document.
@xuda/core's package.json carries "private": false. It is the only package among the three
covered in this section (alongside @xuda/compiler and @xuda/vite-plugin-xu, both private: true)
built to be depended on outside this repository.
It is also not a separate engine from the one the platform already ships: the package's own
build:globals script (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) is how runtime/js/xuda_core.globals.js, the platform's own
shipped reactive-renderer bundle, gets built.
The reactive surface
There is one dependency graph, one owner tree, one batch buffer and one scheduler underneath all of
it: a ref read inside an effect() tracks and re-runs it, the same as a signal read inside a
watch(). computed here accepts a getter, or a { get, set } pair for a writable computed.
effectScope() answers "who disposes this": a named owner you can hand around, nest and stop in one
call, instead of hand-rolling a bag of disposers.
A component instantiated through createApp() already owns one of these: its <script> runs
inside the component's own detached scope, so an effect written there is disposed automatically when
the component unmounts.
The low-level primitive
signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) and
signalComputed are the engine's own cells underneath ref and computed. They are exported and
fully supported, not removed, because the renderer and the legacy bridge are built on them, and
because signal.notify(), re-running subscribers with no value change, has no ref equivalent.
Application code should reach for ref and computed instead; these two names are documented as
the layer below, not deprecated at runtime (a warning on signal() would fire per row scope and per
panel param, thousands of times a screen, for code doing exactly the right thing at that layer).
The app entry point
App is a compiled .xu module, produced by @xuda/compiler or the
vite-plugin-xu build step. createApp builds the seven injected deps the renderer needs over the
thunk table the module's setup() returns, creates the renderer, and mounts the component tree. It
is not a second renderer: the compiled path and the interpreted platform path share render.js.
examples/hello is the concrete, tested version of this: createApp(App).mount('#app') over a
compiled App.xu with a counter, a conditional and a keyed list.
The renderer, dependency-injected
create_renderer(deps) is DOM-agnostic. Everything environmental arrives through one deps object,
and the smallest honest host needs exactly seven of them: document (createElement /
createTextNode / createComment), evaluate (a tracked, synchronous expression evaluator), cast_bool
(truthiness for xu-render / xu-if), resolve_rows (a tracked row-array resolver for xu-for),
row_key (stable row identity), write_field (xu-bind writes) and dispatch_event (xu-on:*
handlers). packages/core/demo builds exactly this over a plain reactive({...}) object, with no
SESSION_OBJ, no datasource layer and no legacy bridge anywhere underneath.
A deps.document node with no nodeType is read as a jQuery object rather than a real DOM node,
which can nest every row inside its predecessor with no thrown error. A node with no remove()
turns a dropped row into a silently rejected promise: the list stops updating and nothing is logged.
create_adapter in the demo guards both by throwing at node-creation time; pass { guard: false }
to opt out once you understand why the guard exists.
Diagnostics and whenElement
onDiagnostic, getDiagnostics, diagnosticCount and resetDiagnostics turn the engine's silent
give-ups into one observable channel, rather than scattered console.error calls, so a host adapter
or a test can subscribe to them by code. whenElement runs a callback once a node exists: it asks
once, then re-asks on the scheduler's commit phase (exactly when the DOM settles, before paint), and
a wait still unsatisfied after twenty settled renders reports itself by name rather than giving up
silently.
The router
createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter and
useRoute ship from the same package. The current route is @xuda/core's own reactive, and
history comes from the platform, so using it adds no dependency of its own.
Package exports
Node 18 or newer is the declared engine floor.