@zubra/runtime 0.0.0-stage → 5.0.3

package/src/signal-impl.js

@@ -0,0 +1,375 @@
+// An implementation of the TC39 Signals proposal API (https://github.com/tc39/proposal-signals).
+//
+// This is zubra's polyfill boundary for reactivity: compiled components talk only to this API,
+// and runtime/src/signal.js uses the native `globalThis.Signal` instead whenever one exists.
+//
+// Model: push-pull with version numbers.
+//   - Every signal has a `version` that increments when its value actually changes (per
+//     `equals`), and every State write bumps a global `epoch`.
+//   - A Computed records, per dependency, the version it last read. On `get()` it re-validates
+//     by bringing each dependency up to date and comparing versions, and re-runs only if one
+//     really changed ("equality cut-off" — what makes reads glitch-free).
+//   - Signals reachable from a Watcher are "live": they keep back-links to their consumers, so
+//     a write can *push* a dirty mark down to watchers. Signals nobody watches keep no
+//     back-links, so an unwatched graph is garbage-collectable and costs nothing on write.
+//
+// Dependency bookkeeping is positional, with back-indices for O(1) unlinking, and follows the
+// proposal's reference polyfill exactly: the differential tests in runtime/test compare this
+// implementation with `signal-polyfill` on hand-written scenarios and hundreds of random graphs,
+// including the order in which watchers are notified and watched/unwatched hooks fire.
+// Deliberate differences (all stricter, none observable in correct programs) are listed in
+// runtime/README.md.
+
+const UNSET = Symbol('unset');
+const COMPUTING = Symbol('computing');
+const ERRORED = Symbol('errored');
+
+const watched = Symbol('watched');
+const unwatched = Symbol('unwatched');
+
+let activeConsumer = null;   // the node whose reads are currently being recorded
+let frozen = false;          // true while watchers are notified or hooks run
+let epoch = 0;
+
+const frozenError = () =>
+  new Error('Signals cannot be read or written during a Watcher notification or a watched/unwatched callback');
+
+// ---- graph nodes ---------------------------------------------------------------------------
+//
+// Consumer side (Computed, Watcher):
+//   sources[i]          the i-th dependency read (duplicates allowed, as in the reference)
+//   sourceVersions[i]   that dependency's version when it was read
+//   sourceSlots[i]      where this consumer sits in sources[i].sinks (only while live)
+//   nextSource          read cursor during a computation / append cursor for a Watcher
+// Producer side (State, Computed):
+//   sinks[j]            live consumers
+//   sinkSlots[j]        where this producer sits in sinks[j].sources
+
+class Node {
+  constructor(wrapper) {
+    this.wrapper = wrapper;
+    this.version = 0;
+    this.dirty = false;
+    this.sinks = [];
+    this.sinkSlots = [];
+    this.sources = [];
+    this.sourceVersions = [];
+    this.sourceSlots = [];
+    this.nextSource = 0;
+  }
+  get live() { return this.sinks.length > 0; }
+}
+
+class StateNode extends Node {
+  constructor(wrapper, value, options) {
+    super(wrapper);
+    this.value = value;
+    this.equals = options?.equals ?? Object.is;
+    this.onWatched = options?.[watched];
+    this.onUnwatched = options?.[unwatched];
+  }
+}
+
+class ComputedNode extends Node {
+  constructor(wrapper, computation, options) {
+    super(wrapper);
+    this.computation = computation;
+    this.value = UNSET;
+    this.error = undefined;
+    this.dirty = true;
+    this.lastCleanEpoch = -1;
+    this.equals = options?.equals ?? Object.is;
+    this.onWatched = options?.[watched];
+    this.onUnwatched = options?.[unwatched];
+  }
+}
+
+class WatcherNode extends Node {
+  constructor(wrapper, notify) {
+    super(wrapper);
+    this.notify = notify;
+  }
+  get live() { return true; }
+}
+
+// ---- liveness: linking and unlinking back-references ---------------------------------------
+
+function runFrozen(hook, receiver) {
+  if (typeof hook !== 'function') return;
+  const previous = frozen;
+  frozen = true;
+  try { hook.call(receiver); } finally { frozen = previous; }
+}
+
+/** Add `consumer` as a live sink of `producer`; returns the slot it occupies. */
+function link(producer, consumer, slotInConsumer) {
+  if (producer.sinks.length === 0) {
+    runFrozen(producer.onWatched, producer.wrapper);
+    for (let i = 0; i < producer.sources.length; i++) {
+      producer.sourceSlots[i] = link(producer.sources[i], producer, i);
+    }
+  }
+  producer.sinkSlots.push(slotInConsumer);
+  return producer.sinks.push(consumer) - 1;
+}
+
+/** Remove the live sink at `slot` of `producer` (swap-remove, fixing the moved back-index). */
+function unlink(producer, slot) {
+  if (producer.sinks.length === 1) {
+    runFrozen(producer.onUnwatched, producer.wrapper);
+    for (let i = 0; i < producer.sources.length; i++) unlink(producer.sources[i], producer.sourceSlots[i]);
+  }
+  const last = producer.sinks.length - 1;
+  producer.sinks[slot] = producer.sinks[last];
+  producer.sinkSlots[slot] = producer.sinkSlots[last];
+  producer.sinks.length = last;
+  producer.sinkSlots.length = last;
+  if (slot < last) producer.sinks[slot].sourceSlots[producer.sinkSlots[slot]] = slot;
+}
+
+// ---- tracking reads ------------------------------------------------------------------------
+
+function track(producer) {
+  if (frozen) throw frozenError();
+  const consumer = activeConsumer;
+  if (!consumer) return;
+  const i = consumer.nextSource++;
+  const previous = consumer.sources[i];
+  if (previous !== producer) {
+    if (previous !== undefined && consumer.live) unlink(previous, consumer.sourceSlots[i]);
+    consumer.sources[i] = producer;
+    consumer.sourceSlots[i] = consumer.live ? link(producer, consumer, i) : 0;
+  }
+  consumer.sourceVersions[i] = producer.version;
+}
+
+/** Drop dependencies from the last run that this run didn't read. */
+function trimSources(consumer) {
+  const count = consumer.nextSource;
+  if (consumer.live) {
+    for (let i = count; i < consumer.sources.length; i++) unlink(consumer.sources[i], consumer.sourceSlots[i]);
+  }
+  consumer.sources.length = count;
+  consumer.sourceVersions.length = count;
+  consumer.sourceSlots.length = count;
+}
+
+// ---- push: a write marks live consumers dirty and notifies watchers ------------------------
+
+function notifySinks(producer) {
+  const previous = frozen;
+  frozen = true;
+  try {
+    for (const consumer of producer.sinks) if (!consumer.dirty) markDirty(consumer);
+  } finally {
+    frozen = previous;
+  }
+}
+
+function markDirty(consumer) {
+  consumer.dirty = true;
+  notifySinks(consumer);
+  if (consumer instanceof WatcherNode && typeof consumer.notify === 'function') {
+    consumer.notify.call(consumer.wrapper);
+  }
+}
+
+// ---- pull: bringing a computed up to date --------------------------------------------------
+
+function refresh(node) {
+  if (!(node instanceof ComputedNode)) return;
+  // Validated during this epoch and not marked dirty since: nothing can have changed.
+  // (No shortcut for live nodes: a node that became live while stale was never marked dirty,
+  // and marking it would stop later writes from reaching its watchers.)
+  if (!node.dirty && node.lastCleanEpoch === epoch) return;
+  if (node.value === UNSET || node.value === COMPUTING || sourcesChanged(node)) recompute(node);
+  node.dirty = false;
+  node.lastCleanEpoch = epoch;
+}
+
+function sourcesChanged(node) {
+  for (let i = 0; i < node.sources.length; i++) {
+    const source = node.sources[i];
+    const seen = node.sourceVersions[i];
+    if (source.version !== seen) return true;
+    refresh(source);
+    if (source.version !== seen) return true;
+  }
+  return false;
+}
+
+function recompute(node) {
+  if (node.value === COMPUTING) throw new Error('Detected cycle in computations.');
+  const previousValue = node.value;
+  node.value = COMPUTING;
+  node.nextSource = 0;
+  const previousConsumer = activeConsumer;
+  activeConsumer = node;
+  let value;
+  let equal = false;
+  try {
+    value = node.computation.call(node.wrapper);
+    equal = previousValue !== UNSET && previousValue !== ERRORED
+      && node.equals.call(node.wrapper, previousValue, value);
+  } catch (error) {
+    value = ERRORED;
+    node.error = error;
+  } finally {
+    activeConsumer = previousConsumer;
+    trimSources(node);
+  }
+  if (equal) {
+    node.value = previousValue;
+    return;
+  }
+  node.value = value;
+  node.version++;
+}
+
+// ---- public API ----------------------------------------------------------------------------
+
+const nodes = new WeakMap();
+const nodeFor = (receiver, Kind, method) => {
+  const node = nodes.get(receiver);
+  if (!(node instanceof Kind)) throw new TypeError(`Wrong receiver type for ${method}`);
+  return node;
+};
+const isSignal = (value) => {
+  const node = nodes.get(value);
+  return node instanceof StateNode || node instanceof ComputedNode;
+};
+const isSink = (value) => {
+  const node = nodes.get(value);
+  return node instanceof ComputedNode || node instanceof WatcherNode;
+};
+
+class State {
+  constructor(initialValue, options) {
+    nodes.set(this, new StateNode(this, initialValue, options));
+  }
+
+  get() {
+    const node = nodeFor(this, StateNode, 'Signal.State.prototype.get');
+    track(node);
+    return node.value;
+  }
+
+  set(value) {
+    const node = nodeFor(this, StateNode, 'Signal.State.prototype.set');
+    if (frozen) throw new Error('Writes to signals not permitted during Watcher callback');
+    if (node.equals.call(this, node.value, value)) return;
+    node.value = value;
+    node.version++;
+    epoch++;
+    notifySinks(node);
+  }
+}
+
+class Computed {
+  constructor(computation, options) {
+    if (typeof computation !== 'function') throw new TypeError('Signal.Computed requires a function');
+    nodes.set(this, new ComputedNode(this, computation, options));
+  }
+
+  get() {
+    const node = nodeFor(this, ComputedNode, 'Signal.Computed.prototype.get');
+    // Checked before refreshing, so a forbidden read can't poison the cached value.
+    if (frozen) throw frozenError();
+    refresh(node);
+    track(node);
+    if (node.value === ERRORED) throw node.error;
+    return node.value;
+  }
+}
+
+class Watcher {
+  constructor(notify) {
+    nodes.set(this, new WatcherNode(this, notify));
+  }
+
+  /** Add signals to the watched set and re-arm notification. */
+  watch(...signals) {
+    const node = nodeFor(this, WatcherNode, 'Signal.subtle.Watcher.prototype.watch');
+    if (!signals.every(isSignal)) throw new TypeError('Called watch/unwatch without a Computed or State argument');
+    node.dirty = false;
+    const previousConsumer = activeConsumer;
+    activeConsumer = node;
+    try {
+      for (const signal of signals) track(nodes.get(signal));
+    } finally {
+      activeConsumer = previousConsumer;
+    }
+  }
+
+  /** Remove every occurrence of the given signals from the watched set. */
+  unwatch(...signals) {
+    const node = nodeFor(this, WatcherNode, 'Signal.subtle.Watcher.prototype.unwatch');
+    if (!signals.every(isSignal)) throw new TypeError('Called watch/unwatch without a Computed or State argument');
+    const removing = new Set(signals.map((signal) => nodes.get(signal)));
+    for (let i = node.sources.length - 1; i >= 0; i--) {
+      if (!removing.has(node.sources[i])) continue;
+      unlink(node.sources[i], node.sourceSlots[i]);
+      const last = node.sources.length - 1;
+      node.sources[i] = node.sources[last];
+      node.sourceSlots[i] = node.sourceSlots[last];
+      node.sourceVersions[i] = node.sourceVersions[last];
+      node.sources.length = last;
+      node.sourceSlots.length = last;
+      node.sourceVersions.length = last;
+      node.nextSource--;
+      if (i < last) node.sources[i].sinkSlots[node.sourceSlots[i]] = i;
+    }
+  }
+
+  /** The watched computeds that have been marked dirty and not yet re-read. */
+  getPending() {
+    const node = nodeFor(this, WatcherNode, 'Signal.subtle.Watcher.prototype.getPending');
+    return node.sources.filter((source) => source.dirty).map((source) => source.wrapper);
+  }
+}
+
+function untrack(callback) {
+  const previous = activeConsumer;
+  activeConsumer = null;
+  try { return callback(); } finally { activeConsumer = previous; }
+}
+
+function currentComputed() {
+  return activeConsumer instanceof ComputedNode ? activeConsumer.wrapper : undefined;
+}
+
+function introspectSources(sink) {
+  if (!isSink(sink)) throw new TypeError('Called introspectSources without a Computed or Watcher argument');
+  return nodes.get(sink).sources.map((source) => source.wrapper);
+}
+
+function introspectSinks(signal) {
+  if (!isSignal(signal)) throw new TypeError('Called introspectSinks without a Signal argument');
+  return nodes.get(signal).sinks.map((consumer) => consumer.wrapper);
+}
+
+function hasSinks(signal) {
+  if (!isSignal(signal)) throw new TypeError('Called hasSinks without a Signal argument');
+  return nodes.get(signal).sinks.length > 0;
+}
+
+function hasSources(sink) {
+  if (!isSink(sink)) throw new TypeError('Called hasSources without a Computed or Watcher argument');
+  return nodes.get(sink).sources.length > 0;
+}
+
+export const Signal = Object.freeze({
+  State,
+  Computed,
+  subtle: Object.freeze({
+    Watcher,
+    untrack,
+    currentComputed,
+    introspectSources,
+    introspectSinks,
+    hasSinks,
+    hasSources,
+    watched,
+    unwatched,
+  }),
+});

