@zubra/runtime 5.7.0 → 5.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zubra/runtime",
-  "version": "5.7.0",
+  "version": "5.9.0",
   "description": "Browser runtime for Zubra compiled components, built on the TC39 Signals API",
   "license": "ISC",
   "repository": {
@@ -30,6 +30,11 @@
       "production": "./dist/production/spread.js",
       "default": "./src/spread.js"
     },
+    "./track": {
+      "types": "./types/track.d.ts",
+      "production": "./dist/production/track.js",
+      "default": "./src/track.js"
+    },
     "./zag": {
       "types": "./types/zag.d.ts",
       "production": "./dist/production/zag.js",
@@ -45,6 +50,36 @@
       "production": "./dist/production/motion.js",
       "default": "./src/motion.js"
     },
+    "./bridge": {
+      "types": "./types/bridge.d.ts",
+      "production": "./dist/production/bridge.js",
+      "default": "./src/bridge.js"
+    },
+    "./context": {
+      "types": "./types/context.d.ts",
+      "production": "./dist/production/context.js",
+      "default": "./src/context.js"
+    },
+    "./forms": {
+      "types": "./types/forms.d.ts",
+      "production": "./dist/production/forms.js",
+      "default": "./src/forms.js"
+    },
+    "./navigation": {
+      "types": "./types/navigation.d.ts",
+      "production": "./dist/production/navigation.js",
+      "default": "./src/navigation.js"
+    },
+    "./outlet": {
+      "types": "./types/outlet.d.ts",
+      "production": "./dist/production/outlet.js",
+      "default": "./src/outlet.js"
+    },
+    "./testing": {
+      "types": "./types/testing.d.ts",
+      "production": "./dist/production/testing.js",
+      "default": "./src/testing.js"
+    },
     "./react": {
       "types": "./types/react.d.ts",
       "production": "./dist/production/react.js",
@@ -79,7 +114,8 @@
     "@angular/forms": ">=16",
     "@zag-js/vanilla": ">=1.47",
     "react": ">=18",
-    "vue": "^3.3"
+    "vue": "^3.3",
+    "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
     "@angular/core": {
@@ -96,6 +132,9 @@
     },
     "vue": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -106,6 +145,8 @@
     "@angular/forms": "22.2.5",
     "@angular/platform-browser": "22.2.5",
     "@babel/core": "8.1.0",
+    "@felte/vanilla": "0.3.14",
+    "@tanstack/react-form": "1.33.5",
     "@types/react": "19.3.0",
     "@zag-js/combobox": "1.47.0",
     "@zag-js/vanilla": "1.47.0",
@@ -116,13 +157,17 @@
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "react-dom18": "npm:react-dom@18.3.1",
+    "react-hook-form": "7.92.0",
+    "react-router": "8.5.1",
     "react18": "npm:react@18.3.1",
     "rxjs": "7.8.2",
     "signal-polyfill": "0.2.2",
     "typescript": "^7.0.2",
+    "vee-validate": "4.15.1",
     "vscode-html-languageservice": "5.6.2",
     "vscode-languageserver-textdocument": "1.0.16",
-    "vue": "3.5.45"
+    "vue": "3.5.45",
+    "vue-router": "5.5.0"
   },
   "files": [
     "src",

package/src/bridge.js

@@ -0,0 +1,96 @@
+// 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/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/effect.js

@@ -8,6 +8,11 @@
 //   scope(fn)         an ownership root: effects created inside belong to it
 //   flush() / tick()  apply pending re-runs now / await them
 //
+// Disposal: effect()'s dispose function and every scope are also disposables
+// (`[Symbol.dispose]`), so `using` and `DisposableStack` can own them where the browser has
+// Explicit Resource Management. Nothing here depends on it. Pausing is not disposal: a paused
+// scope resumes; only dispose() (or Symbol.dispose) ends one.
+//
 // Ownership: an effect created while another effect (or a scope) is running belongs to it. When
 // the owner re-runs or is disposed, everything it owns is disposed first, so nothing outlives
 // the code that created it.
@@ -28,6 +33,12 @@ let scheduled = null;      // promise for the pending microtask flush
 let flushing = false;
 const effectOf = new WeakMap();
 
+/**
+ * `Symbol.dispose`, or, where the engine doesn't have it yet, the symbol TypeScript's downlevel
+ * `using` and the polyfills look up (`Symbol.for('Symbol.dispose')`).
+ */
+export const DISPOSE = Symbol.dispose ?? Symbol.for('Symbol.dispose');
+
 // @dev
 /**
  * For the DevTools hook (devtools.js), in development only: `label` is what the effect being
@@ -100,6 +111,10 @@ class Owner {
     this.parent?.children.delete(this);
   }
 
+  [DISPOSE]() {
+    this.dispose();
+  }
+
   pause() {
     if (this.paused || this.disposed) return;
     this.paused = true;
@@ -193,7 +208,9 @@ class Scope extends Owner {
 export function effect(fn) {
   const e = new Effect(fn, owner);
   e.run(); // if this throws, the effect stays registered and re-runs when its dependencies change
-  return () => e.dispose();
+  const dispose = () => e.dispose();
+  dispose[DISPOSE] = dispose;
+  return dispose;
 }
 
 /**

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);
@@ -206,12 +215,13 @@ export function emit(name) {
 
 /**
  * An id unique to this element and call, for `id`/`for`/`aria-*` attributes. Stable for the
- * element's life; based on the host's own `id` when it has one, so it can be made to match
- * server-rendered markup.
+ * element's life. Based on the host's own `id` when it has one, else on the base the server
+ * rendered it with (`data-zb-id`), so the ids in server-rendered markup stay as they are.
  */
 export function id() {
   const component = hooks('id');
-  const base = component.host.id || `${component.host.localName}-${component.instance}`;
+  const host = component.host;
+  const base = host.id || host.getAttribute('data-zb-id') || `${host.localName}-${component.instance}`;
   return `${base}-${++component.ids}`;
 }
 
@@ -345,7 +355,18 @@ export function provide(context, value) {
  * key as `context`.
  */
 export function inject(context, fallback = context?.defaultValue) {
-  const host = hooks('inject').host;
+  const component = hooks('inject');
+  const host = component.host;
+  // The value the server rendered with (`data-zb-inject`, by call number) is where it starts,
+  // so hydrating doesn't show the default until the provider answers.
+  const number = (component.injects = (component.injects ?? 0) + 1);
+  const rendered = host.getAttribute('data-zb-inject');
+  if (rendered) {
+    try {
+      const values = JSON.parse(rendered);
+      if (Object.hasOwn(values, number)) fallback = values[number];
+    } catch { /* not ours: keep the default */ }
+  }
   const value = new Signal.State(fallback);
   let unsubscribe = null;
   let answered = false;
@@ -556,8 +577,27 @@ function departBetween(open, close, motion) {
 }
 
 /** Remove everything between `open` and `close` in one operation. */
+const nativeTextContent = typeof Node !== 'undefined' ? Object.getOwnPropertyDescriptor(Node.prototype, 'textContent').set : undefined;
 function deleteBetween(open, close) {
   if (open.nextSibling === close) return;
+  // The region is everything its parent holds but blank text (a list's own <tbody> or <ul>):
+  // emptying the parent and putting the markers and that text back is several times cheaper than
+  // deleting a range's contents.
+  const parent = open.parentNode;
+  const before = [];
+  const after = [];
+  const blank = (node) => node.nodeType === TEXT && node.data.trim() === '';
+  let edge = open.previousSibling;
+  while (edge && blank(edge) && before.length < 4) { before.unshift(edge); edge = edge.previousSibling; }
+  if (parent && !edge) {
+    edge = close.nextSibling;
+    while (edge && blank(edge) && after.length < 4) { after.push(edge); edge = edge.nextSibling; }
+    if (!edge) {
+      nativeTextContent.call(parent, '');
+      for (const node of [...before, open, close, ...after]) Node.prototype.insertBefore.call(parent, node, null);
+      return;
+    }
+  }
   const range = document.createRange();
   range.setStartAfter(open);
   range.setEndBefore(close);
@@ -1393,6 +1433,7 @@ function bindEach(part, open, hydrating, context) {
       }
       // `animate`: the rows that stay glide from where they were (@zubra/runtime/motion).
       const reorder = () => {
+        const was = new Map(rows.map((row, index) => [row, index]));
         const next = list.map((value, index) => {
           const row = byKey.get(keys[index]);
           if (!row) return createRow(value, index, keys[index]);
@@ -1402,17 +1443,14 @@ function bindEach(part, open, hydrating, context) {
           return row;
         });
         batch(() => { for (const row of byKey.values()) removeRow(row); });
-        // Text between rows, and rows on their way out, aren't rows to place against.
-        const skip = (node) => node && (node.nodeType === TEXT || part.animate?.isLeaving(node));
-        let at = open.nextSibling;
-        while (skip(at)) at = at.nextSibling;
-        for (const row of next) {
-          if (row.open === at) {
-            at = row.close.nextSibling;
-            while (skip(at)) at = at.nextSibling;
-            continue;
-          }
-          placeRow(row, at ?? close);
+        // The longest run of rows still in their old order stays put; every other row (and every
+        // new one) goes before the row after it, from the end. A swap moves two rows, not the
+        // rows between them.
+        const stay = inOrder(next.map((row) => was.get(row) ?? -1));
+        let before = close;
+        for (let index = next.length - 1; index >= 0; index--) {
+          if (!stay.has(index)) placeRow(next[index], before);
+          before = next[index].open;
         }
         rows = next;
       };
@@ -1422,6 +1460,31 @@ function bindEach(part, open, hydrating, context) {
   });
 }
 
+/**
+ * The indexes of a longest strictly increasing run in `sequence` (negative entries never count):
+ * for a keyed list, which rows are already in order and needn't move. O(n log n).
+ */
+function inOrder(sequence) {
+  const tails = []; // tails[length - 1]: the index ending the best run of that length so far
+  const previous = new Array(sequence.length);
+  for (let index = 0; index < sequence.length; index++) {
+    const value = sequence[index];
+    if (value < 0) continue;
+    let low = 0;
+    let high = tails.length;
+    while (low < high) {
+      const middle = (low + high) >> 1;
+      if (sequence[tails[middle]] < value) low = middle + 1;
+      else high = middle;
+    }
+    previous[index] = low > 0 ? tails[low - 1] : -1;
+    tails[low] = index;
+  }
+  const kept = new Set();
+  for (let index = tails.length ? tails[tails.length - 1] : -1; index >= 0; index = previous[index]) kept.add(index);
+  return kept;
+}
+
 const hasContent = (root) =>
   [...root.childNodes].some((node) => node.nodeType !== TEXT || node.data.trim() !== '');
 
@@ -1564,6 +1627,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 +1733,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?.();
+    },
+  };
+}