@zubra/runtime 5.8.0 → 5.9.0

package/dist/production/effect.js

@@ -9,6 +9,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.
@@ -29,6 +34,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');
+
 
 const watcher = new Signal.subtle.Watcher(() => {
   scheduled ??= new Promise((resolve) => queueMicrotask(() => {
@@ -93,6 +104,10 @@ class Owner {
     this.parent?.children.delete(this);
   }
 
+  [DISPOSE]() {
+    this.dispose();
+  }
+
   pause() {
     if (this.paused || this.disposed) return;
     this.paused = true;
@@ -183,7 +198,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/dist/production/element.js

@@ -196,12 +196,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}`;
 }
 
@@ -335,7 +336,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;
@@ -546,8 +558,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);
@@ -1374,6 +1405,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]);
@@ -1383,17 +1415,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;
       };
@@ -1403,6 +1432,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() !== '');
 

package/dist/production/resource.js

@@ -9,8 +9,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;
 
@@ -30,7 +32,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;
@@ -72,5 +74,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/dist/production/track.js

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

@@ -1,6 +1,6 @@
 {
   "name": "@zubra/runtime",
-  "version": "5.8.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",

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

@@ -215,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}`;
 }
 
@@ -354,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;
@@ -565,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);
@@ -1402,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]);
@@ -1411,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;
       };
@@ -1431,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() !== '');
 

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/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/types/effect.d.ts

@@ -1,15 +1,28 @@
+/**
+ * `[Symbol.dispose]()`, so `using` and `DisposableStack` accept it, when the project's `lib`
+ * has Explicit Resource Management (`esnext.disposable`, or `esnext`); nothing otherwise, so
+ * older `lib` settings still type-check.
+ */
+export type Disposal = SymbolConstructor extends { readonly dispose: infer K extends symbol }
+  ? { [P in K]: () => void }
+  : {};
+
 /** Something to run when an effect re-runs or is disposed. */
 export type Cleanup = () => void;
 
 /**
  * Run `fn` now and again whenever a signal it read changes (batched: several writes in one task
  * cause one re-run, in a microtask). `fn` may return a cleanup. Returns a function that disposes
- * the effect. Effects created inside another effect or scope belong to it.
+ * the effect, and is also disposable (`using stop = effect(…)`). Effects created inside another
+ * effect or scope belong to it.
  */
-export declare function effect(fn: () => void | Cleanup): () => void;
+export declare function effect(fn: () => void | Cleanup): (() => void) & Disposal;
 
-/** An ownership root: disposing, pausing or resuming it applies to every effect inside. */
-export interface Scope {
+/**
+ * An ownership root: disposing, pausing or resuming it applies to every effect inside. It's
+ * disposable too (`using s = scope(…)`); pausing isn't disposal, and a paused scope resumes.
+ */
+export interface Scope extends Disposal {
   run<T>(fn: () => T): T;
   dispose(): void;
   pause(): void;

package/types/index.d.ts

@@ -2,7 +2,8 @@
 import type { Signal } from './signal.js';
 
 export { Signal, isNative } from './signal.js';
-export { effect, scope, flush, tick, type Cleanup, type Scope } from './effect.js';
+export { effect, scope, flush, tick, type Cleanup, type Disposal, type Scope } from './effect.js';
+import type { Disposal } from './effect.js';
 
 /** A value, or a signal holding one: what templates and most hooks accept. */
 export type MaybeSignal<T> = T | Signal.State<T> | Signal.Computed<T>;
@@ -23,7 +24,7 @@ export declare function computed<T>(fn: () => T, options?: Signal.Options<T>): S
 export declare function watch<T>(source: (() => T) | MaybeSignal<T>, callback: (next: T, previous: T) => void): void;
 
 /** Async data as signals; see `resource()`. Awaitable: resolves to the current run's value. */
-export interface Resource<T> extends PromiseLike<T> {
+export interface Resource<T> extends PromiseLike<T>, Disposal {
   /** The latest run's value (or `initial`); kept while the next run is pending. */
   readonly value: T | undefined;
   readonly error: unknown;
@@ -31,6 +32,8 @@ export interface Resource<T> extends PromiseLike<T> {
   readonly loading: boolean;
   /** Run the fetcher again. */
   refresh(): void;
+  /** Stop: abort the run in flight and never run again. `using` does this through `Symbol.dispose`. */
+  dispose(): void;
 }
 /**
  * Run `fetcher` now and whenever a signal it read before its first `await` changes; a new run
@@ -55,7 +58,7 @@ export declare function host<E extends HTMLElement = HTMLElement>(): E;
  * declares every event it sees. Returns false if a listener called `preventDefault()` on a
  * cancelable (`before…`) event.
  */
-export declare function emit(name: string, detail?: unknown): boolean;
+export declare function emit<Detail = unknown>(name: string, detail?: Detail): boolean;
 
 /**
  * The signal itself, where a script passes a signal `const` along: `watch(signal(count), …)`.

package/types/track.d.ts

@@ -0,0 +1,19 @@
+// @zubra/runtime/track: reads after an `await` in a resource's fetcher.
+
+/** What a fetcher wrapped by `tracked()` is given for each run. */
+export interface TrackedRun {
+  /** Aborted when a newer run starts or the resource is disposed. */
+  signal: AbortSignal;
+  /**
+   * Read signals and follow them, after an `await` too: when what `read` returns changes, the
+   * resource runs the fetcher again. A replaced run still reads, without subscribing.
+   */
+  track<V>(read: () => V): V;
+}
+
+/**
+ * Wraps a resource's fetcher so it is also given `track()`:
+ * `resource(tracked(async ({ signal, track }) => …))`. The compiler writes it for an async
+ * fetcher in a `.zb` script.
+ */
+export declare function tracked<T>(fetcher: (run: TrackedRun) => T | PromiseLike<T>): (context: { signal: AbortSignal }) => T | PromiseLike<T>;