@zubra/runtime 5.6.0 → 5.8.0

package/src/context.js

@@ -0,0 +1,100 @@
+// Context from the app: a `<zb-context>` element that answers the Context Protocol for the
+// elements inside it, so an app's theme, locale or current user reaches every component without
+// being passed down as props.
+//
+//   <zb-context .context=${theme} .value=${'dark'}>   …elements that inject(theme)…   </zb-context>
+//
+// It's a plain custom element with two properties, so every framework can use it as it is:
+// Svelte `<zb-context {context} {value}>`, Solid `prop:context`, Angular `[context]`, Lit
+// `.context`, plain HTML `el.value = …`. React and Vue have `ZubraContext` components
+// (`@zubra/runtime/react`, `@zubra/runtime/vue`) that wrap it. The element is `display:
+// contents`, so it adds no box to the layout.
+//
+// The value can be a plain value or a signal; subscribers hear each change either way. Any
+// Context Protocol consumer is answered: Zubra's `inject()`, Lit's `@consume`, and so on. A
+// consumer that asked before the element was given its context asks again when the element
+// announces it with a `context-provider` event (children connect after their parent, so one
+// given its context before it's in the document is there when they first ask).
+import { Signal } from './signal.js';
+import { effect, root } from './effect.js';
+import { ContextProviderEvent } from './element.js';
+
+const isSignal = (value) => value instanceof Signal.State || value instanceof Signal.Computed;
+const unwrap = (value) => (isSignal(value) ? value.get() : value);
+
+const Base = globalThis.HTMLElement ?? class {};
+
+export class ZubraContextElement extends Base {
+  #context = undefined;
+  #value = undefined;
+  #subscribers = new Set();
+  #watching = null; // the effect following a signal value
+
+  constructor() {
+    super();
+    this.addEventListener('context-request', (event) => {
+      if (this.#context === undefined || event.context !== this.#context || event.contextTarget === this) return;
+      event.stopPropagation();
+      const current = Signal.subtle.untrack(() => unwrap(this.#value));
+      if (!event.subscribe) return event.callback(current);
+      const subscriber = { callback: event.callback };
+      subscriber.unsubscribe = () => this.#subscribers.delete(subscriber);
+      this.#subscribers.add(subscriber);
+      event.callback(current, subscriber.unsubscribe);
+    });
+  }
+
+  /** The context key this element provides (from `createContext()`, or any protocol key). */
+  get context() {
+    return this.#context;
+  }
+
+  set context(key) {
+    if (key === this.#context) return;
+    // Consumers of the old key keep what they have, but stop hearing from this element.
+    this.#subscribers.clear();
+    this.#context = key;
+    this.#announce();
+  }
+
+  /** The value, or a signal holding it. */
+  get value() {
+    return this.#value;
+  }
+
+  set value(next) {
+    if (Object.is(next, this.#value)) return;
+    this.#value = next;
+    this.#watching?.dispose();
+    this.#watching = null;
+    if (isSignal(next)) {
+      let first = true;
+      this.#watching = root(() => effect(() => {
+        const value = next.get();
+        if (first) first = false;
+        else Signal.subtle.untrack(() => this.#notify(value));
+      }));
+    }
+    this.#notify(Signal.subtle.untrack(() => unwrap(next)));
+  }
+
+  connectedCallback() {
+    if (!this.style.display) this.style.display = 'contents';
+  }
+
+  #notify(value) {
+    for (const subscriber of [...this.#subscribers]) subscriber.callback(value, subscriber.unsubscribe);
+  }
+
+  #announce() {
+    if (this.#context !== undefined && this.isConnected) this.dispatchEvent(new ContextProviderEvent(this.#context, this));
+  }
+}
+
+/** Define `<zb-context>` (once; a no-op where there's no `customElements`, as on a server). */
+export function defineContextElement() {
+  const registry = globalThis.customElements;
+  if (registry && !registry.get('zb-context')) registry.define('zb-context', ZubraContextElement);
+}
+
+defineContextElement();

package/src/element.js

@@ -63,6 +63,15 @@ const clone = (value) => (value && typeof value === 'object' ? structuredClone(v
 /** Attribute text → prop value, typed by the prop's default (JSON for arrays and objects). */
 function parseAttribute(spec, raw) {
   const fallback = spec.default;
+  // An enum prop (`<script lang="ts">`): the member whose value the text is, or the member it names.
+  if (spec.enum) {
+    if (raw === null) return clone(fallback);
+    const found = Object.values(spec.enum).find((value) => String(value) === raw);
+    if (found !== undefined) return found;
+    if (Object.hasOwn(spec.enum, raw)) return spec.enum[raw];
+    console.warn(`zubra: attribute "${spec.attribute}" is "${raw}", not one of ${Object.keys(spec.enum).join(', ')}`);
+    return clone(fallback);
+  }
   if (typeof fallback === 'boolean') return fallback ? raw !== 'false' : raw !== null;
   if (raw === null) return clone(fallback);
   if (typeof fallback === 'number') return Number(raw);
@@ -1564,6 +1573,18 @@ function defineElement(tag, definition) {
   const live = new Set(); // WeakRefs to the elements, kept only for hot reloads
   // @hot-end
   const byAttribute = Object.fromEntries(Object.entries(props).map(([name, spec]) => [spec.attribute, name]));
+  // HTML lowercases attribute names, so `maxValue` in a page arrives as `maxvalue`, which isn't
+  // the prop's attribute (`max-value`): the element would ignore it without a word.
+  const lowercased = Object.entries(props)
+    .filter(([name, spec]) => name !== name.toLowerCase() && spec.attribute !== name.toLowerCase())
+    .map(([name, spec]) => [name.toLowerCase(), name, spec.attribute]);
+  const checkAttributeCase = (element) => {
+    for (const [lower, name, attribute] of lowercased) {
+      if (element.hasAttribute(lower) && !element.hasAttribute(attribute)) {
+        console.warn(`zubra: <${tag}> ignores the attribute "${lower}": HTML lowercases attribute names, and the prop ${name} is the attribute "${attribute}"${see('writing-a-component')}`);
+      }
+    }
+  };
 
   let internals; // (element) => its ElementInternals; set in the static block below
   class ZubraElement extends HTMLElement {
@@ -1658,7 +1679,10 @@ function defineElement(tag, definition) {
         // Server markup without its comments: start once the code that puts them back is here.
         loadRemark().then(() => { if (this.isConnected && !this.#scope) this.connectedCallback(); });
         return;
-      } else this.#boot();
+      } else {
+        if (lowercased.length) checkAttributeCase(this);
+        this.#boot();
+      }
       this.#cleanups = this.#hooks.mount.map((fn) => fn()).filter((cleanup) => typeof cleanup === 'function');
       this.#started();
     }

package/src/forms.js

@@ -0,0 +1,125 @@
+// Form libraries: a Zubra control as a field of React Hook Form, TanStack Form, VeeValidate or
+// Felte. Each helper turns what the library hands you for a field into the props (or the Svelte
+// action) a Zubra control takes, through its two-way binding: a `<prop>` and its `<prop>change`
+// event (`value` and `valuechange` by default).
+//
+//   React Hook Form   <Stepper {...registerProps(register('seats'))} />
+//                     <Controller name="seats" render={({ field }) => <Stepper {...fieldProps(field)} />} />
+//   TanStack Form     <form.Field name="seats">{(field) => <Stepper {...fieldProps(field)} />}</form.Field>
+//   VeeValidate       <Stepper v-bind="vueFieldProps(useField('seats'))" />
+//   Felte             <zb-stepper use:felteControl={createField('seats')}>
+//
+// Nothing here imports a library: each helper reads the shape the library documents. Native
+// form submission needs none of this; a Zubra control with `form-associated` is already a form
+// control (FormData, `<form method=post>`, server actions).
+
+const handler = (prop) => `on${prop.toLowerCase()}change`; // the React wrapper takes any casing
+const unref = (value) => (value && typeof value === 'object' && value.__v_isRef ? value.value : value);
+
+/**
+ * React Hook Form's `register(name)` as props for a wrapped Zubra control: the control's
+ * `value`, its `valuechange` reported as a change, blur reported as a blur, and the element as
+ * the ref (so `reset()` and `setValue()` write its `value`, and `setFocus()` focuses it). For a
+ * control whose model isn't `value`, use `fieldProps` with a `<Controller>`.
+ */
+export function registerProps(registration) {
+  const { name, ref, onChange, onBlur, disabled } = registration;
+  return {
+    name,
+    ref,
+    ...(disabled === undefined ? {} : { disabled }),
+    onvaluechange: (event) => onChange({ type: 'change', target: { name, value: event.detail } }),
+    onBlur: (event) => onBlur({ type: 'blur', target: { name, value: event.currentTarget?.value } }),
+  };
+}
+
+/**
+ * A field's props for a wrapped Zubra control in React, from React Hook Form's `<Controller>`
+ * (`{ value, onChange, onBlur, name, ref }`) or TanStack Form's field API
+ * (`{ state: { value }, handleChange, handleBlur, name }`). `prop` names the control's model
+ * (`value` by default).
+ */
+export function fieldProps(field, { prop = 'value' } = {}) {
+  const tanstack = typeof field.handleChange === 'function';
+  const value = tanstack ? field.state.value : field.value;
+  const change = tanstack ? field.handleChange : field.onChange;
+  const blur = tanstack ? field.handleBlur : field.onBlur;
+  return {
+    name: field.name,
+    [prop]: value,
+    [handler(prop)]: (event) => change(event.detail),
+    onBlur: () => blur(),
+    ...(field.ref ? { ref: field.ref } : {}),
+  };
+}
+
+/**
+ * A field's props for a wrapped Zubra control in Vue, from VeeValidate's `useField()` (whose
+ * `value` is a ref) or the `field` a `<Field v-slot="{ field }">` gives. `prop` names the
+ * control's model (`value` by default).
+ */
+export function vueFieldProps(field, { prop = 'value' } = {}) {
+  const change = field.handleChange ?? field.onChange;
+  const blur = field.handleBlur ?? field.onBlur;
+  const value = 'value' in field ? unref(field.value) : field.modelValue;
+  return {
+    name: unref(field.name),
+    [prop]: value,
+    [`onUpdate:${prop}`]: (next) => (Array.isArray(change) ? change.forEach((fn) => fn(next)) : change(next)),
+    // The control's own focus leaves it: `blur` doesn't bubble out of its inner input, `focusout` does.
+    onFocusout: (event) => (Array.isArray(blur) ? blur.forEach((fn) => fn(event)) : blur?.(event)),
+  };
+}
+
+/**
+ * Felte: a Svelte action (or a plain function for `@felte/vanilla`) that connects a Zubra control
+ * to a field from Felte's `createField(name)`. Felte reads native inputs, so the field keeps a
+ * hidden one in step with the control: each `<prop>change` is reported as input, focus leaving
+ * the control as a blur, and Felte's own writes (`reset()`, `setFields()`) reach the control. Returns `{ destroy }`.
+ *
+ *   <zb-stepper use:felteControl={createField('seats')}></zb-stepper>
+ */
+export function felteControl(node, created, { prop = 'value' } = {}) {
+  const field = created?.field ? created : null;
+  if (!field) throw new TypeError("zubra: felteControl() needs the result of Felte's createField(name)");
+  const action = field.field(node) ?? {};
+  // Felte puts its hidden input in place, after the control, on the next task. Start it at the
+  // control's value; keep a number a number (Felte reads `type="number"` inputs as numbers, and this
+  // one stays hidden); and pass Felte's own writes to it (`reset()`, `setFields()`) to the control.
+  let writing = false;
+  const start = setTimeout(() => {
+    const input = node.nextElementSibling;
+    if (input?.localName === 'input' && input.type === 'hidden') {
+      if (typeof node[prop] === 'number') {
+        input.type = 'number';
+        input.hidden = true;
+      }
+      const own = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value');
+      Object.defineProperty(input, 'value', {
+        configurable: true,
+        get: () => own.get.call(input),
+        set: (value) => {
+          own.set.call(input, value);
+          if (!writing) node[prop] = input.type === 'number' && value !== '' ? Number(value) : value;
+        },
+      });
+    }
+    report(node[prop]);
+  });
+  const report = (value) => {
+    writing = true;
+    try { field.onInput(value); } finally { writing = false; }
+  };
+  const change = (event) => report(event.detail);
+  const blur = () => field.onBlur();
+  node.addEventListener(prop.toLowerCase() + 'change', change);
+  node.addEventListener('focusout', blur);
+  return {
+    destroy() {
+      clearTimeout(start);
+      node.removeEventListener(prop.toLowerCase() + 'change', change);
+      node.removeEventListener('focusout', blur);
+      action.destroy?.();
+    },
+  };
+}

package/src/navigation.js

@@ -0,0 +1,52 @@
+// Links inside components, through the app's router: a plain `<a href>` in a Zubra component
+// navigates with the router the app already has (React Router, Next.js, Vue Router, SvelteKit,
+// Angular Router…) instead of reloading the page. Not a router: one listener that hands the
+// app's router the URL, and otherwise leaves the link alone.
+//
+//   routeLinks((to) => router.push(to))          // Vue Router; returns a function that stops it
+//   useRouteLinks(useNavigate())                  // React Router (`@zubra/runtime/react`)
+//   useRouteLinks(useRouter().push)               // Next.js
+//   routeLinks((to) => goto(to))                  // SvelteKit, in onMount
+//   routeLinks((to) => router.navigateByUrl(to))  // Angular
+//
+// Without JavaScript, or for a link it leaves alone, the link is a link. It leaves alone: a click
+// something already handled (`preventDefault()`), a modified or non-primary click (new tab,
+// window, download), a `target` other than `_self`, `download`, `rel="external"`, another
+// origin, and a link to a place on the current page (`#…`). Only links inside a Zubra component
+// are routed by default (the app's own links are its router's business); `within` changes that.
+//
+// If the app's router already intercepts the Navigation API's `navigate` event (Baseline since
+// January 2026), links in components already go through it, and none of this is needed.
+
+/** A Zubra component's host: its class carries the compiled `zubra` metadata. */
+export const isComponent = (node) => Boolean(node?.constructor?.zubra);
+
+/**
+ * Route clicks on links inside Zubra components through `navigate(to, { event, anchor, url })`,
+ * where `to` is the path, query and hash (`/seats?row=b#top`). Returns a function that stops it.
+ * `within(node)` decides which ancestors count (by default, a Zubra component's host); `root` is
+ * where to listen (by default, the document).
+ */
+export function routeLinks(navigate, { within = isComponent, root = globalThis.document } = {}) {
+  if (typeof navigate !== 'function') throw new TypeError('zubra: routeLinks() needs a function that navigates, such as (to) => router.push(to)');
+  if (!root) return () => {};
+  const click = (event) => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    const path = event.composedPath();
+    const at = path.findIndex((node) => node.localName === 'a' && node.hasAttribute?.('href'));
+    if (at < 0) return;
+    const anchor = path[at];
+    if (!path.slice(at + 1).some((node) => node.nodeType === 1 && within(node))) return;
+    const target = anchor.getAttribute('target');
+    if ((target && target !== '_self') || anchor.hasAttribute('download')) return;
+    if ((anchor.getAttribute('rel') ?? '').split(/\s+/).includes('external')) return;
+    const url = new URL(anchor.href, anchor.baseURI);
+    const here = new URL(globalThis.location.href);
+    if (url.origin !== here.origin) return;
+    if (url.hash && url.pathname === here.pathname && url.search === here.search) return;
+    event.preventDefault();
+    navigate(url.pathname + url.search + url.hash, { event, anchor, url });
+  };
+  root.addEventListener('click', click);
+  return () => root.removeEventListener('click', click);
+}

package/src/outlet.js

@@ -0,0 +1,79 @@
+// Outlets (experimental): a place in a Zubra component where the app's framework renders its
+// own components, with the app's context, state and events, through a portal.
+//
+//   <!-- row-list.zb -->
+//   <zb-each items={items} as="item" key={item.id}>
+//     <li><zb-outlet name="row" item={item}></zb-outlet></li>
+//   </zb-each>
+//
+//   // React
+//   <RowList items={rows} renderRow={(item) => <Row item={item} />} />
+//
+// Slots let the consumer put content *in* a component; an outlet lets the component ask the
+// consumer for content *per item*, which is what render props and scoped slots do inside one
+// framework. The component stays the owner of the structure (the list, its keys, its order);
+// the framework renders what goes in each outlet, as a portal, so React context, hooks and
+// event handlers work there as anywhere else in the app.
+//
+// Protocol: a connected `<zb-outlet>` fires a bubbling, composed `outletconnect` event. A
+// listener that serves outlets of that name calls `event.claim({ change, disconnect })` and
+// stops it: `change(outlet)` is called when the outlet's `item` changes, `disconnect(outlet)`
+// when it leaves the document. Outlets connected before anyone listened are found with
+// `outletsOf(host)`. A keyed move disconnects and reconnects the outlet node itself, so a
+// renderer that keys its portal by the node (as the React adapter does) keeps what's in it.
+const Base = globalThis.HTMLElement ?? class {};
+
+export class ZubraOutletElement extends Base {
+  #item = undefined;
+  /** Who renders into this outlet: `{ change, disconnect }`, or null. */
+  owner = null;
+
+  /** Which of the consumer's renderers fills it. */
+  get name() {
+    return this.getAttribute('name') ?? '';
+  }
+
+  /** The data the component gives the renderer for this outlet. */
+  get item() {
+    return this.#item;
+  }
+
+  set item(value) {
+    if (Object.is(value, this.#item)) return;
+    this.#item = value;
+    this.owner?.change(this);
+  }
+
+  connectedCallback() {
+    if (!this.style.display) this.style.display = 'contents';
+    if (this.owner) return;
+    const event = new Event('outletconnect', { bubbles: true, composed: true });
+    event.outlet = this;
+    event.claim = (owner) => {
+      this.owner = owner;
+      event.stopPropagation();
+    };
+    this.dispatchEvent(event);
+  }
+
+  disconnectedCallback() {
+    const owner = this.owner;
+    this.owner = null;
+    owner?.disconnect(this);
+  }
+}
+
+/** The unclaimed outlets inside `host` (its light DOM and its shadow root), in document order. */
+export function outletsOf(host) {
+  const found = [...host.querySelectorAll('zb-outlet')];
+  if (host.shadowRoot) found.push(...host.shadowRoot.querySelectorAll('zb-outlet'));
+  return found.filter((outlet) => !outlet.owner);
+}
+
+/** Define `<zb-outlet>` (once; a no-op without `customElements`). */
+export function defineOutletElement() {
+  const registry = globalThis.customElements;
+  if (registry && !registry.get('zb-outlet')) registry.define('zb-outlet', ZubraOutletElement);
+}
+
+defineOutletElement();

package/src/react.js

@@ -15,9 +15,29 @@
 //   works the same way.
 import * as React from 'react';
 import { serverContent } from './server.js';
+import { outletsOf } from './outlet.js';
+import { routeLinks } from './navigation.js';
+import './context.js';
+import { subscribe, read } from './bridge.js';
 
 const useIsomorphicLayoutEffect = typeof window === 'undefined' ? React.useEffect : React.useLayoutEffect;
 
+// `renderRow` serves `<zb-outlet name="row">`, `renderDetailPanel` serves `detail-panel`.
+const outletName = (key) => key.slice(6).replace(/[A-Z]/g, (letter, at) => (at ? '-' : '') + letter.toLowerCase());
+const isRenderer = (key, value) => key.length > 6 && key.startsWith('render') && /[A-Z]/.test(key[6]) && typeof value === 'function';
+// react-dom's createPortal, loaded when an element first has an outlet to fill: a page that
+// uses no outlets (or maps only `react` in an import map) never imports react-dom from here.
+let createPortal = null;
+const portals = () => (createPortal ? Promise.resolve() : import('react-dom').then((dom) => { createPortal = dom.createPortal; }));
+
+// A stable key per outlet, for its portal.
+const outletKeys = new WeakMap();
+let nextOutlet = 0;
+const outletKey = (outlet) => {
+  if (!outletKeys.has(outlet)) outletKeys.set(outlet, `zb-outlet-${++nextOutlet}`);
+  return outletKeys.get(outlet);
+};
+
 const clone = (value) => (value && typeof value === 'object' ? structuredClone(value) : value);
 
 /** `zb-star-rating` → `ZbStarRating`. */
@@ -55,14 +75,69 @@ export function wrap(Element) {
     const values = {};
     const listeners = {};
     const rest = {};
+    const renderers = {};
     for (const key of Object.keys(all)) {
       if (key === 'children') continue;
       const event = key.length > 2 && key.startsWith('on') ? key.slice(2).toLowerCase() : null;
       if (Object.hasOwn(props, key)) values[key] = all[key];
       else if (event && events.includes(event)) listeners[event] = all[key];
+      else if (isRenderer(key, all[key])) renderers[outletName(key)] = all[key];
       else rest[key] = all[key];
     }
 
+    // Outlets (experimental, outlet.js): `render<Name>` fills each `<zb-outlet name>` the element
+    // renders, through a portal, so what's rendered there is part of this React tree (context,
+    // state, events). `outlets` maps each claimed outlet to its current item.
+    const served = React.useRef(renderers);
+    served.current = renderers;
+    const [outlets, setOutlets] = React.useState(() => new Map());
+    useIsomorphicLayoutEffect(() => {
+      const node = element.current;
+      const claimed = new Set();
+      const owner = {
+        change: (outlet) => setOutlets((map) => new Map(map).set(outlet, outlet.item)),
+        disconnect: (outlet) => {
+          claimed.delete(outlet);
+          setOutlets((map) => {
+            const next = new Map(map);
+            next.delete(outlet);
+            return next;
+          });
+        },
+      };
+      const take = (outlets) => {
+        if (!outlets.length) return;
+        for (const outlet of outlets) {
+          outlet.owner = owner;
+          claimed.add(outlet);
+        }
+        const add = () => setOutlets((map) => {
+          const next = new Map(map);
+          for (const outlet of outlets) if (claimed.has(outlet)) next.set(outlet, outlet.item);
+          return next;
+        });
+        if (createPortal) add();
+        else portals().then(add);
+      };
+      const connected = (event) => {
+        if (!Object.hasOwn(served.current, event.outlet.name)) return;
+        event.claim(owner);
+        take([event.outlet]);
+      };
+      node.addEventListener('outletconnect', connected);
+      // Outlets the element rendered before this listener existed.
+      take(outletsOf(node).filter((outlet) => Object.hasOwn(served.current, outlet.name)));
+      return () => {
+        node.removeEventListener('outletconnect', connected);
+        for (const outlet of claimed) outlet.owner = null;
+      };
+    }, []);
+    const filled = [];
+    for (const [outlet, item] of outlets) {
+      const render = renderers[outlet.name];
+      if (render && createPortal) filled.push(createPortal(render(item), outlet, outletKey(outlet)));
+    }
+
     // Subscribe once per event; always call the latest handler.
     const handlers = React.useRef(listeners);
     handlers.current = listeners;
@@ -114,11 +189,70 @@ export function wrap(Element) {
     // @zubra/server's injectShadowRoots; this works without one.)
     if (React.Children.count(all.children) === 0) {
       const html = typeof window === 'undefined' ? serverContent(Element, { props: json ? JSON.parse(json) : {}, name: rest.name }) : '';
-      return React.createElement(tag, { ...host, dangerouslySetInnerHTML: { __html: html }, suppressHydrationWarning: true });
+      return React.createElement(React.Fragment, null,
+        React.createElement(tag, { ...host, dangerouslySetInnerHTML: { __html: html }, suppressHydrationWarning: true }), filled);
     }
-    return React.createElement(tag, host, all.children);
+    return React.createElement(React.Fragment, null, React.createElement(tag, host, all.children), filled);
   });
   Component.displayName = pascal(tag);
   Component.element = Element;
   return Component;
 }
+
+/**
+ * Route links inside Zubra components through the app's router while this component is mounted:
+ * `useRouteLinks(useNavigate())` (React Router), `useRouteLinks(useRouter().push)` (Next.js).
+ * The function can change between renders. Options as for `routeLinks` (`@zubra/runtime/navigation`).
+ */
+export function useRouteLinks(navigate, options) {
+  const latest = React.useRef(navigate);
+  latest.current = navigate;
+  React.useEffect(() => routeLinks((to, info) => latest.current(to, info), options), []);
+}
+
+/**
+ * Provide a Context Protocol value to every element inside: an app's theme, locale or current user,
+ * read by components with `inject(context)` (or Lit's `@consume`).
+ *
+ *   <ZubraContext context={theme} value={dark ? 'dark' : 'light'}>…</ZubraContext>
+ *
+ * `value` can also be a signal. It renders a `<zb-context>` element, which is `display: contents`.
+ */
+export function ZubraContext({ context, value, children }) {
+  const ref = React.useRef(null);
+  useIsomorphicLayoutEffect(() => {
+    ref.current.context = context;
+    ref.current.value = value;
+  });
+  // React 19 sets these as properties when it creates the element, before the children are in
+  // the document, so they're answered on their first request; React 18 sets them in the effect,
+  // and the element's announcement makes the children ask again.
+  const early = legacy || typeof window === 'undefined' ? {} : { context, value };
+  return React.createElement('zb-context', { ...early, ref, style: { display: 'contents' } }, children);
+}
+
+/**
+ * Read a Zubra signal (or a function of signals) in a React component, re-rendering when it
+ * changes: a store shared with elements, a `computed`, a `@zubra/sync` field.
+ *
+ *   const items = useSignal(cart, { deep: true })   // write with cart.set(...) or cart.get().push(...)
+ *
+ * Built on `useSyncExternalStore`, so it's safe under concurrent rendering and on the server
+ * (where it reads the value once). With `deep: true` a mutation inside an array or object
+ * re-renders too; the value is the same object, so memoize on the returned value with care.
+ * Pass a stable source (module-level, or from `useMemo`): a new function each render
+ * re-subscribes each render.
+ */
+export function useSignal(source, { deep = false } = {}) {
+  const store = React.useMemo(() => {
+    let version = 0;
+    return {
+      subscribe: (notify) => subscribe(source, () => { version++; notify(); }, { deep }),
+      // Without `deep`, the value itself is the snapshot (React compares it with Object.is);
+      // with it, a counter that each notification moves, so a mutation counts as a change.
+      snapshot: deep ? () => version : () => read(source),
+    };
+  }, [source, deep]);
+  React.useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot);
+  return read(source);
+}