package/src/signal.js

@@ -0,0 +1,9 @@
+// The one place compiled zubra code gets reactivity from.
+//
+// If the platform provides the TC39 Signals API natively, use it. Otherwise fall back to our
+// implementation of the same API. Nothing else in the runtime may depend on which one it got,
+// so the day browsers ship `Signal`, this file is the only thing that changes behavior.
+import { Signal as Implementation } from './signal-impl.js';
+
+export const Signal = globalThis.Signal ?? Implementation;
+export const isNative = Signal !== Implementation;

package/src/spread.js

@@ -0,0 +1,154 @@
+// {...spread} in compiled components: an object's entries as an element's attributes,
+// properties and listeners. Its own entry (`@zubra/runtime/spread`), which a compiled module imports
+// only when its template spreads, so components that don't, don't load it.
+import { $r, isSafeUrl } from './element.js';
+import { effect } from './effect.js';
+
+const see = (section) => ` (see https://github.com/journey-to-code-org/zubra#${section})`;
+
+// ---- {...spread}: an object's entries as attributes, properties and listeners --------------
+
+// The same lists the compiler checks attributes against (src/validate.rs).
+const SPREAD_URLS = new Set(['action', 'background', 'cite', 'codebase', 'data', 'formaction', 'href', 'longdesc', 'manifest', 'poster', 'profile', 'src', 'xlink:href', 'usemap']);
+// Keys that would write markup or script: never from a spread.
+const SPREAD_REFUSED = new Set(['innerhtml', 'outerhtml', 'innertext', 'textcontent', 'srcdoc', 'dangerouslysetinnerhtml', 'children']);
+const SPREAD_PROPERTIES = new Set(['value', 'checked', 'selected', 'indeterminate']);
+const SPREAD_NAMES = { classname: 'class', htmlfor: 'for' };
+const kebab = (key) => (key.startsWith('--') ? key : key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`));
+
+/**
+ * `{...object}` on an element: each entry an attribute (`true` a bare one, `false`, `null` and
+ * `undefined` none; `aria-*` booleans as "true"/"false", as Zag and React write them), `on<Name>`
+ * functions listeners, `value`/`checked`/`selected`/`indeterminate` properties, `class` merged
+ * token by token, `style` an object set through the CSSOM. Keys the element binds itself
+ * (`part.own`) are left to it. Entries that disappear are removed. Nothing a spread does could
+ * not be done by an attribute: string handlers, style strings, unsafe URLs and markup are refused.
+ */
+export function spread(part, node) {
+  const own = new Set(part.own ?? []);
+  const listeners = new Map(); // event → { latest, listener }
+  let previous = new Map(); // normalized name → value
+  let classes = [];
+  let styles = new Set();
+  effect(() => {
+    let given = $r(part.spread());
+    if (given == null) given = {};
+    if (typeof given !== 'object' || Array.isArray(given)) {
+      console.error('zubra: {...} spreads an object of attributes; got', given);
+      given = {};
+    }
+    const next = new Map();
+    const events = new Set();
+    let nextClasses = [];
+    let nextStyles = new Set();
+    for (const [key, value] of Object.entries(given)) {
+      if (value === undefined) continue;
+      const lower = key.toLowerCase();
+      if (lower.length > 2 && lower.startsWith('on') && (typeof value === 'function' || typeof value === 'string')) {
+        if (typeof value === 'string') {
+          console.error(`zubra: a spread can't add a handler as text ("${key}"); pass a function${see('safety')}`);
+          continue;
+        }
+        const event = lower.slice(2);
+        if (own.has(`on${event}`)) continue;
+        events.add(event);
+        let entry = listeners.get(event);
+        if (!entry) {
+          entry = { latest: value, listener: (domEvent) => entry.latest.call(node, domEvent) };
+          listeners.set(event, entry);
+          node.addEventListener(event, entry.listener);
+        }
+        entry.latest = value;
+        continue;
+      }
+      const name = SPREAD_NAMES[lower] ?? (lower.startsWith('aria-') || lower.startsWith('data-') || node.namespaceURI !== 'http://www.w3.org/1999/xhtml' ? key : lower);
+      if (SPREAD_REFUSED.has(lower)) {
+        console.error(`zubra: a spread can't set "${key}"${see('safety')}`);
+        continue;
+      }
+      if (name === 'class') {
+        nextClasses = String(value ?? '').split(/\s+/).filter(Boolean);
+        continue;
+      }
+      if (name === 'style') {
+        if (value === null || value === false) continue;
+        if (typeof value !== 'object') {
+          console.error(`zubra: a spread's style must be an object of properties (set through the CSSOM), not text${see('safety')}:`, value);
+          continue;
+        }
+        for (const [property, propertyValue] of Object.entries(value)) {
+          const css = kebab(property);
+          if (own.has(`style:${css}`)) continue;
+          if (propertyValue == null || propertyValue === false) continue;
+          nextStyles.add(css);
+          if (node.style.getPropertyValue(css) !== String(propertyValue)) node.style.setProperty(css, String(propertyValue));
+        }
+        continue;
+      }
+      if (own.has(name.toLowerCase())) continue;
+      next.set(name, value);
+    }
+    // Listeners whose keys went away.
+    for (const [event, entry] of listeners) {
+      if (!events.has(event)) {
+        node.removeEventListener(event, entry.listener);
+        listeners.delete(event);
+      }
+    }
+    // Classes, token by token (the element's own class and class: toggles stay).
+    for (const token of classes) if (!nextClasses.includes(token)) node.classList.remove(token);
+    for (const token of nextClasses) node.classList.add(token);
+    classes = nextClasses;
+    for (const css of styles) if (!nextStyles.has(css)) node.style.removeProperty(css);
+    if (styles.size && !nextStyles.size && node.getAttribute('style') === '') node.removeAttribute('style');
+    styles = nextStyles;
+    // Attributes and properties.
+    for (const [name, value] of previous) {
+      if (next.has(name)) continue;
+      if (SPREAD_PROPERTIES.has(name)) node[name] = name === 'value' ? '' : false;
+      else node.removeAttribute(name);
+    }
+    for (const [name, value] of next) {
+      if (SPREAD_PROPERTIES.has(name) && name in node) {
+        const property = name === 'value' ? (value == null ? '' : String(value)) : !!value;
+        if (node[name] !== property) node[name] = property;
+        continue;
+      }
+      if (value === null || value === false && !name.startsWith('aria-')) {
+        node.removeAttribute(name);
+        continue;
+      }
+      if (typeof value === 'boolean') {
+        if (name.startsWith('aria-')) node.setAttribute(name, String(value));
+        else node.toggleAttribute(name, value);
+        continue;
+      }
+      if (typeof value === 'object' || typeof value === 'function') {
+        console.error(`zubra: a spread can't write ${typeof value === 'function' ? 'a function' : 'an object'} to the "${name}" attribute`, value);
+        node.removeAttribute(name);
+        continue;
+      }
+      const text = String(value);
+      if (SPREAD_URLS.has(name.toLowerCase())) {
+        if (text.trim() === '') {
+          node.removeAttribute(name);
+          continue;
+        }
+        if (!isSafeUrl(text)) {
+          console.error(`zubra: blocked an unsafe URL in "${name}"${see('safety')}:`, text);
+          node.removeAttribute(name);
+          continue;
+        }
+      }
+      if (node.getAttribute(name) !== text) node.setAttribute(name, text);
+    }
+    previous = next;
+    return undefined;
+  });
+  // The listeners go with the element's scope.
+  effect(() => () => {
+    for (const [event, entry] of listeners) node.removeEventListener(event, entry.listener);
+    listeners.clear();
+  });
+}
+

