@zubra/runtime 5.2.0 → 5.4.0

package/dist/production/deep.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/deep.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/deep.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // Deep reactivity for state: `let items = []` followed by `items.push(x)` updates the DOM.
 //
 // A `state()` holding an array or a plain object holds a proxy of it instead. Each property the
@@ -29,11 +29,14 @@ const isPlain = (value) => {
 /** The object behind a reactive proxy, or the value itself. */
 export const raw = (value) => (value && typeof value === 'object' && value[RAW]) || value;
 
+
 function track(target, key) {
   let map = signals.get(target);
   if (!map) signals.set(target, (map = new Map()));
   let signal = map.get(key);
-  if (!signal) map.set(key, (signal = new Signal.State(0)));
+  if (!signal) {
+    map.set(key, (signal = new Signal.State(0)));
+  }
   signal.get();
 }
 

package/dist/production/effect.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/effect.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/effect.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // Effects and ownership, built only on the Signals API.
 //
 // The Signals proposal intentionally leaves effects and scheduling to libraries; this is ours.
@@ -29,6 +29,7 @@ let scheduled = null;      // promise for the pending microtask flush
 let flushing = false;
 const effectOf = new WeakMap();
 
+
 const watcher = new Signal.subtle.Watcher(() => {
   scheduled ??= new Promise((resolve) => queueMicrotask(() => {
     try { flush(); } finally { scheduled = null; resolve(); }
@@ -214,7 +215,9 @@ export function flush() {
     for (let round = 0; ; round++) {
       const pending = watcher.getPending();
       watcher.watch(); // re-arm before running, so writes made by effects schedule another round
-      if (pending.length === 0) return;
+      if (pending.length === 0) {
+        return;
+      }
       if (round >= MAX_ROUNDS) {
         report(new Error('zubra: effects keep re-triggering each other; stopped after 100 rounds'));
         return;

package/dist/production/element.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/element.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/element.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // define(): the custom element a compiled component becomes.
 //
 // The compiler hands over a template and a list of parts (see src/emit_js.rs). Each part has a
@@ -1673,7 +1673,10 @@ function defineElement(tag, definition) {
         const initial = (name, compute) => {
           if (!this.#given.has(name)) this.#signals[name].set(compute());
         };
-        try { parts = setup ? setup($p, (name, detail) => this.#emit(name, detail), initial) : []; } finally { current = previous; }
+        try {
+          parts = setup ? setup($p, (name, detail) => this.#emit(name, detail), initial
+          ) : [];
+        } finally { current = previous; }
         // A form control with one two-way prop: that's what it submits, and what a form reset
         // restores, unless the script says otherwise.
         const models = Object.keys(props).filter((name) => props[name].model);

package/dist/production/index.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/index.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/index.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // @zubra/runtime — everything compiled components and their scripts import.
 export { Signal, isNative } from './signal.js';
 export { effect, scope, flush, tick } from './effect.js';

package/dist/production/primitives.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/primitives.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/primitives.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // @zubra/runtime/primitives: the two keyboard behaviours the platform doesn't have.
 //
 // The platform now does most of what headless libraries used to: <dialog> traps focus and closes

package/dist/production/react.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/react.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/react.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // React adapter: a zubra element as a React component, for React 18 and 19.
 //
 //   import Rating from './rating.zb'          // the build plugin wraps it for React files

package/dist/production/remark.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/remark.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/remark.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // Server markup whose markers were stripped: the element's runtime loads this module only when it
 // meets such markup.
 //
@@ -10,10 +10,12 @@
 // - an zb-if region holds the branch the current values choose, and an zb-each region one row
 //   per item, each with the shape of its block (checked element by element);
 // - a light-DOM slot region is the rest of its range, when nothing follows it there; its
-//   content is the fallback if it has the fallback's shape, and supplied content otherwise.
-// Anything else (an zb-await, content projected into a child component, a region the server
-// left to the browser, other than one left empty) can't be placed for sure, and the element
-// renders afresh as before.
+//   content is the fallback if it has the fallback's shape, and supplied content otherwise;
+// - an zb-await region holds its zb-then block, for a value known at build time, or its pending
+//   block, which the element renders afresh anyway (so only where the region ends matters).
+// Anything else (content projected into a child component, a region the server left to the
+// browser, other than one left empty or a pending zb-await) can't be placed for sure, and the
+// element renders afresh as before.
 
 const TEXT = 3;
 const COMMENT = 8;
@@ -56,7 +58,12 @@ export function remark(root, template, parts, { blueprint, isOpen, isClose, read
     let index = 0;
     for (; t; t = t.nextSibling) {
       if (t.nodeType === TEXT) {
-        if (cursor?.nodeType === TEXT) cursor = cursor.nextSibling; // static text (if kept)
+        // Static text (if kept): the same words as the template's. Text that isn't (a page's own
+        // `<x-a>Save</x-a>` where the template has only whitespace) isn't server markup.
+        if (cursor?.nodeType === TEXT) {
+          if (cursor.data.trim() !== t.data.trim()) throw fail;
+          cursor = cursor.nextSibling;
+        }
         continue;
       }
       const path = [...prefix, index];
@@ -147,8 +154,40 @@ export function remark(root, template, parts, { blueprint, isOpen, isClose, read
           insert(parent, null, ']');
         }
         cursor = null;
+      } else if (part.await) {
+        // zb-await: the server rendered the zb-then block for a value it knew at build time (a
+        // plain value here too), or the pending block in a region it left to the element, which
+        // the element renders afresh anyway (`[?`): only its extent has to be found, by the
+        // pending block's shape. Failing both, an empty region left to the element, as above.
+        const saved = edits.length;
+        const start = cursor;
+        const value = untrack(() => $r(part.await()));
+        const thenable = (item) => item != null && typeof $r(item)?.then === 'function';
+        const settled = !(Array.isArray(value) ? value.some(thenable) : thenable(value));
+        const attempts = [];
+        if (settled && part.blocks[1]) attempts.push(['[', part.blocks[1], [new State(value), new State(() => {})]]);
+        if (part.blocks[0]) attempts.push(['[?', part.blocks[0], []]);
+        let placed = false;
+        for (const [open, chosen, args] of attempts) {
+          try {
+            insert(parent, cursor, open);
+            cursor = block(chosen, args);
+            insert(parent, cursor, ']');
+            placed = true;
+            break;
+          } catch (error) {
+            if (error !== fail) throw error;
+            edits.length = saved;
+            cursor = start;
+          }
+        }
+        if (!placed) {
+          if (!followsRegion(t, skipText(cursor))) throw fail;
+          insert(parent, cursor, '[?');
+          insert(parent, cursor, ']');
+        }
       } else {
-        throw fail; // zb-await
+        throw fail;
       }
       // Past the template's matching close.
       let depth = 0;

package/dist/production/resource.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/resource.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/resource.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // Async data as signals: `resource(fetcher)`.
 //
 //   const user = resource(({ signal }) => fetch(`/api/users/${p.id}`, { signal }).then((r) => r.json()))

package/dist/production/server.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/server.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/server.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // Server rendering of zubra elements, for framework integrations (the Astro renderer, …).
 //
 // A `.zb` module loads on a server: `define()` returns a stand-in that carries the element's

package/dist/production/signal-impl.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/signal-impl.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/signal-impl.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // An implementation of the TC39 Signals proposal API (https://github.com/tc39/proposal-signals).
 //
 // This is zubra's polyfill boundary for reactivity: compiled components talk only to this API,

package/dist/production/signal.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/signal.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/signal.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // The one place compiled zubra code gets reactivity from.
 //
 // If the platform provides the TC39 Signals API natively, use it. Otherwise fall back to our

package/dist/production/spread.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/spread.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/spread.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // {...spread} in compiled components: an object's entries as an element's attributes,
 // properties and listeners. Its own entry (`@zubra/runtime/spread`), which a compiled module imports
 // only when its template spreads, so components that don't, don't load it.

package/dist/production/vue.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/vue.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/vue.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // Vue 3 adapter: a zubra element as a Vue component.
 //
 //   <script setup>

package/dist/production/zag.js

@@ -1,4 +1,4 @@
-// Generated by scripts/build-production.js from src/zag.js: the runtime without hot reloading. Do not edit.
+// Generated by scripts/build-production.js from src/zag.js: the runtime without hot reloading or the DevTools hook. Do not edit.
 // @zubra/runtime/zag: Zag.js state machines driving zubra components.
 //
 // Zag (https://zagjs.com) is a framework-agnostic set of accessible widget behaviours (combobox,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zubra/runtime",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "Browser runtime for Zubra compiled components, built on the TC39 Signals API",
   "license": "ISC",
   "repository": {

package/src/deep.js

@@ -28,17 +28,33 @@ const isPlain = (value) => {
 /** The object behind a reactive proxy, or the value itself. */
 export const raw = (value) => (value && typeof value === 'object' && value[RAW]) || value;
 
+// @dev
+/**
+ * For the DevTools hook (devtools.js), in development only: each property signal's object and
+ * key, so it can be named, and `wrote` hears each write through a proxy.
+ */
+export const dev = { propertyOf: new WeakMap(), wrote: null };
+// @dev-end
+
 function track(target, key) {
   let map = signals.get(target);
   if (!map) signals.set(target, (map = new Map()));
   let signal = map.get(key);
-  if (!signal) map.set(key, (signal = new Signal.State(0)));
+  if (!signal) {
+    map.set(key, (signal = new Signal.State(0)));
+    // @dev
+    dev.propertyOf.set(signal, { target, key });
+    // @dev-end
+  }
   signal.get();
 }
 
 function trigger(target, key) {
   const signal = signals.get(target)?.get(key);
   if (signal) signal.set(signal.get() + 1);
+  // @dev
+  if (signal) dev.wrote?.(signal);
+  // @dev-end
 }
 
 const handler = {

package/src/devhook.js

@@ -0,0 +1,41 @@
+// What development records for the DevTools, from the page's first element on: which components
+// are on the page, and which listeners each node has. Only element.js imports it, from a
+// `// @dev` block, so the production build (scripts/build-production.js) leaves it out.
+//
+// This part is small and always loaded in development. The reading (devtools.js) is loaded
+// when the browser extension connects, so a page that never opens the pane carries only this.
+
+export const elements = new WeakMap(); // host → { tag, source, props, named, scope }
+export const listeners = new WeakMap(); // node → the listener parts bound to it
+export const hooks = { registered: null }; // devtools.js listens once it's loaded
+
+// Elements from before the reading side loads: it watches their writes when it does. WeakRefs,
+// so a removed element isn't kept alive, and pruned now and then on a page that never connects.
+export const early = [];
+
+/** An element finished setting up (see devtools.js for what the record holds). */
+export function register(host, record) {
+  elements.set(host, record);
+  if (hooks.registered) return hooks.registered(record);
+  if (early.length >= 1000) early.splice(0, Infinity, ...early.filter((ref) => ref.deref()));
+  early.push(new WeakRef(record));
+}
+
+/** A listener part was bound to `node` (effects carry their part; listeners aren't effects). */
+export function listened(part, node) {
+  let parts = listeners.get(node);
+  if (!parts) listeners.set(node, (parts = []));
+  if (!parts.includes(part)) parts.push(part);
+}
+
+let loading = null;
+if (!globalThis.__ZUBRA_DEVTOOLS__) {
+  globalThis.__ZUBRA_DEVTOOLS__ = {
+    version: 1,
+    /** Load the reading side; the extension calls this, then `inspect()` once it's there. */
+    connect() {
+      loading ??= import('./devtools.js');
+      return true;
+    },
+  };
+}

package/src/devtools.js

@@ -0,0 +1,284 @@
+// The DevTools reading side: what the browser extension (editors/devtools) shows for a node.
+// devhook.js records from the page's start and loads this when the extension connects, so a
+// page that never opens the pane doesn't carry it. Neither is in the production build
+// (scripts/build-production.js).
+//
+// The extension reads the page through `globalThis.__ZUBRA_DEVTOOLS__` and nothing else: plain
+// JSON out, so the runtime's internals stay free to change. `version` says which shape.
+//
+// What it knows comes from a `--devtools` build (which @zubra/unplugin makes in Vite's dev
+// server): each part's line and column in the `.zb` file, the file itself, and the script's
+// signals by name. Without that build, an element still shows its tag, props and bindings,
+// unlocated and with fewer names.
+//
+// The dependencies are read through `Signal.subtle.introspectSources`, the Signals proposal's
+// own introspection, so the same view works on the polyfill and on a native `Signal`.
+import { Signal, isNative } from './signal.js';
+import { dev as effects } from './effect.js';
+import { dev as deep, raw } from './deep.js';
+import { elements, listeners, hooks, early } from './devhook.js';
+
+const { introspectSources, untrack } = Signal.subtle;
+const isComputed = (value) => value instanceof Signal.Computed;
+const isState = (value) => value instanceof Signal.State;
+
+// The most recent flush since connecting: the effects it re-ran, and the signals written since
+// the one before.
+let writes = new Set();
+let last = { ran: new Set(), written: new Set() };
+let updates = 0;
+
+effects.flushed = (ran) => {
+  last = { ran: new Set(ran), written: writes };
+  writes = new Set();
+  updates++;
+};
+const wrote = (signal) => {
+  // A write nothing reads never flushes: don't let those pile up.
+  if (writes.size > 1000) writes = new Set();
+  writes.add(signal);
+};
+deep.wrote = wrote;
+
+/** Watch writes to a signal (a prop's, or a named state's). */
+function watchWrites(signal) {
+  if (signal.__zubraWatched) return;
+  const set = signal.set;
+  signal.set = function (value) {
+    wrote(signal);
+    return set.call(this, value);
+  };
+  Object.defineProperty(signal, '__zubraWatched', { value: true });
+}
+
+/** Watch a component's props and named state (once; elements from before connecting too). */
+function watch(record) {
+  if (record.watched) return;
+  record.watched = true;
+  for (const signal of Object.values(record.props)) watchWrites(signal);
+  for (const signal of Object.values(record.named ?? {})) {
+    if (isState(signal) || typeof signal?.set === 'function') watchWrites(signal);
+  }
+}
+hooks.registered = watch;
+for (const ref of early.splice(0)) {
+  const record = ref.deref();
+  if (record) watch(record);
+}
+
+// ---- reading -------------------------------------------------------------------------------
+
+/** The nearest registered component at or above `node`, crossing shadow roots. */
+function hostOf(node, skipSelf = false) {
+  for (let at = skipSelf ? up(node) : node; at; at = up(at)) if (elements.has(at)) return at;
+  return null;
+}
+const up = (node) => node.parentNode ?? node.host ?? null;
+
+/** Every effect `owner` owns, depth first (a component's own: child components have their own roots). */
+function effectsOf(owner, out = []) {
+  for (const child of owner.children) {
+    if (child.disposed) continue;
+    if (child.computed) out.push(child);
+    effectsOf(child, out);
+  }
+  return out;
+}
+
+// Form controls' live state, which the runtime sets as a property (element.js, bindAttribute).
+const LIVE = new Set(['input.value', 'textarea.value', 'select.value', 'input.checked', 'option.selected']);
+
+/** The DOM operation a part performs on `node`, in the platform's terms. */
+export function operation(part, node) {
+  if (part.text) return 'textContent = …';
+  if (part.anchor) return 'Text.data = …';
+  if (part.global) return `${part.global}.addEventListener('${part.on}', …)`;
+  if (part.on) return `addEventListener('${part.on}', …)`;
+  if (part.classes) return 'classList.add/remove(…)';
+  if (part.toggle) return `classList.toggle('${part.toggle}', …)`;
+  if (part.style) return `style.setProperty('${part.style}', …)`;
+  if (part.ref) return 'ref(element)';
+  if (part.property) return `.${part.property} = …`;
+  if (part.attribute) {
+    if (node && LIVE.has(`${node.localName}.${part.attribute}`)) return `.${part.attribute} = …`;
+    if (part.boolean) return `toggleAttribute('${part.attribute}', …)`;
+    if (part.prop) return `.${part.prop} = … (or setAttribute('${part.attribute}', …))`;
+    return `setAttribute('${part.attribute}', …)`;
+  }
+  if (part.when) return 'zb-if: insert or remove a block';
+  if (part.each) return 'zb-each: add, move or remove rows';
+  if (part.await) return 'zb-await: pending, then or catch';
+  if (part.slot) return `slot "${part.slot}"`;
+  if (part.spread) return 'spread: attributes and properties';
+  return 'binding';
+}
+
+/** A short name for a node: `<button.on>`, or its parent's for a text anchor or region marker. */
+function describe(node) {
+  if (!node) return '?';
+  if (node.nodeType === 1) {
+    const id = node.id ? `#${node.id}` : '';
+    const classes = [...(node.classList ?? [])].slice(0, 2).map((name) => `.${name}`).join('');
+    return `<${node.localName}${id}${classes}>`;
+  }
+  return node.parentNode?.nodeType === 1 ? `${describe(node.parentNode)} content` : node.nodeName;
+}
+
+/** A value as a short string: the pane shows values, it doesn't hold them. */
+export function preview(value, depth = 0) {
+  value = raw(value);
+  if (value === undefined) return 'undefined';
+  if (value === null || typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (typeof value === 'string') return JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}…` : value);
+  if (typeof value === 'bigint') return `${value}n`;
+  if (typeof value === 'symbol') return value.toString();
+  if (typeof value === 'function') return `ƒ ${value.name || 'anonymous'}()`;
+  if (isComputed(value) || isState(value)) return preview(untrack(() => value.get()), depth);
+  if (typeof Node !== 'undefined' && value instanceof Node) return describe(value);
+  if (value instanceof Promise) return 'Promise';
+  if (Array.isArray(value)) {
+    if (depth > 1) return `Array(${value.length})`;
+    const shown = value.slice(0, 5).map((item) => preview(item, depth + 1));
+    return `[${shown.join(', ')}${value.length > 5 ? `, … ${value.length - 5} more` : ''}]`;
+  }
+  const name = value.constructor && value.constructor !== Object ? value.constructor.name : '';
+  if (depth > 1) return name || '{…}';
+  const keys = Object.keys(value);
+  const shown = keys.slice(0, 5).map((key) => `${key}: ${preview(value[key], depth + 1)}`);
+  return `${name ? `${name} ` : ''}{${shown.join(', ')}${keys.length > 5 ? ', …' : ''}}`;
+}
+
+/**
+ * Names for the signals a component can read: its props and named script signals, and the
+ * property signals of the arrays and objects they hold (`items[0].done`, `items.length`).
+ */
+function namer(record) {
+  const names = new Map();
+  for (const [name, signal] of Object.entries(record.props)) names.set(signal, name);
+  for (const [name, signal] of Object.entries(record.named ?? {})) if (signal && typeof signal === 'object') names.set(signal, name);
+  const paths = new Map(); // raw object → path
+  const walk = (value, path, depth) => {
+    value = raw(value);
+    if (!value || typeof value !== 'object' || paths.has(value) || depth > 3) return;
+    paths.set(value, path);
+    if (Array.isArray(value)) value.slice(0, 200).forEach((item, i) => walk(item, `${path}[${i}]`, depth + 1));
+    else if (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) {
+      for (const key of Object.keys(value).slice(0, 50)) walk(value[key], `${path}.${key}`, depth + 1);
+    }
+  };
+  for (const [signal, name] of names) {
+    try { walk(untrack(() => signal.get()), name, 0); } catch {}
+  }
+  return (signal) => {
+    if (names.has(signal)) return names.get(signal);
+    const property = deep.propertyOf.get(signal);
+    if (!property) return null;
+    const path = paths.get(property.target);
+    if (!path) return null;
+    const { key } = property;
+    if (typeof key === 'symbol') return path; // its keys
+    return /^\d+$/.test(key) ? `${path}[${key}]` : `${path}.${key}`;
+  };
+}
+
+/** The named signals `sink` reads, looking through unnamed computeds to the names behind them. */
+function dependencies(sink, name) {
+  const found = [];
+  const seen = new Set();
+  const visit = (node, depth) => {
+    let sources;
+    try { sources = introspectSources(node); } catch { return; }
+    for (const source of sources) {
+      if (seen.has(source)) continue;
+      seen.add(source);
+      const label = name(source);
+      if (label) {
+        if (!found.includes(label)) found.push(label);
+      } else if (isComputed(source) && depth < 6) visit(source, depth + 1);
+    }
+  };
+  visit(sink, 0);
+  return found;
+}
+
+const location = (part) => (Array.isArray(part?.at) ? { line: part.at[0], column: part.at[1] } : null);
+
+/** One binding as the pane shows it. */
+function binding(part, node, effect, name, selected) {
+  return {
+    operation: operation(part, node),
+    target: describe(node),
+    at: location(part),
+    dependsOn: effect ? dependencies(effect.computed, name) : [],
+    ranLast: !!effect && last.ran.has(effect),
+    here: node === selected || (node?.nodeType !== 1 && node?.parentNode === selected),
+  };
+}
+
+/** What the pane shows for `node`: its component, and that component's state and bindings. */
+export function inspect(node) {
+  if (!node) return { version: 1, component: null };
+  const host = hostOf(node);
+  if (!host) return { version: 1, component: null, native: isNative };
+  const record = elements.get(host);
+  watch(record);
+  const name = namer(record);
+  const effects = record.scope ? effectsOf(record.scope) : [];
+  const bindings = effects
+    .filter((effect) => effect.label)
+    .map((effect) => binding(effect.label.part, effect.label.node, effect, name, node));
+  // Listeners on the selected node (on the host itself, they're its parent's: see `setBy`).
+  if (node !== host) for (const part of listeners.get(node) ?? []) bindings.unshift(binding(part, node, null, name, node));
+  // The selected node is itself a component: what its parent binds onto it (its props, its events).
+  let setBy = null;
+  const parent = node === host ? hostOf(host, true) : null;
+  if (parent) {
+    const parentRecord = elements.get(parent);
+    const parentName = namer(parentRecord);
+    const onto = (parentRecord.scope ? effectsOf(parentRecord.scope) : [])
+      .filter((effect) => effect.label?.node === host)
+      .map((effect) => binding(effect.label.part, host, effect, parentName, host));
+    for (const part of listeners.get(host) ?? []) onto.push(binding(part, host, null, parentName, host));
+    if (onto.length) setBy = { tag: parentRecord.tag, file: parentRecord.definition.source?.file ?? null, bindings: onto };
+  }
+  const values = (entries) => entries.map(([key, signal]) => ({ name: key, value: preview(signal) }));
+  const written = [...last.written].map(name).filter(Boolean);
+  return {
+    version: 1,
+    native: isNative,
+    update: updates,
+    component: {
+      tag: record.tag,
+      file: record.definition.source?.file ?? null,
+      at: location(record.definition.source),
+      located: !!record.definition.source,
+    },
+    props: values(Object.entries(record.props)),
+    state: values(Object.entries(record.named ?? {}).filter(([, signal]) => signal && typeof signal === 'object')),
+    bindings,
+    setBy,
+    lastUpdate: {
+      number: updates,
+      written: [...new Set(written)],
+      ran: bindings.filter((item) => item.ranLast).length,
+    },
+  };
+}
+
+/** Open `file` at `line` and `column` in the editor, through Vite's dev server (or the page). */
+export function open(file, line = 1, column = 1) {
+  // A page can show the place itself (the playground selects the line in its editor): it
+  // cancels this event. Otherwise Vite's dev server opens the editor.
+  const event = new CustomEvent('zubra:open', { detail: { file, line, column }, cancelable: true });
+  if (!globalThis.dispatchEvent(event)) return Promise.resolve(true);
+  return fetch(`/__open-in-editor?file=${encodeURIComponent(`${file}:${line}:${column}`)}`).then((response) => response.ok, () => false);
+}
+
+// (defineProperties, not Object.assign, which would copy the getter's value once.)
+Object.defineProperties(globalThis.__ZUBRA_DEVTOOLS__, {
+  ready: { value: true, enumerable: true },
+  inspect: { value: inspect, enumerable: true },
+  open: { value: open, enumerable: true },
+  /** Counts flushes since connecting: the pane re-reads when it changes. */
+  updates: { get: () => updates, enumerable: true },
+});

package/src/effect.js

@@ -28,6 +28,15 @@ let scheduled = null;      // promise for the pending microtask flush
 let flushing = false;
 const effectOf = new WeakMap();
 
+// @dev
+/**
+ * For the DevTools hook (devtools.js), in development only: `label` is what the effect being
+ * created binds (element.js sets it around each binding), and `flushed` hears which effects each
+ * flush re-ran.
+ */
+export const dev = { label: null, flushed: null };
+// @dev-end
+
 const watcher = new Signal.subtle.Watcher(() => {
   scheduled ??= new Promise((resolve) => queueMicrotask(() => {
     try { flush(); } finally { scheduled = null; resolve(); }
@@ -113,6 +122,9 @@ class Effect extends Owner {
     super(parent);
     this.id = ++nextId;
     this.cleanup = undefined;
+    // @dev
+    this.label = dev.label;
+    // @dev-end
     this.computed = new Signal.Computed(() => {
       this.disposeChildren();
       this.runCleanup();
@@ -209,11 +221,19 @@ export function root(fn) {
 export function flush() {
   if (flushing) return;
   flushing = true;
+  // @dev
+  const ran = [];
+  // @dev-end
   try {
     for (let round = 0; ; round++) {
       const pending = watcher.getPending();
       watcher.watch(); // re-arm before running, so writes made by effects schedule another round
-      if (pending.length === 0) return;
+      if (pending.length === 0) {
+        // @dev
+        if (ran.length) dev.flushed?.(ran);
+        // @dev-end
+        return;
+      }
       if (round >= MAX_ROUNDS) {
         report(new Error('zubra: effects keep re-triggering each other; stopped after 100 rounds'));
         return;
@@ -222,6 +242,9 @@ export function flush() {
       for (const e of effects) {
         if (e.disposed || e.paused) continue;
         try { e.run(); } catch (error) { report(error); }
+        // @dev
+        ran.push(e);
+        // @dev-end
       }
     }
   } finally {

package/src/element.js

@@ -12,6 +12,10 @@ import { Signal } from './signal.js';
 import { wrap, raw } from './deep.js';
 import { effect, scope, root as rootScope, tick, batch } from './effect.js';
 import { RESOURCE } from './resource.js';
+// @dev (left out of the production build: scripts/build-production.js)
+import { dev as devEffects } from './effect.js';
+import { register as devRegister, listened as devListened } from './devhook.js';
+// @dev-end
 
 const { untrack } = Signal.subtle;
 const TEXT = 3;
@@ -690,6 +694,12 @@ function listen(part, node) {
 }
 
 function bind(part, node, hydrating, context) {
+  // @dev
+  // The effects created here are this part's (for the DevTools hook, devtools.js).
+  const outerLabel = devEffects.label;
+  devEffects.label = { part, node };
+  if (part.on && !part.global) devListened(part, node);
+  // @dev-end
   if (part.text) {
     effect(() => {
       const text = part.text();
@@ -764,6 +774,9 @@ function bind(part, node, hydrating, context) {
   } else if (part.slot) {
     bindSlot(part, node, hydrating, context);
   }
+  // @dev
+  devEffects.label = outerLabel;
+  // @dev-end
 }
 
 /** The signal saying whether slot `name` has content (shared by hasSlot() and the slot). */
@@ -1738,6 +1751,9 @@ function defineElement(tag, definition) {
         mount: [], unmount: [], host: this, props: $p, instance: ++instances, ids: 0, filled: new Map(), states: [], kept, hydrated: new Signal.State(false),
         internals: this.#internals, formReset: [], formRestore: [], formDisabled: [],
       };
+      // @dev
+      let named = null; // the script's signals by name (a --devtools build)
+      // @dev-end
       // The element's own root: an effect that inserted it (a list row) doesn't own it, so
       // re-running that effect can't dispose the element's effects.
       this.#scope = rootScope(() => {
@@ -1749,7 +1765,17 @@ function defineElement(tag, definition) {
         const initial = (name, compute) => {
           if (!this.#given.has(name)) this.#signals[name].set(compute());
         };
-        try { parts = setup ? setup($p, (name, detail) => this.#emit(name, detail), initial) : []; } finally { current = previous; }
+        // @dev
+        // A --devtools build hands over its script's signals by name, for the DevTools hook.
+        const dev = (names) => { named = names; };
+        // @dev-end
+        try {
+          parts = setup ? setup($p, (name, detail) => this.#emit(name, detail), initial
+            // @dev
+            , dev
+            // @dev-end
+          ) : [];
+        } finally { current = previous; }
         // A form control with one two-way prop: that's what it submits, and what a form reset
         // restores, unless the script says otherwise.
         const models = Object.keys(props).filter((name) => props[name].model);
@@ -1829,6 +1855,9 @@ function defineElement(tag, definition) {
       // always calls formDisabledCallback after connectedCallback, so this never runs there (the
       // browser tests confirm the behaviour without it); it guards engines that order the
       // callbacks the other way, which the test suite can't currently exercise.
+      // @dev
+      devRegister(this, { tag, definition, props: this.#signals, named, scope: this.#scope });
+      // @dev-end
       if (this.#disabled) for (const fn of this.#hooks.formDisabled) fn(true);
     }
   }

package/src/remark.js

@@ -9,10 +9,12 @@
 // - an zb-if region holds the branch the current values choose, and an zb-each region one row
 //   per item, each with the shape of its block (checked element by element);
 // - a light-DOM slot region is the rest of its range, when nothing follows it there; its
-//   content is the fallback if it has the fallback's shape, and supplied content otherwise.
-// Anything else (an zb-await, content projected into a child component, a region the server
-// left to the browser, other than one left empty) can't be placed for sure, and the element
-// renders afresh as before.
+//   content is the fallback if it has the fallback's shape, and supplied content otherwise;
+// - an zb-await region holds its zb-then block, for a value known at build time, or its pending
+//   block, which the element renders afresh anyway (so only where the region ends matters).
+// Anything else (content projected into a child component, a region the server left to the
+// browser, other than one left empty or a pending zb-await) can't be placed for sure, and the
+// element renders afresh as before.
 
 const TEXT = 3;
 const COMMENT = 8;
@@ -55,7 +57,12 @@ export function remark(root, template, parts, { blueprint, isOpen, isClose, read
     let index = 0;
     for (; t; t = t.nextSibling) {
       if (t.nodeType === TEXT) {
-        if (cursor?.nodeType === TEXT) cursor = cursor.nextSibling; // static text (if kept)
+        // Static text (if kept): the same words as the template's. Text that isn't (a page's own
+        // `<x-a>Save</x-a>` where the template has only whitespace) isn't server markup.
+        if (cursor?.nodeType === TEXT) {
+          if (cursor.data.trim() !== t.data.trim()) throw fail;
+          cursor = cursor.nextSibling;
+        }
         continue;
       }
       const path = [...prefix, index];
@@ -146,8 +153,40 @@ export function remark(root, template, parts, { blueprint, isOpen, isClose, read
           insert(parent, null, ']');
         }
         cursor = null;
+      } else if (part.await) {
+        // zb-await: the server rendered the zb-then block for a value it knew at build time (a
+        // plain value here too), or the pending block in a region it left to the element, which
+        // the element renders afresh anyway (`[?`): only its extent has to be found, by the
+        // pending block's shape. Failing both, an empty region left to the element, as above.
+        const saved = edits.length;
+        const start = cursor;
+        const value = untrack(() => $r(part.await()));
+        const thenable = (item) => item != null && typeof $r(item)?.then === 'function';
+        const settled = !(Array.isArray(value) ? value.some(thenable) : thenable(value));
+        const attempts = [];
+        if (settled && part.blocks[1]) attempts.push(['[', part.blocks[1], [new State(value), new State(() => {})]]);
+        if (part.blocks[0]) attempts.push(['[?', part.blocks[0], []]);
+        let placed = false;
+        for (const [open, chosen, args] of attempts) {
+          try {
+            insert(parent, cursor, open);
+            cursor = block(chosen, args);
+            insert(parent, cursor, ']');
+            placed = true;
+            break;
+          } catch (error) {
+            if (error !== fail) throw error;
+            edits.length = saved;
+            cursor = start;
+          }
+        }
+        if (!placed) {
+          if (!followsRegion(t, skipText(cursor))) throw fail;
+          insert(parent, cursor, '[?');
+          insert(parent, cursor, ']');
+        }
       } else {
-        throw fail; // zb-await
+        throw fail;
       }
       // Past the template's matching close.
       let depth = 0;