@zubra/runtime 5.7.0 → 5.9.0

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);
+}

package/src/resource.js

@@ -8,8 +8,10 @@
 // `AbortSignal` it was given, and so does the element's removal; a result that arrives after a
 // newer run started is dropped, so the value is always the latest request's. While a new run is
 // pending the previous value stays (`loading` is true), so the UI doesn't flash empty.
+// `dispose()` (or `using`, through `Symbol.dispose`) stops it early: the run in flight is
+// aborted and nothing re-runs it. Otherwise it lives as long as the scope that created it.
 import { Signal } from './signal.js';
-import { effect } from './effect.js';
+import { DISPOSE, effect } from './effect.js';
 
 const { untrack } = Signal.subtle;
 
@@ -29,7 +31,7 @@ export function resource(fetcher, { initial } = {}) {
   const version = new Signal.State(0);
   let current = null; // the latest run's promise
 
-  effect(() => {
+  const stop = effect(() => {
     version.get();
     const controller = new AbortController();
     let result;
@@ -71,5 +73,7 @@ export function resource(fetcher, { initial } = {}) {
     get loading() { return status.get() === 'pending'; },
     refresh() { version.set(untrack(() => version.get()) + 1); },
     then(resolve, reject) { return current.then(resolve, reject); },
+    dispose: stop,
+    [DISPOSE]: stop,
   };
 }

package/src/testing.js

@@ -0,0 +1,153 @@
+// Testing helpers: mount a Zubra component the way each framework's consumers do, so a library
+// author can run one test through plain HTML, React and Vue, in any browser test runner (Vitest
+// browser mode, Web Test Runner, Playwright's own).
+//
+//   import { frameworks, mount } from '@zubra/runtime/testing';
+//   import StarRating from './star-rating.zb';
+//
+//   for (const framework of await frameworks()) {
+//     test(`${framework}: a click sets the value and fires valuechange`, async () => {
+//       const view = await mount(StarRating, { framework, props: { value: 2 } });
+//       view.element.querySelector('button:nth-of-type(4)').click();
+//       expect(view.events('valuechange')).toEqual([4]);
+//       await view.set({ value: 1 });                 // through the framework, as an app would
+//       expect(view.element.value).toBe(1);
+//       view.unmount();
+//     });
+//   }
+//
+// A `<prop>change` event updates the prop the framework passes, as an app binding it two-way
+// would (`v-model`, React's controlled pattern). React and Vue are imported only when asked for, through the same adapters apps use
+// (`@zubra/runtime/react`, `@zubra/runtime/vue`), so events reach the framework's own handlers,
+// props are set the framework's way, and slots are the framework's children.
+
+const ALL = ['html', 'react', 'vue'];
+
+/** The frameworks that can be mounted here: plain HTML always, React and Vue when installed. */
+export async function frameworks() {
+  const found = ['html'];
+  for (const name of ['react', 'vue']) {
+    try {
+      await load(name);
+      found.push(name);
+    } catch {
+      // not installed: skipped
+    }
+  }
+  return found;
+}
+
+const loaded = {};
+function load(framework) {
+  if (framework === 'react') {
+    loaded.react ??= Promise.all([import('react'), import('react-dom'), import('react-dom/client'), import('./react.js')])
+      .then(([React, ReactDOM, client, adapter]) => ({ React, flushSync: ReactDOM.flushSync, createRoot: client.createRoot, wrap: adapter.wrap }));
+    return loaded.react;
+  }
+  if (framework === 'vue') {
+    loaded.vue ??= Promise.all([import('vue'), import('./vue.js')]).then(([Vue, adapter]) => ({ Vue, wrap: adapter.wrap }));
+    return loaded.vue;
+  }
+  return Promise.resolve(null);
+}
+
+// What the element is doing once a change has landed: its own render, and the framework's.
+const settle = async (element) => {
+  await new Promise((resolve) => setTimeout(resolve));
+  await element?.updateComplete;
+};
+
+/**
+ * Mount `Element` (a compiled component's default export) through `framework` (`html`, `react` or
+ * `vue`), with `props` and `slots` (`{ default: 'text', title: 'Heading' }`: text for each slot).
+ * Resolves once it has rendered, to:
+ * - `element`: the component's host element;
+ * - `events(name)`: the `detail` of each `name` event so far, as the framework's handler got it
+ *   (`events()`: every event as `[name, detail]`);
+ * - `set(props)`: change props through the framework (merged with the current ones), and settle;
+ * - `unmount()`: remove it the framework's way.
+ */
+export async function mount(Element, { framework = 'html', props = {}, slots = {}, container } = {}) {
+  const meta = Element?.zubra;
+  if (!meta) throw new TypeError('zubra: mount() needs a compiled zubra element (the default export of a .zb module)');
+  if (!ALL.includes(framework)) throw new TypeError(`zubra: mount() knows ${ALL.join(', ')}, not "${framework}"`);
+  if (!customElements.get(meta.tag)) customElements.define(meta.tag, Element);
+  const host = container ?? document.body.appendChild(document.createElement('div'));
+  const log = [];
+  // Like an app that binds the component two-way (`v-model`, React's controlled pattern): a
+  // `<prop>change` event updates the prop the framework passes back, so its next render doesn't
+  // put the old value back.
+  const models = Object.fromEntries(Object.keys(meta.props).filter((name) => meta.events.includes(`${name.toLowerCase()}change`)).map((name) => [`${name.toLowerCase()}change`, name]));
+  let model = () => {};
+  const record = (name) => (event) => {
+    log.push([name, event.detail]);
+    if (models[name]) model(models[name], event.detail);
+  };
+  let current = { ...props };
+  let view;
+
+  if (framework === 'html') {
+    const element = document.createElement(meta.tag);
+    for (const [name, value] of Object.entries(current)) element[name] = value;
+    for (const name of meta.events) element.addEventListener(name, record(name));
+    for (const [name, text] of Object.entries(slots)) {
+      if (name === 'default') element.append(text);
+      else element.append(Object.assign(document.createElement('span'), { slot: name, textContent: text }));
+    }
+    host.append(element);
+    view = {
+      element,
+      set: async (next) => { Object.assign(current, next); for (const [name, value] of Object.entries(next)) element[name] = value; },
+      unmount: () => element.remove(),
+    };
+  } else if (framework === 'react') {
+    const { React, flushSync, createRoot, wrap } = await load('react');
+    const Component = wrap(Element);
+    const handlers = Object.fromEntries(meta.events.map((name) => [`on${name}`, record(name)]));
+    const children = Object.entries(slots).map(([name, text]) =>
+      name === 'default' ? text : React.createElement('span', { key: name, slot: name }, text));
+    let element = null;
+    const ref = (node) => { if (node) element = node; };
+    const root = createRoot(host);
+    const render = () => flushSync(() => root.render(React.createElement(Component, { ...current, ...handlers, ref }, ...children)));
+    model = (name, value) => { current[name] = value; queueMicrotask(render); };
+    render();
+    view = {
+      get element() { return element; },
+      set: async (next) => { Object.assign(current, next); render(); },
+      unmount: () => root.unmount(),
+    };
+  } else {
+    const { Vue, wrap } = await load('vue');
+    const Component = wrap(Element);
+    const state = Vue.reactive({ ...current });
+    model = (name, value) => { current[name] = value; state[name] = value; };
+    const handlers = Object.fromEntries(meta.events.map((name) => [`on${name[0].toUpperCase()}${name.slice(1)}`, record(name)]));
+    const slotFunctions = Object.fromEntries(Object.entries(slots).map(([name, text]) => [name, () => (name === 'default' ? text : Vue.h('span', text))]));
+    const component = Vue.ref(null);
+    const app = Vue.createApp({ render: () => Vue.h(Component, { ...state, ...handlers, ref: component }, slotFunctions) });
+    app.mount(host);
+    view = {
+      get element() { return component.value?.element ?? null; },
+      set: async (next) => { Object.assign(current, next); Object.assign(state, next); await Vue.nextTick(); },
+      unmount: () => app.unmount(),
+    };
+  }
+
+  await settle(view.element);
+  const element = () => view.element;
+  return {
+    framework,
+    host,
+    get element() { return element(); },
+    events: (name) => (name === undefined ? log.slice() : log.filter(([event]) => event === name).map(([, detail]) => detail)),
+    async set(next) {
+      await view.set(next);
+      await settle(element());
+    },
+    unmount() {
+      view.unmount();
+      if (!container) host.remove();
+    },
+  };
+}

package/src/track.js

@@ -0,0 +1,77 @@
+// Reads after an `await` in a resource's fetcher: `resource(tracked(fetcher))`.
+//
+//   const list = resource(tracked(async ({ signal, track }) => {
+//     const token = await auth(signal)
+//     return load(token, track(() => page.get()), signal)
+//   }))
+//
+// The Signals API tracks a read only while a Computed is running. A resource's fetcher runs
+// inside its effect until its first `await`; the code after that runs later, outside it, so its
+// reads are not followed. `tracked()` gives each run `track(read)`: it reads, and when what
+// `read` returns changes, the resource runs the fetcher again, as for a read before the
+// `await`. The compiler writes `tracked()` and the `track()` calls for an async fetcher in a
+// `.zb` script, so this module is loaded only by components that have one.
+//
+// A run that was replaced or has settled, or a resource that was disposed, still reads through
+// `track()`, but no longer subscribes. The reads are watched by an effect owned where `tracked()` was called (a
+// component's setup), so a detached element holds none of them and catches up when it returns.
+import { Signal } from './signal.js';
+import { effect } from './effect.js';
+
+const { untrack, currentComputed } = Signal.subtle;
+const THREW = Symbol('threw');
+
+function readOnce(computed) {
+  try { return computed.get(); } catch { return THREW; }
+}
+
+/** Wraps a resource's fetcher so it is also given `track(read)`, for reads after an `await`. */
+export function tracked(fetcher) {
+  if (typeof fetcher !== 'function') throw new TypeError('zubra: tracked() takes a function');
+  // Read by each run before it can wait, so the resource's effect runs again when it changes.
+  const again = new Signal.State(0);
+  // The run whose later reads are watched: set when it makes one, and when it settles.
+  const tail = new Signal.State(null);
+  let latest = null;
+
+  // When a read changes, run again. A new read is appended (and seen) without re-running.
+  const stop = effect(() => {
+    const watched = tail.get();
+    if (!watched) return;
+    let changed = false;
+    for (const read of watched.run.reads) {
+      if (!Object.is(readOnce(read.computed), read.seen)) changed = true; // read each, to keep watching it
+    }
+    if (changed && watched.run === latest) untrack(() => again.set(again.get() + 1));
+  });
+
+  return (context) => {
+    again.get();
+    const { signal } = context;
+    const run = { reads: [] };
+    latest = run;
+    // The resource aborts a run when the next one starts, or when it is disposed: then no run
+    // follows, and nothing is watched any more.
+    signal?.addEventListener('abort', () => queueMicrotask(() => { if (latest === run) stop(); }), { once: true });
+    const track = (read) => {
+      if (typeof read !== 'function') throw new TypeError('zubra: track() takes a function that reads signals');
+      // Before the first `await` the resource's effect is running, and tracks the read itself.
+      if (currentComputed()) return read();
+      // A replaced or finished run (a timer the fetcher left), or a disposed resource: its value
+      // can't depend on the read any more, so read without subscribing.
+      if (run !== latest || run.done || signal?.aborted) return untrack(read);
+      const computed = new Signal.Computed(read);
+      run.reads.push({ computed, seen: readOnce(computed) });
+      tail.set({ run });
+      return computed.get(); // rethrows what `read` threw
+    };
+    const settled = () => {
+      run.done = true;
+      // The newest run has finished: stop watching an older run's later reads.
+      if (run === latest && untrack(() => tail.get())?.run !== run) tail.set(run.reads.length ? { run } : null);
+    };
+    const result = fetcher({ ...context, track });
+    Promise.resolve(result).then(settled, settled);
+    return result;
+  };
+}

package/src/vue.js

@@ -12,8 +12,11 @@
 //   `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 { defineComponent, h, withDirectives, Text, Comment, Fragment, customRef, getCurrentScope, onScopeDispose } from 'vue';
 import { serverContent } from './server.js';
+import { routeLinks } from './navigation.js';
+import './context.js';
+import { subscribe, read, writable } from './bridge.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('');
@@ -123,3 +126,66 @@ export function wrap(Element) {
     },
   });
 }
+
+/**
+ * Route links inside Zubra components through Vue Router (or any `push`) until the current effect
+ * scope ends: `useRouteLinks((to) => router.push(to))` in a component's `setup`. Returns the
+ * function that stops it.
+ */
+export function useRouteLinks(navigate, options) {
+  const stop = routeLinks(navigate, options);
+  if (getCurrentScope()) onScopeDispose(stop);
+  return stop;
+}
+
+/**
+ * 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 const ZubraContext = defineComponent({
+  name: 'ZubraContext',
+  props: { context: { default: undefined }, value: { default: undefined } },
+  setup(given, { slots }) {
+    // Set as DOM properties when the element is created, before its children are inserted.
+    return () => h('zb-context', { '.context': given.context, '.value': given.value, style: 'display: contents' }, slots.default?.());
+  },
+});
+
+/**
+ * A Zubra signal (or a function of signals) as a Vue ref: reading `.value` tracks it in
+ * templates, computeds and watchers, and assigning `.value` writes the signal when it's writable
+ * (a `Signal.State`, `state()`, `from()`), so `v-model="cart"` works on one.
+ *
+ *   const items = useSignal(cart, { deep: true })
+ *
+ * The subscription ends with the effect scope it was created in (the component's `setup`); outside
+ * one, call `stop()` on the ref when done. With `deep: true` a mutation inside an array or object
+ * triggers too.
+ */
+export function useSignal(source, { deep = false } = {}) {
+  let stop = () => {};
+  const ref = customRef((track, trigger) => {
+    let first = true;
+    stop = subscribe(source, () => {
+      if (first) first = false;
+      else trigger();
+    }, { deep });
+    return {
+      get() {
+        track();
+        return read(source);
+      },
+      set(value) {
+        if (!writable(source)) throw new TypeError('zubra: useSignal(): this signal is read-only (a computed); write the state it reads');
+        source.set(value);
+      },
+    };
+  });
+  Object.defineProperty(ref, 'stop', { value: () => stop() });
+  if (getCurrentScope()) onScopeDispose(() => stop());
+  return ref;
+}