package/src/vue.js

@@ -0,0 +1,125 @@
+// Vue 3 adapter: a zubra element as a Vue component.
+//
+//   <script setup>
+//   import Rating from './rating.zb'          // the build plugin wraps it for .vue files
+//   </script>
+//   <Rating v-model="stars" @change="saved" />
+//
+// - Props are set as DOM properties when the element is created, before it starts, so it never
+//   renders with defaults first. A prop that's left out is the component's default.
+// - The component's events are Vue events (`@valuechange`); the handler gets the DOM event.
+// - Two-way binding comes from naming: a `<prop>` + `<prop>change` pair supports
+//   `v-model:<prop>`, and `v-model` binds the `value` pair (or the only pair, if there's one).
+// - Other attributes and listeners (class, style, @click, …) go to the element; slots become its
+//   children, named slots with `slot="name"`.
+import { defineComponent, h, withDirectives, Text, Comment, Fragment } from 'vue';
+import { serverContent } from './server.js';
+
+const clone = (value) => (value && typeof value === 'object' ? structuredClone(value) : value);
+const pascal = (tag) => tag.split(/[-.]/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join('');
+
+/** `<prop>` + `<prop>change` pairs: the component's two-way bindings. */
+export function models({ props, events }) {
+  return Object.keys(props)
+    .filter((name) => events.includes(`${name.toLowerCase()}change`))
+    .map((name) => ({ prop: name, event: `${name.toLowerCase()}change` }));
+}
+
+/** Give each node of a named slot its `slot` attribute (text gets a <span> to carry it). */
+function named(name, nodes) {
+  return nodes.flatMap((node) => {
+    if (node.type === Fragment) return named(name, node.children ?? []);
+    if (node.type === Comment) return [];
+    if (node.type === Text || typeof node !== 'object') return [h('span', { slot: name }, node.children ?? String(node))];
+    return [h(node, { slot: name })];
+  });
+}
+
+const same = (a, b) => Object.is(a, b);
+
+/** The given props as JSON for the host's `zb-props`, or null. */
+function propsJson(values) {
+  const given = Object.entries(values).filter(([, value]) => value !== undefined && typeof value !== 'function');
+  if (!given.length) return null;
+  try {
+    return JSON.stringify(Object.fromEntries(given));
+  } catch {
+    return null;
+  }
+}
+
+// Props are set by a directive, after Vue creates the element and before it's inserted (so before
+// the element starts) and before each update. Not as `.name` DOM props: Vue turns `null` into
+// `0`, `''` or `false` there, by the property's current type, and a prop's null is meaningful.
+const setProps = {
+  beforeMount(element, { value }) {
+    for (const name of Object.keys(value)) element[name] = value[name];
+  },
+  beforeUpdate(element, { value }) {
+    for (const name of Object.keys(value)) if (!same(element[name], value[name])) element[name] = value[name];
+  },
+};
+
+export function wrap(Element) {
+  const meta = Element?.zubra;
+  if (!meta) throw new TypeError('zubra: wrap() needs a compiled zubra element (the default export of a .zb module)');
+  const { tag, props, events } = meta;
+  const pairs = models(meta);
+  const primary = pairs.find((pair) => pair.prop === 'value') ?? (pairs.length === 1 ? pairs[0] : null);
+
+  return defineComponent({
+    name: pascal(tag),
+    inheritAttrs: false,
+    props: {
+      ...Object.fromEntries(Object.keys(props).map((name) => [name, { default: undefined }])),
+      ...(primary ? { modelValue: { default: undefined } } : {}),
+    },
+    emits: [
+      ...events,
+      ...pairs.map((pair) => `update:${pair.prop}`),
+      ...(primary ? ['update:modelValue'] : []),
+    ],
+    setup(given, { attrs, slots, emit, expose }) {
+      const listeners = Object.fromEntries(events.map((name) => {
+        // `on` + the name as given is how Vue's patchProp attaches a listener for exactly it.
+        const key = `on${name[0].toUpperCase()}${name.slice(1)}`;
+        return [key, (event) => {
+          // Only the element's own event (one from inside with the same name was stopped there).
+          emit(name, event);
+          for (const pair of pairs) {
+            if (pair.event !== name) continue;
+            emit(`update:${pair.prop}`, event.detail);
+            if (pair === primary) emit('update:modelValue', event.detail);
+          }
+        }];
+      }));
+      let element = null;
+      const defaults = {}; // one copy per instance, so re-rendering doesn't set a new one
+      expose({ get element() { return element; } });
+      return () => {
+        const values = {};
+        for (const name of Object.keys(props)) {
+          let value = given[name];
+          if (primary && name === primary.prop && given.modelValue !== undefined) value = given.modelValue;
+          values[name] = value === undefined ? (defaults[name] ??= clone(props[name].default)) : value;
+        }
+        const children = [];
+        for (const [name, slot] of Object.entries(slots)) {
+          const nodes = slot() ?? [];
+          children.push(...(name === 'default' ? nodes : named(name, nodes)));
+        }
+        // The given props as JSON, on the server and in the browser alike (see the React adapter).
+        const json = propsJson(Object.fromEntries(Object.keys(props).map((name) => [name, primary && name === primary.prop && given.modelValue !== undefined ? given.modelValue : given[name]])));
+        // An element with no children: on the server, its content (a shadow-DOM element's
+        // declarative shadow root, a light-DOM element's rendered children) as the host's inner
+        // HTML, so it shows before JavaScript. In the browser the vnode has no children at all
+        // (`null`, not `[]`): Vue then never looks inside the host while hydrating, so the
+        // element's markup stays for the element to hydrate in place (3.3). (A page can also go
+        // through @zubra/server's injectShadowRoots, which is the same for shadow DOM.)
+        const bare = children.length === 0;
+        const inner = bare && typeof window === 'undefined' ? { innerHTML: serverContent(Element, { props: json ? JSON.parse(json) : {}, name: attrs.name }) } : {};
+        return withDirectives(h(tag, { ...attrs, ...listeners, ...(json ? { 'zb-props': json } : {}), ...inner, ref: (node) => { element = node; } }, bare ? null : children), [[setProps, values]]);
+      };
+    },
+  });
+}