@zubra/runtime 5.7.0 → 5.8.0

package/README.md

@@ -13,9 +13,14 @@ ships one, this package deletes code instead of components being rewritten.
 | `src/element.js` hooks | Plain functions (see the project's hooks decision) | `state`, `from`, `computed`, `watch`, `onMount`, `onUnmount`, `id`, `props`, `host`, `emit`, `hydrated` |
 | `src/element.js` slots | Light-DOM slotting with the host's child methods routed to the slots, so frameworks can keep managing the children; native `<slot>` in shadow DOM | Done |
 | `src/react.js`, `src/vue.js` | Adapters: an element as a React (18, 19) or Vue 3 component | Done |
+| `src/testing.js` | `mount(Element, { framework })`: a component through plain HTML, the React adapter or the Vue adapter, for one test per framework in any browser test runner | Done |
+| `src/navigation.js` | Links inside components through the app's router: `routeLinks(navigate)`; `useRouteLinks` in the React and Vue adapters. Not a router | Done |
+| `src/forms.js` | A control as a form library's field: React Hook Form (`registerProps`, `fieldProps`), TanStack Form (`fieldProps`), VeeValidate (`vueFieldProps`), Felte (`felteControl`) | Done |
+| `src/bridge.js` | Signals read from framework code: `subscribe`, and `toStore` (the Svelte store contract and an RxJS-style Subscribable); React and Vue `useSignal` | Done |
 | `types/` | TypeScript declarations for every entry point | Done |
 | `src/element.js` forms | Form-associated custom elements (`ElementInternals`) | `formValue`, `validity`, `onFormReset`, `onFormRestore`, `onFormDisabled`; native control API on the element |
 | `src/element.js` context | [Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md) (`context-request` / `context-provider` events) | `createContext`, `provide`, `inject`; interoperates with any protocol implementation |
+| `src/context.js` | The same protocol, provided from the app: `<zb-context>` with `context` and `value` properties; `ZubraContext` in the React and Vue adapters | Done |
 
 ## The production build
 
@@ -82,6 +87,25 @@ await tick();
 A write to a signal an effect has already read in the same run does not re-run it (same as a
 computed in the reference). Derive the value instead of writing it back.
 
+## Signals in framework code
+
+A signal elements read can be read by the app too, so state is shared rather than copied in by
+props and back out by events (`@zubra/runtime/bridge`):
+
+```js
+import { state } from '@zubra/runtime';
+export const cart = state([]);                       // cart-state.js, imported by elements too
+
+// React                                             // Vue
+const items = useSignal(cart, { deep: true });       const items = useSignal(cart, { deep: true }); // a ref
+// Svelte: const items = toStore(cart, { deep: true }), then {$items.length}
+// Solid: from(toStore(cart))     Angular: toSignal(toStore(cart), { requireSync: true })
+```
+
+`subscribe` and the stores are effects owned by nothing: they last until unsubscribed (Vue's ref
+stops with the scope it was made in; React's hook with the component). `deep: true` reads through
+an array or plain object, so a mutation inside it notifies.
+
 ## Tests
 
 ```sh

package/dist/production/bridge.js

@@ -0,0 +1,97 @@
+// Generated by scripts/build-production.js from src/bridge.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// Signal bridges: read (and write) a Zubra signal from a framework's own code.
+//
+//   import { shared } from './cart-state.js'               // export const shared = state([])
+//   import { toStore } from '@zubra/runtime/bridge'
+//   const cart = toStore(shared, { deep: true })
+//
+//   Svelte:   {$cart.length}                               (the store contract)
+//   Solid:    const items = from(cart)                     (solid-js `from`)
+//   Angular:  items = toSignal(cart, { requireSync: true })  (a Subscribable)
+//   RxJS:     from(cart)                                   (Symbol.observable)
+//   React:    useSignal(shared) from '@zubra/runtime/react'
+//   Vue:      useSignal(shared) from '@zubra/runtime/vue'
+//
+// The adapters carry props, events and two-way bindings across the element boundary; this
+// carries state: a signal that elements and the app's code both read, without copying it into
+// the framework's state and back. Any `Signal.State` or `Signal.Computed` works (`state()`,
+// `computed()`, `from()`, a `@zubra/sync` field, a native `Signal` once browsers ship one), as
+// does a function that reads signals (it's tracked like a computed).
+//
+// `deep: true` also tracks what's inside an array or plain object, so `items.push(x)` notifies
+// as `items = [...items, x]` does. Without it a mutation inside the value isn't a change.
+import { Signal } from './signal.js';
+import { effect, root } from './effect.js';
+
+const isSignal = (value) => value instanceof Signal.State || value instanceof Signal.Computed;
+
+function check(source, name) {
+  if (typeof source !== 'function' && !isSignal(source)) {
+    throw new TypeError(`zubra: ${name}() needs a signal (state(), computed(), a Signal.State or Signal.Computed) or a function that reads signals`);
+  }
+}
+
+/** The source's current value: a signal's `get()`, or the function's result. */
+export const read = (source) => (typeof source === 'function' ? source() : source.get());
+
+/** Whether the source can be written: a `Signal.State`, or a signal with its own `set` (`from()`). */
+export const writable = (source) => typeof source?.set === 'function';
+
+// Read every property of an array or plain object (through state's proxy, each read is tracked),
+// so a change anywhere inside notifies.
+function touch(value, seen = new Set()) {
+  if (value === null || typeof value !== 'object' || seen.has(value)) return;
+  if (!Array.isArray(value)) {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) return;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) for (let index = 0; index < value.length; index++) touch(value[index], seen);
+  else for (const key of Object.keys(value)) touch(value[key], seen);
+}
+
+/**
+ * Call `callback(value)` now and whenever `source` changes, until the returned function is
+ * called. Changes are batched like the runtime's own effects: one call per microtask, with the
+ * latest value. Not owned by any component, so it lives until it's unsubscribed.
+ */
+export function subscribe(source, callback, { deep = false } = {}) {
+  check(source, 'subscribe');
+  const owner = root(() => {
+    effect(() => {
+      const value = read(source);
+      if (deep) touch(value);
+      Signal.subtle.untrack(() => callback(value));
+    });
+  });
+  return () => owner.dispose();
+}
+
+/**
+ * The source as a store: the Svelte store contract (`subscribe(run)` calls `run` now and on each
+ * change, returning the unsubscribe function), which is also an RxJS-style Subscribable
+ * (`subscribe({ next })` returns something with `unsubscribe()`), so Angular's `toSignal`, Solid's
+ * `from` and RxJS's `from` take it as it is. `set` and `update` are there when the source is
+ * writable (a Svelte writable store, so `bind:value={$store}` works).
+ */
+export function toStore(source, options = {}) {
+  check(source, 'toStore');
+  const store = {
+    get: () => read(source),
+    subscribe(run) {
+      const next = typeof run === 'function' ? run : (value) => run?.next?.(value);
+      const stop = subscribe(source, next, options);
+      const unsubscribe = () => stop();
+      unsubscribe.unsubscribe = unsubscribe;
+      return unsubscribe;
+    },
+    [Symbol.observable ?? '@@observable']() {
+      return this;
+    },
+  };
+  if (writable(source)) {
+    store.set = (value) => source.set(value);
+    store.update = (fn) => source.set(fn(Signal.subtle.untrack(() => read(source))));
+  }
+  return store;
+}

package/dist/production/context.js

@@ -0,0 +1,101 @@
+// Generated by scripts/build-production.js from src/context.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// 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/dist/production/element.js

@@ -60,6 +60,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);
@@ -1523,6 +1532,18 @@ function defineElement(tag, definition) {
   let templateSignature = signature(childRange(componentTemplate.content));
   let instances = 0;
   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 {
@@ -1597,7 +1618,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/dist/production/forms.js

@@ -0,0 +1,126 @@
+// Generated by scripts/build-production.js from src/forms.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// 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/dist/production/navigation.js

@@ -0,0 +1,53 @@
+// Generated by scripts/build-production.js from src/navigation.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// 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/dist/production/outlet.js

@@ -0,0 +1,80 @@
+// Generated by scripts/build-production.js from src/outlet.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// 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();