Limits and plans
What Exodra does not do yet, what it will never do, and why. Everything here was measured against the current code rather than assumed — where a limit exists, the test that pins it is named, so you can check the claim and watch it change.
Custom elements
Rendering a custom element works today: the tag is created, the element upgrades, and ordinary attributes reach it.
import { exoJsx, type TExoSchemaElementProps } from '@exodra/jsx/schema';
declare module '@exodra/jsx/schema/jsx-runtime' {
namespace JSX {
interface IntrinsicElements {
'my-widget': TExoSchemaElementProps;
}
}
}
export const widgetSchema = exoJsx(($) => <my-widget id="chart" title={$.heading} />);
Event names work. An event port carries its name verbatim
to addEventListener, so on:sl-change={handleChange} — the convention every
component library follows — is heard. Nothing is lowercased and nothing is
mapped, on either the direct or the delegated pack.
Properties still are. A custom element takes structured data through a JS
property, not through an attribute — el.items = [...]. An attribute port
writes an attribute, so an object or an array arrives as "[object Object]".
Whether a name is a property is decided from a table (EXO_DOM_PROPERTIES) and, for
the names where the tag matters, from exoDomPropertyKind(tag, name) — which is how
value, checked and selected are resolved. A custom element cannot be in
that table and cannot be asked either: before it upgrades it has no properties at
all, so the intent has to come from whoever wrote the schema.
The JSX dialect has no way to say "write this one as a property" either: attr={$.x}
is an attribute port, on: is the only namespace, and any
other namespace (prop:options={…}) is refused by name. How the dialect should
spell a property write is still open.
One subtlety is worth knowing before it lands: if a component's definition is
loaded lazily, a property written before the element upgrades is shadowed by the
class field when it does. Writing after customElements.whenDefined avoids it and
costs a turn of the event loop, and which of the two Exodra should do is exactly
the question that is still open.
Until then, the way through is the child's own mount hook — it runs once the
element is in the tree, which is also when a widget wants to be measured or
focused:
import { wireExoNode } from '@exodra/core';
import { exoNodeDom } from '@exodra/dom';
const child = c.createExoNode(Select);
wireExoNode(child, params);
exoNodeDom(child).mount = function () {
(this.node as HTMLElement & { options: unknown }).options = items;
};
c.appendChild(FormPorts.select, child);
That hook is called by the children stack, so it fires for anything placed
through a children port — c.one, c.list, the port methods (c.appendChild, c.insertChild;
see Children) or a reconciler made by createExoChildrenReconciler — and
not for the root instance backend.render puts in a parent itself.
Pages that other software has edited
A browser translator, an extension, a password manager or a bookmarklet will
rewrite parts of your page without telling anyone. Chrome's translator, in
particular, does not edit a text node — it takes it out and puts a <font>
element in its place. Any renderer holding that node is then holding a node the
document has moved or discarded, and the classic result is a crash on the next
update.
Exodra does not crash, and it does not freeze either. A bound text port caches
the Text node it wrote so that an update is a .data store rather than a
textContent assignment — but the cache is trusted only while that node is still
its element's one and only child, and when it is not, the write falls back to
textContent and re-caches whatever the browser made
(packages/dom/src/dom/tests/text-binding.test.ts). That covers any software that
replaces the node, and both shapes a translator produces in particular:
- Wrapped — your
Textnode is moved inside a<font>that took its place. Without the guard,cached.data = …would keep succeeding on a node the element no longer renders, and the page would freeze at the translated text with no error anywhere. The fallback writes through and the wrapper goes with it. - Replaced — your node is discarded and a copy of the text appears inside the translator's element. There is nothing to recover the mapping from, so the most any renderer can do is notice and rebuild, which is what happens: the next update prints the new value and clears the wrapper.
Lists are covered by the same rule at the element level: every insertion and
removal asks the document who a node's parent currently is rather than trusting
what it cached, so removing a row takes the <font> that swallowed it with it
(packages/dom/src/dom/tests/reconcile-exo-order.test.ts).
What no renderer can restore is the translation: after a rebuild the text is your value, untranslated, until the translator gets to it again.
If a page mixes heavy reactivity with text that translators will attack, the cheap insurance is to opt out of translation for that part:
<meta name="google" content="notranslate" />
Focus when a list is reordered
Moving a focused element loses focus — in Exodra, and in every other framework,
because the DOM specification removes a node before it re-inserts it, even when
the "move" is a single insertBefore call. Verified in Chromium, not deduced.
The caret position inside an input survives; the focus does not.
This is not on the list to fix: a renderer cannot tell a deliberate reorder from
a rebuild, and restoring focus behind your back would be wrong as often as it
would be right. If a list is reorderable while someone is typing in it, save
document.activeElement and restore it after the change.
Server rendering
@exodra/string and @exodra/ssr render a schema to HTML, and hydration attaches
to it. Custom elements render as their tag with attributes — their shadow content
is theirs to produce, and Exodra does not attempt declarative shadow DOM.
Known issues
These are known, measured where a measurement exists, and not yet solved. Each names where its number comes from, so it can be re-run and watched as it moves.
Components are longer than in React or Solid
The application every benchmark axis mounts is 477 lines in Exodra, against
208 in React and 220 in Solid, counted by the harness itself with
TypeScript's parser, comments and blank lines excluded (the app LOC column of
initial-render). A schema built with createExoSchema declares its ports by
hand, and a machine names every transition it runs. That is the cost of having
no compiler in the way, and nothing yet makes it shorter.
Updates sit further from their floor than mounting does
Mounting is within 1.35–1.42× of a hand-written program producing the same DOM
(What the floor says). Updates, each against a
hand-written program doing the same job (update-floor.shuffled): a list that
grows and shrinks is level with hand-written diff code (1.000×), and the rest
sit above their floor — text-sweep 1.522×, text-one 1.562×, reorder
1.566× and wide 2.242×, the application-wide flip.
Without the compiler, @exodra/react-compat mounts level with React, not ahead
Measured on the benchmark application with production builds, in narrowed runs
(ratios only, inside one run, initial-render.compat8): mounting with host
templates, which are on by default, took 1.000 ms against React's 0.980. The compiled path,
@exodra/babel-plugin-schema/react, took 0.860. On app-update
(app-update.compat8) the axis reports no resolution, so only the order is
known: compiled, then templates, then React.
Toggling a large block rebuilds it by default
Tearing out 200 panels and building others takes 10.2 ms out of the box against
Solid's 9.2 (toggle.base1). Keeping the subtree alive takes 3.3, but that row
builds its panels in advance and so is not comparable with Solid or any other
framework; the default rebuilds.
The cost of building a schema cannot be re-measured
schema-build.published puts a runtime schema at roughly 0.26–0.29 µs per
element, once per module load. The axis that produced it is no longer in the
tree, so the figure cannot be reproduced until it is written again.