@govela/runtime 0.0.0-stage → 0.3.0

package/runtime-blocks.js

@@ -0,0 +1,875 @@
+/**
+ * Vela block runtime (docs/HYDRATION_ARCHITECTURE.md).
+ *
+ * Structural template behaviour lives here once instead of being generated
+ * into every component: compiled fragments build DOM through a cursor, and
+ * blocks ($$if, $$each, $$key, $$await, $$component, $$slot, $$client) own
+ * their DOM ranges and child resources.
+ *
+ * Fragment contract (F-2.x): a fragment is `(cursor, scope) => handle`, where
+ * handle is `{ p(dirty, scopeChanged) }` or undefined. The runtime never
+ * interprets `dirty`; blocks receive an optional `changed(dirty)` predicate
+ * generated by the compiler and forward `dirty` to their fragments.
+ */
+
+import { $$runtimeContract1 } from './runtime.js';
+void $$runtimeContract1;
+
+// ── Owners ───────────────────────────────────────────────────────────────
+// An owner collects the resources created while a fragment mounts
+// (listeners, child blocks, component instances, deferred work) and releases
+// them in reverse registration order (B-3.2, B-3.3). Releasing never touches
+// the DOM: the block that owns a range removes it as a whole.
+
+// stats counts live owners and listeners for the destroy checks of the
+// test harness (Q-10.2 item 5, task 052).
+const stats = { owners: 0, listeners: 0 };
+
+// $$debugStats reports live owners, live listeners, and queued updates.
+export function $$debugStats() {
+  const batch = globalThis[Symbol.for('vela.batch')];
+  return { owners: stats.owners, listeners: stats.listeners, queued: batch ? batch.queue.length : 0 };
+}
+
+// $$listen adds an event listener that the owner removes.
+export function $$listen(owner, target, event, handler, options) {
+  target.addEventListener(event, handler, options);
+  stats.listeners++;
+  owner.add(() => {
+    target.removeEventListener(event, handler, options);
+    stats.listeners--;
+  });
+}
+
+export function $$owner(parent) {
+  stats.owners++;
+  const owner = {
+    done: false,
+    cleanups: [],
+    add(cleanup) {
+      if (owner.done) {
+        cleanup();
+        return;
+      }
+      owner.cleanups.push(cleanup);
+    },
+    release() {
+      if (owner.done) return;
+      owner.done = true;
+      stats.owners--;
+      const cleanups = owner.cleanups;
+      owner.cleanups = [];
+      for (let i = cleanups.length - 1; i >= 0; i--) cleanups[i]();
+    },
+  };
+  if (parent) parent.add(() => owner.release());
+  return owner;
+}
+
+// ── Ranges ───────────────────────────────────────────────────────────────
+// A range is the DOM a fragment occupies. A single top-level element or text
+// node is its own range; anything else is wrapped in an empty comment pair,
+// so nodes added later by nested blocks stay inside it.
+
+function rangeOf(fragment) {
+  const nodes = fragment.childNodes;
+  if (nodes.length === 1 && (nodes[0].nodeType === 1 || nodes[0].nodeType === 3)) {
+    return { start: nodes[0], end: nodes[0] };
+  }
+  const start = document.createComment('');
+  const end = document.createComment('');
+  fragment.insertBefore(start, fragment.firstChild);
+  fragment.appendChild(end);
+  return { start, end };
+}
+
+function rangeNodes(range) {
+  const nodes = [];
+  // An adopted fragment with no nodes has no range (hydration, C-4.3).
+  if (!range) return nodes;
+  for (let node = range.start; node; node = node.nextSibling) {
+    nodes.push(node);
+    if (node === range.end) break;
+  }
+  return nodes;
+}
+
+function removeRange(range) {
+  for (const node of rangeNodes(range)) node.remove();
+}
+
+function moveRange(range, before) {
+  const parent = before.parentNode;
+  for (const node of rangeNodes(range)) parent.insertBefore(node, before);
+}
+
+function rangeContains(range, node) {
+  for (const item of rangeNodes(range)) {
+    if (item === node || item.contains(node)) return true;
+  }
+  return false;
+}
+
+// ── Create cursor ────────────────────────────────────────────────────────
+// The create cursor builds new DOM (C-4.1). The hydrate cursor of task 041
+// implements the same interface over existing server DOM.
+
+export function $$template(html) {
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  return template;
+}
+
+function createCursor(parent, before, owner) {
+  const stack = [];
+  const cursor = {
+    owner,
+    hydrating: false,
+    // at names the next adopted site for hydration reports (V-11.3b).
+    at() {},
+    insert(node) {
+      parent.insertBefore(node, before);
+      return node;
+    },
+    // element creates an element with its static attributes, given as a flat
+    // [name, value, ...] list (the scope attribute comes first).
+    element(tag, attrs) {
+      const element = document.createElement(tag);
+      if (attrs) for (let i = 0; i < attrs.length; i += 2) element.setAttribute(attrs[i], attrs[i + 1]);
+      return cursor.insert(element);
+    },
+    text(value) {
+      return cursor.insert(document.createTextNode(value));
+    },
+    comment() {
+      return cursor.insert(document.createComment(''));
+    },
+    static(template) {
+      const content = template.content.cloneNode(true);
+      const nodes = [...content.childNodes];
+      cursor.insert(content);
+      return nodes;
+    },
+    enter(element) {
+      stack.push([parent, before]);
+      parent = element;
+      before = null;
+    },
+    exit() {
+      [parent, before] = stack.pop();
+    },
+    // init runs an initial DOM write (attribute, property, class, style,
+    // control value). The hydrate cursor adopts the server value instead
+    // (F-2.2), so writes go through this hook rather than running inline.
+    init(write) {
+      write();
+    },
+    // adopt takes a live control value on hydration (C-4.5); creating has
+    // nothing to adopt.
+    adopt() {},
+    listen(target, event, handler, options) {
+      $$listen(owner, target, event, handler, options);
+    },
+    block(kind, ...args) {
+      return kind(cursor, ...args);
+    },
+  };
+  return cursor;
+}
+
+// mountFragment builds a fragment detached from the document, computes its
+// range, then inserts it before `before`. The owning block releases the
+// fragment, so its owner is not registered with a parent: a parent cleanup
+// per mounted branch or row would accumulate across updates.
+function mountFragment(fragmentFn, scope, before) {
+  const owner = $$owner(null);
+  const container = document.createDocumentFragment();
+  const handle = fragmentFn(createCursor(container, null, owner), scope);
+  const range = rangeOf(container);
+  before.parentNode.insertBefore(container, before);
+  return { owner, handle, range, scope };
+}
+
+function updateMounted(mounted, dirty, scopeChanged) {
+  if (mounted && mounted.handle && mounted.handle.p) mounted.handle.p(dirty, scopeChanged);
+}
+
+function unmount(mounted) {
+  if (!mounted) return;
+  mounted.owner.release();
+  removeRange(mounted.range);
+}
+
+// registerBlock ties a block to its owner and gives it the common
+// destroy/abandon behaviour (B-3.3, B-3.4).
+function registerBlock(cursor, block, anchor, release) {
+  let done = false;
+  const finish = (removeDom) => {
+    if (done) return;
+    done = true;
+    release(removeDom);
+    if (removeDom) anchor.remove();
+  };
+  block.destroy = () => finish(true);
+  block.abandon = () => finish(false);
+  block.isDone = () => done;
+  cursor.owner.add(() => finish(false));
+  return block;
+}
+
+// ── Root ─────────────────────────────────────────────────────────────────
+
+// $$mountRoot mounts a component's root fragment into target (an element,
+// or a comment anchor that the content is inserted before).
+export function $$mountRoot(target, fragmentFn, scope) {
+  const owner = $$owner(null);
+  const before = target.nodeType === 8 ? target : null;
+  const parent = before ? before.parentNode : target;
+  const handle = fragmentFn(createCursor(parent, before, owner), scope);
+  return {
+    owner,
+    p(dirty) {
+      if (handle && handle.p) handle.p(dirty, false);
+    },
+    release() {
+      owner.release();
+    },
+  };
+}
+
+
+// ── Hydration session ────────────────────────────────────────────────────
+// While hydrate() (runtime-hydrate.js) adopts a root, the session holds the
+// payload stream and the hydrate cursor at the position where the next
+// component factory adopts its DOM. Every mount after the root commits
+// creates DOM (C-4.4).
+
+let $$session = null;
+
+// $$setHydration installs or clears the session (runtime-hydrate.js).
+export function $$setHydration(session) {
+  const previous = $$session;
+  $$session = session;
+  return previous;
+}
+
+// $$hydrationState returns the restored state of the component instance
+// that starts now: its "s" entry without omitted bindings (S-6.8), or null
+// when the component is created rather than hydrated.
+export function $$hydrationState(component) {
+  if (!$$session || !$$session.cursors[$$session.cursors.length - 1]) return null;
+  return $$session.state(component);
+}
+
+// withComponentCursor makes cursor the position the next component factory
+// hydrates at.
+function withComponentCursor(cursor, mount) {
+  $$session.cursors.push(cursor);
+  try {
+    return mount();
+  } finally {
+    $$session.cursors.pop();
+  }
+}
+
+// $$mountComponent mounts a component's root fragment. Created: into a new
+// display:contents wrapper (when wrapperScope is not null; "" is a wrapper
+// without a scope attribute, for a component without styles) or a detached
+// fragment, then inserted at target. Hydrated: on the server DOM at the
+// cursor of the enclosing block or root. setRoot receives the wrapper;
+// getRoot returns the component element afterwards.
+export function $$mountComponent(target, fragmentFn, wrapperScope, setRoot, getRoot) {
+  const outer = $$session ? $$session.cursors[$$session.cursors.length - 1] || null : null;
+  if (outer) {
+    const owner = $$owner(null);
+    let handle;
+    if (wrapperScope != null) {
+      const wrapper = outer.element('div', wrapperScope ? [wrapperScope, '', 'style', 'display: contents;'] : ['style', 'display: contents;']);
+      setRoot(wrapper);
+      outer.enter(wrapper);
+      handle = fragmentFn(outer.sub(owner));
+      outer.exit();
+    } else {
+      handle = fragmentFn(outer.sub(owner));
+    }
+    return rootView(owner, handle);
+  }
+  let view;
+  if (wrapperScope != null) {
+    const wrapper = document.createElement('div');
+    if (wrapperScope) wrapper.setAttribute(wrapperScope, '');
+    wrapper.style.display = 'contents';
+    setRoot(wrapper);
+    view = $$mountRoot(wrapper, fragmentFn);
+  } else {
+    view = $$mountRoot(document.createDocumentFragment(), fragmentFn);
+  }
+  const root = getRoot();
+  if (target.nodeType === 8) target.parentNode.insertBefore(root, target);
+  else target.appendChild(root);
+  return view;
+}
+
+function rootView(owner, handle) {
+  return {
+    owner,
+    p(dirty) {
+      if (handle && handle.p) handle.p(dirty, false);
+    },
+    release() {
+      owner.release();
+    },
+  };
+}
+// ── $$if ─────────────────────────────────────────────────────────────────
+// select() returns the active branch index or -1.
+
+export function $$if(cursor, select, branches, changed) {
+  let anchor;
+  let index = -1;
+  let current = null;
+  const show = (next) => {
+    index = next;
+    current = next >= 0 ? mountFragment(branches[next], undefined, anchor) : null;
+  };
+  if (cursor.hydrating) {
+    // The range state is the branch the server rendered (X-7.1).
+    const token = cursor.open();
+    index = select();
+    cursor.expect(token === (index >= 0 ? String(index) : 'x'), `#if renders branch ${index >= 0 ? index : 'x'}, the server rendered ${token}`);
+    if (index >= 0) current = cursor.mount(branches[index]);
+    anchor = cursor.close();
+  } else {
+    anchor = cursor.comment();
+    show(select());
+  }
+  const block = {
+    p(dirty) {
+      if (block.isDone()) return;
+      if (!changed || changed(dirty)) {
+        const next = select();
+        if (next !== index) {
+          unmount(current);
+          show(next);
+          return;
+        }
+      }
+      updateMounted(current, dirty, false);
+    },
+    move(before) {
+      if (current) moveRange(current.range, before);
+      before.parentNode.insertBefore(anchor, before);
+    },
+  };
+  return registerBlock(cursor, block, anchor, (removeDom) => {
+    if (!current) return;
+    if (removeDom) unmount(current);
+    else current.owner.release();
+  });
+}
+
+// ── $$key ────────────────────────────────────────────────────────────────
+
+export function $$key(cursor, value, body, changed) {
+  let anchor;
+  let key = value();
+  let current;
+  if (cursor.hydrating) {
+    cursor.open();
+    current = cursor.mount(body);
+    anchor = cursor.close();
+  } else {
+    anchor = cursor.comment();
+    current = mountFragment(body, undefined, anchor);
+  }
+  const block = {
+    p(dirty) {
+      if (block.isDone()) return;
+      if (!changed || changed(dirty)) {
+        const next = value();
+        if (next !== key) {
+          key = next;
+          unmount(current);
+          current = mountFragment(body, undefined, anchor);
+          return;
+        }
+      }
+      updateMounted(current, dirty, false);
+    },
+    move(before) {
+      moveRange(current.range, before);
+      before.parentNode.insertBefore(anchor, before);
+    },
+  };
+  return registerBlock(cursor, block, anchor, (removeDom) => {
+    if (removeDom) unmount(current);
+    else current.owner.release();
+  });
+}
+
+// ── $$each ───────────────────────────────────────────────────────────────
+// collection() returns the iterable; key(item, index) returns the row key or
+// is null for an unkeyed list. A row fragment receives the scope
+// { item, index } and is updated in place with scopeChanged = true.
+// dirtyRows(), when given, returns the indexes of rows changed only by
+// in-place mutation of a deep collection (or null): those rows update
+// without a reconciliation, as long as the row count is unchanged.
+
+export function $$each(cursor, collection, key, row, fallback, changed, dirtyRows) {
+  let anchor;
+  let rows = [];
+  let byKey = key ? new Map() : null;
+  let empty = null;
+
+  const mountRow = (item, index, before) => mountFragment(row, { item, index }, before);
+
+  const reconcile = (dirty, initial) => {
+    const items = Array.from(collection() || []);
+    if (items.length === 0) {
+      for (const mounted of rows) unmount(mounted);
+      rows = [];
+      if (byKey) byKey.clear();
+      if (fallback && !empty) empty = mountFragment(fallback, undefined, anchor);
+      else updateMounted(empty, dirty, false);
+      return;
+    }
+    if (empty) {
+      unmount(empty);
+      empty = null;
+    }
+    if (!byKey) {
+      // Unkeyed: rows are positional and update in place.
+      for (let i = 0; i < items.length; i++) {
+        if (i < rows.length) {
+          rows[i].scope.item = items[i];
+          rows[i].scope.index = i;
+          updateMounted(rows[i], dirty, true);
+        } else {
+          rows.push(mountRow(items[i], i, anchor));
+        }
+      }
+      for (const mounted of rows.splice(items.length)) unmount(mounted);
+      return;
+    }
+    // Keyed: retain, move, create and remove rows by key; keep focus inside a
+    // retained row that moves.
+    const focused = initial ? null : document.activeElement;
+    const restoreFocus = focused && focused !== document.body &&
+      rows.some((mounted) => rangeContains(mounted.range, focused));
+    const next = [];
+    const nextKeys = new Map();
+    for (let i = 0; i < items.length; i++) {
+      const rowKey = key(items[i], i);
+      nextKeys.set(rowKey, i);
+      let mounted = byKey.get(rowKey);
+      if (mounted) {
+        mounted.scope.item = items[i];
+        mounted.scope.index = i;
+        updateMounted(mounted, dirty, true);
+      } else {
+        mounted = mountRow(items[i], i, anchor);
+        byKey.set(rowKey, mounted);
+      }
+      mounted.key = rowKey;
+      next.push(mounted);
+    }
+    for (const [rowKey, mounted] of byKey) {
+      if (!nextKeys.has(rowKey)) {
+        unmount(mounted);
+        byKey.delete(rowKey);
+      }
+    }
+    // Place rows in order, moving only those not already in position.
+    let before = anchor;
+    for (let i = next.length - 1; i >= 0; i--) {
+      const mounted = next[i];
+      if (mounted.range.end.nextSibling !== before) moveRange(mounted.range, before);
+      before = mounted.range.start;
+    }
+    rows = next;
+    if (restoreFocus && focused.isConnected && typeof focused.focus === 'function' &&
+        document.activeElement !== focused) {
+      focused.focus();
+    }
+  };
+
+  if (cursor.hydrating) {
+    // Rows are adopted in order; keys come from the restored collection
+    // (S-6.10). A different row count leaves a row marker or the end
+    // marker unconsumed, which the cursor reports (X-7.1).
+    const token = cursor.open();
+    const items = Array.from(collection() || []);
+    if (items.length === 0) {
+      cursor.expect(token === (fallback ? 'e' : ''), `#each is empty, the server rendered ${token === 'e' ? 'the fallback' : 'rows'}`);
+      if (fallback) empty = cursor.mount(fallback);
+    } else {
+      cursor.expect(token === '', `#each has ${items.length} rows, the server rendered the fallback`);
+      for (let i = 0; i < items.length; i++) {
+        const mounted = cursor.mountRow(row, { item: items[i], index: i });
+        if (byKey) {
+          mounted.key = key(items[i], i);
+          byKey.set(mounted.key, mounted);
+        }
+        rows.push(mounted);
+      }
+    }
+    anchor = cursor.close();
+  } else {
+    anchor = cursor.comment();
+    reconcile(undefined, true);
+  }
+  const block = {
+    p(dirty) {
+      if (block.isDone()) return;
+      if (!changed || changed(dirty)) {
+        const indexes = dirtyRows ? dirtyRows() : null;
+        const items = indexes ? Array.from(collection() || []) : null;
+        if (indexes && items.length === rows.length) {
+          const updated = new Set(indexes);
+          for (let i = 0; i < rows.length; i++) {
+            if (updated.has(i)) {
+              rows[i].scope.item = items[i];
+              rows[i].scope.index = i;
+              updateMounted(rows[i], dirty, true);
+            } else {
+              updateMounted(rows[i], dirty, false);
+            }
+          }
+          return;
+        }
+        reconcile(dirty, false);
+        return;
+      }
+      for (const mounted of rows) updateMounted(mounted, dirty, false);
+      updateMounted(empty, dirty, false);
+    },
+    move(before) {
+      for (const mounted of rows) moveRange(mounted.range, before);
+      if (empty) moveRange(empty.range, before);
+      before.parentNode.insertBefore(anchor, before);
+    },
+  };
+  return registerBlock(cursor, block, anchor, (removeDom) => {
+    for (const mounted of rows) {
+      if (removeDom) unmount(mounted);
+      else mounted.owner.release();
+    }
+    if (empty) {
+      if (removeDom) unmount(empty);
+      else empty.owner.release();
+    }
+  });
+}
+
+// ── $$await ──────────────────────────────────────────────────────────────
+// Branch fragments receive { value } or { error }. A settlement of a promise
+// that is no longer current is ignored.
+
+export function $$await(cursor, operand, pending, then, catcher, changed) {
+  let anchor;
+  let promise = null;
+  let current = null;
+  let state = -1;
+
+  const show = (nextState, scope) => {
+    unmount(current);
+    current = null;
+    state = nextState;
+    const fragment = nextState === 0 ? pending : nextState === 1 ? then : catcher;
+    if (fragment) current = mountFragment(fragment, scope, anchor);
+  };
+
+  // drive evaluates the operand; adopted keeps the adopted pending branch.
+  const drive = (adopted) => {
+    const next = Promise.resolve(operand());
+    if (next === promise) return false;
+    promise = next;
+    if (!adopted) show(0, undefined);
+    next.then(
+      (value) => {
+        if (promise !== next || block.isDone()) return;
+        show(1, { value });
+      },
+      (error) => {
+        if (promise !== next || block.isDone()) return;
+        show(2, { error });
+      },
+    );
+    return true;
+  };
+
+  const block = {
+    p(dirty) {
+      if (block.isDone()) return;
+      if ((!changed || changed(dirty)) && drive()) return;
+      updateMounted(current, dirty, false);
+    },
+    move(before) {
+      if (current) moveRange(current.range, before);
+      before.parentNode.insertBefore(anchor, before);
+    },
+    state: () => state,
+  };
+  if (cursor.hydrating) {
+    // The "a" entry holds the branch the server rendered (S-6.11).
+    const token = cursor.open();
+    const entry = cursor.entry('a') || {};
+    cursor.expect(entry.state === token, `#await entry is ${entry.state}, the server range is ${token}`);
+    if (token === 't') {
+      state = 1;
+      if (then) current = cursor.mount(then, { value: entry.value });
+    } else if (token === 'c') {
+      state = 2;
+      if (catcher) current = cursor.mount(catcher, { error: entry.error });
+    } else {
+      state = 0;
+      if (pending) current = cursor.mount(pending);
+      cursor.afterCommit(() => {
+        if (!block.isDone()) drive(true);
+      });
+    }
+    anchor = cursor.close();
+  } else {
+    anchor = cursor.comment();
+  }
+  registerBlock(cursor, block, anchor, (removeDom) => {
+    promise = null;
+    if (!current) return;
+    if (removeDom) unmount(current);
+    else current.owner.release();
+  });
+  if (!cursor.hydrating) drive();
+  return block;
+}
+
+// ── $$component ──────────────────────────────────────────────────────────
+// Mounts a child through its public factory before an anchor, whichever DOM
+// engine compiled it. props() returns the current prop object; events maps
+// component event names to handlers attached to the child's root element;
+// scope is the parent's CSS scope attribute, set on the child's root.
+
+export function $$component(cursor, factory, props, slots, events, changed, scope) {
+  if (factory.$$clientOnly && cursor.hydrating) {
+    // A client-only component (contract §9.2): the server rendered an empty
+    // client range; the component mounts after the root commits (T-9.2b).
+    const main = (inner) => {
+      const block = $$component(inner, factory, props, slots, events, changed, scope);
+      return { p: (dirty) => block.p(dirty) };
+    };
+    return $$client(cursor, main, null);
+  }
+  let anchor;
+  let instance;
+  if (cursor.hydrating) {
+    // The child factory adopts the server DOM inside the component range.
+    cursor.open();
+    instance = withComponentCursor(cursor, () => factory(null, props(), slots || {}));
+    anchor = cursor.close();
+  } else {
+    anchor = cursor.comment();
+    // A block created while a root hydrates (a repaired range) creates its
+    // children too.
+    instance = $$session
+      ? withComponentCursor(null, () => factory(anchor, props(), slots || {}))
+      : factory(anchor, props(), slots || {});
+  }
+  if (scope && instance.el) cursor.init(() => instance.el.setAttribute(scope, ''));
+  if (events) {
+    for (const name of Object.keys(events)) cursor.listen(instance.el, name, events[name]);
+  }
+  const block = {
+    instance,
+    p(dirty) {
+      if (block.isDone()) return;
+      // A child without settable state exposes no set().
+      if ((!changed || changed(dirty)) && instance.set) instance.set(props());
+    },
+    move(before) {
+      before.parentNode.insertBefore(instance.el, before);
+      before.parentNode.insertBefore(anchor, before);
+    },
+  };
+  // A release without DOM removal (abandon, B-3.4) keeps the child's DOM.
+  return registerBlock(cursor, block, anchor, (removeDom) => {
+    if (removeDom || !instance.abandon) instance.destroy();
+    else instance.abandon();
+  });
+}
+
+// ── Slots ────────────────────────────────────────────────────────────────
+// Slots use the component protocol: a slot is a function returning a
+// DocumentFragment with the slot content. The parent
+// owns the content: it is built on the first call, updated by the parent,
+// and the same nodes are returned when the child opens the slot again.
+
+// $$slotFactory builds slot content from a parent fragment. The content is
+// owned by the parent's current owner and updated through `live`, a set the
+// parent fragment walks on every update (B-3.7).
+export function $$slotFactory(cursor, live, fragment) {
+  let range = null;
+  let nodes = null;
+  const open = () => {
+    const container = document.createDocumentFragment();
+    if (range) {
+      // Reopen: move the content back. If a child removed the nodes one by
+      // one, the range chain is broken; fall back to the last snapshot.
+      let current = rangeNodes(range);
+      if (current[current.length - 1] !== range.end) current = nodes;
+      for (const node of current) container.appendChild(node);
+      nodes = current;
+      return container;
+    }
+    const owner = $$owner(cursor.owner);
+    const handle = fragment(createCursor(container, null, owner));
+    if (handle && handle.p) {
+      live.add(handle);
+      owner.add(() => live.delete(handle));
+    }
+    const start = document.createComment('');
+    const end = document.createComment('');
+    container.insertBefore(start, container.firstChild);
+    container.appendChild(end);
+    range = { start, end };
+    nodes = [...container.childNodes];
+    return container;
+  };
+  // adopt hydrates the content where the server rendered it, inside the
+  // child's slot range; reopening returns the adopted nodes.
+  open.adopt = (target) => {
+    const owner = $$owner(cursor.owner);
+    const mounted = target.mount(fragment, undefined, owner);
+    if (mounted.handle && mounted.handle.p) {
+      live.add(mounted.handle);
+      owner.add(() => live.delete(mounted.handle));
+    }
+    range = mounted.range || { start: null, end: null };
+    nodes = rangeNodes(mounted.range);
+    return mounted.range;
+  };
+  return open;
+}
+
+// $$slot opens slot content provided by the parent (from either engine) or
+// mounts the child's own fallback. On release the parent's content is parked
+// in a detached fragment rather than destroyed, so the parent can reopen it.
+export function $$slot(cursor, factory, fallback) {
+  let anchor;
+  let first = null;
+  let last = null;
+  let current = null;
+  if (cursor.hydrating) {
+    cursor.open();
+    if (factory) {
+      cursor.expect(typeof factory.adopt === 'function', 'slot content without an adopt() method cannot be hydrated');
+      const adopted = factory.adopt ? factory.adopt(cursor) : null;
+      if (adopted) {
+        first = adopted.start;
+        last = adopted.end;
+      }
+    } else if (fallback) {
+      current = cursor.mount(fallback);
+    }
+    anchor = cursor.close();
+  } else {
+    anchor = cursor.comment();
+    const content = factory ? factory() : null;
+    if (content && content.firstChild) {
+      first = content.firstChild;
+      last = content.lastChild;
+      anchor.parentNode.insertBefore(content, anchor);
+    } else if (fallback) {
+      current = mountFragment(fallback, undefined, anchor);
+    }
+  }
+  const park = () => {
+    if (!first) return;
+    const holder = document.createDocumentFragment();
+    for (let node = first; node;) {
+      const next = node.nextSibling;
+      holder.appendChild(node);
+      if (node === last) break;
+      node = next;
+    }
+    first = last = null;
+  };
+  const block = {
+    p(dirty) {
+      // Parent content is updated by its parent; only the child's fallback
+      // depends on the child's state.
+      if (!block.isDone()) updateMounted(current, dirty, false);
+    },
+    move(before) {
+      if (first) {
+        for (let node = first; node;) {
+          const next = node.nextSibling;
+          before.parentNode.insertBefore(node, before);
+          if (node === last) break;
+          node = next;
+        }
+      }
+      if (current) moveRange(current.range, before);
+      before.parentNode.insertBefore(anchor, before);
+    },
+  };
+  return registerBlock(cursor, block, anchor, (removeDom) => {
+    park();
+    if (!current) return;
+    if (removeDom) unmount(current);
+    else current.owner.release();
+  });
+}
+
+// ── $$client ─────────────────────────────────────────────────────────────
+// {#client} and client-only components (contract §9). A create cursor (CSR,
+// or a block created after hydration) mounts the main branch directly and
+// ignores the fallback (T-9.1f). Hydration adopts the server range, whose
+// state token is "f" and whose content is the fallback, and after the root
+// commits replaces the fallback with the main branch (T-9.1d). Destroying
+// the owner, or rolling its hydration back, cancels a pending mount
+// (T-9.1e).
+
+export function $$client(cursor, main, fallback) {
+  let anchor;
+  let current = null;
+  let mounted = false;
+  const block = {
+    p(dirty) {
+      if (!block.isDone() && mounted) updateMounted(current, dirty, false);
+    },
+    move(before) {
+      if (current) moveRange(current.range, before);
+      before.parentNode.insertBefore(anchor, before);
+    },
+    state: () => (mounted ? 1 : 0),
+  };
+  if (cursor.hydrating) {
+    const token = cursor.open();
+    cursor.expect(token === "f", `#client range is ${token}, expected f`);
+    if (fallback) current = cursor.mount(fallback);
+    anchor = cursor.close();
+    cursor.afterCommit(() => {
+      if (block.isDone()) return;
+      unmount(current);
+      current = mountFragment(main, undefined, anchor);
+      mounted = true;
+    });
+  } else {
+    anchor = cursor.comment();
+  }
+  registerBlock(cursor, block, anchor, (removeDom) => {
+    if (!current) return;
+    if (removeDom) unmount(current);
+    else current.owner.release();
+  });
+  if (!cursor.hydrating) {
+    current = mountFragment(main, undefined, anchor);
+    mounted = true;
+  }
+  return block;
+}
+
+// $$createCursor exposes the create cursor to the hydration runtime, which
+// remounts a block whose server range does not match (X-7.3).
+export function $$createCursor(parent, before, owner) {
+  return createCursor(parent, before, owner);
+}