@zubra/runtime 0.0.0-stage → 5.0.3

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Mikey Nichols
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @zubra/runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser runtime that compiled Zubra components run on. It is a **polyfill boundary**: everything
+compiled code depends on is shaped like a proposed web platform primitive, so when the platform
+ships one, this package deletes code instead of components being rewritten.
+
+| Module | Shaped like | Status |
+|---|---|---|
+| `src/signal.js` | [TC39 Signals](https://github.com/tc39/proposal-signals) (`Signal.State`, `Signal.Computed`, `Signal.subtle`) | Done. Uses native `globalThis.Signal` when present, otherwise `src/signal-impl.js` |
+| `src/effect.js` | Not a proposal — the Signals proposal leaves effects to libraries. Built only on `Signal.subtle.Watcher` and microtasks | Done |
+| `src/element.js` parts (`walk`/`bind`) | [DOM Parts](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/DOM-Parts.md): a template plus the locations of its dynamic parts | Done: text, attributes, properties, events, `zb-if`/`zb-each` regions (keyed rows move with `moveBefore()`), slots; paths count elements and comments only, and a region counts once |
+| `src/element.js` `define` | Custom elements, light DOM by default, shadow opt-in | Done: signal-backed props, typed attributes, pre-upgrade capture, hydration without re-rendering, pause on detach |
+| `src/element.js` hooks | Plain functions (see the project's hooks decision) | `state`, `from`, `computed`, `watch`, `onMount`, `onUnmount`, `id`, `props`, `host`, `emit`, `hydrated` |
+| `src/element.js` slots | Light-DOM slotting with the host's child methods routed to the slots, so frameworks can keep managing the children; native `<slot>` in shadow DOM | Done |
+| `src/react.js`, `src/vue.js` | Adapters: an element as a React (18, 19) or Vue 3 component | Done |
+| `types/` | TypeScript declarations for every entry point | Done |
+| `src/element.js` forms | Form-associated custom elements (`ElementInternals`) | `formValue`, `validity`, `onFormReset`, `onFormRestore`, `onFormDisabled`; native control API on the element |
+| `src/element.js` context | [Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md) (`context-request` / `context-provider` events) | `createContext`, `provide`, `inject`; interoperates with any protocol implementation |
+
+## The production build
+
+`dist/production/` is the same modules without hot reloading (the code between `// @hot` and
+`// @hot-end` in `src/`). Bundlers pick it through the `production` export condition (Vite and
+webpack do in production builds), and `@zubra/server` serves it when `NODE_ENV` is `production`.
+It's generated by `npm run build:production` and checked in; `npm run test:tools` fails if it's
+out of date, and measures both builds against their size budgets (13.5 KB and 13 KB gzipped).
+
+## Signals
+
+`src/signal-impl.js` is an independent implementation of the proposed API. It is held to the
+proposal's reference polyfill, [`signal-polyfill`](https://github.com/proposal-signals/signal-polyfill),
+by **differential tests**: each scenario runs against both, and the logs must be identical,
+including values, recompute counts, the order watchers are notified, the order `watched` and
+`unwatched` hooks fire, pending lists and introspection.
+
+- 26 hand-written scenarios: caching, equality cut-off, glitch-free diamonds, dynamic
+  dependencies, cached errors, cycles, `equals` semantics, watcher re-arming, frozen-graph rules,
+  liveness hooks, introspection, receiver checks.
+- 300 seeded random graphs (states, computeds with data-dependent branches and errors, two
+  watchers, random reads, writes, watch/unwatch). A one-off run of 5,000 seeds also matched.
+
+### Deliberate differences from the reference polyfill
+
+Each one only affects programs that break a rule the proposal states, so correct programs
+behave the same on both. All are tested in `test/signal.test.js`.
+
+1. **Reads and writes inside `watched`/`unwatched` hooks throw.** The proposal says hooks run
+   with the graph frozen; the reference doesn't enforce it, and a hook that reads its own signal
+   recurses until the stack overflows.
+2. **Reading a computed inside a Watcher's `notify` throws before recomputing.** The reference
+   starts recomputing first, so the computed caches the "read during notification" error and
+   keeps throwing it after the notification is over.
+3. **`new Signal.Computed(x)` requires a function** (TypeError), instead of failing on first read.
+
+## Effects
+
+```js
+import { Signal } from '@zubra/runtime/signal';
+import { effect, scope, flush, tick } from '@zubra/runtime/effect';
+
+const count = new Signal.State(0);
+const dispose = effect(() => {
+  console.log(count.get());
+  return () => { /* cleanup before the next run, and on dispose */ };
+});
+count.set(1); count.set(2);   // one re-run, in a microtask
+await tick();
+```
+
+- **Batched**: any number of writes in a task cause one re-run per effect.
+- **Owned**: an effect created inside another effect (or a `scope`) is disposed when its owner
+  re-runs or is disposed. A child's reads never become its parent's dependencies.
+- **Ordered**: parents re-run before children; a child replaced by its parent never runs.
+- **Isolated**: an error in a re-run is reported (`reportError`, else `console.error`) and the
+  other effects still run. Effects that keep re-triggering each other are stopped after 100
+  rounds.
+- **Pausable**: `scope.pause()` (an element left the DOM) unwatches everything inside it, so
+  long-lived signals hold no reference to it; `scope.resume()` re-runs only the effects whose
+  inputs changed while paused. This is wc.js v4's leak fix, now provided by `Signal.Computed`'s
+  own version checks.
+
+A write to a signal an effect has already read in the same run does not re-run it (same as a
+computed in the reference). Derive the value instead of writing it back.
+
+## Tests
+
+```sh
+npm install
+npm test               # Signals, effects (Node only)
+npm run test:browser   # compiled components in Chromium; needs Rust and Playwright
+```
+
+The browser tests compile real `.zb` files with the Rust CLI and check fresh rendering, batched updates, pre-upgrade properties, hydration that keeps every server node, anchored text, mismatched markup, a `state()` + `onclick` counter, mount/unmount hooks across a detach and re-attach, and runtime URL blocking; and for regions (`regions.test.js`): lists growing, shrinking and updating rows in place, branches switching (including a list inside a hidden branch), a branch not re-rendering when its test re-runs to the same result, per-row updates that leave other rows' nodes alone, text directly inside rows, and hydration of server-rendered branches, rows and else branches; and for keyed lists (`keyed.test.js`): reordering that keeps each row's element, typed input and focus, middle inserts and removals, in-place updates under the same key, runtime duplicate keys, and hydrated keyed lists; and for slots (`slots.test.js`): light-DOM projection that moves the element's own nodes, live fallbacks, slotted content surviving an `zb-if` toggle, unknown slot names, hydration of supplied content and fallbacks, and native slots in shadow components, fresh and from a declarative shadow root; and for context (`context.test.js`): nearest-provider answers, nested providers, consumers defined before providers, late provider announcements, moving and removing consumers (including unsubscribing), interop with bare-protocol providers and consumers in both directions, `id()`, and the error for hooks called outside setup; and for forms (`forms.test.js`): submitted values under `name`, `form` and `labels`, reset, validation blocking submission with `:invalid`/`:valid`, disabled fieldsets (including starting and being inserted inside one), restore, and the error for form hooks without `form-associated`. They were mutation-checked: each of twenty-seven deliberate runtime breakages (always rewriting text, never hydrating, not pausing on disconnect, skipping the runtime URL check, counting text nodes in paths, re-rendering a branch on every test run, letting the list effect own its rows, not stepping over regions in paths, never hydrating rows, recreating rows instead of updating them, ignoring keys, not using `moveBefore`, losing keys on hydrated rows, leaving moved rows with a stale index, forgetting slotted content after first use, treating supplied server content as fallback, never slotting the element's children, not recognizing `[!` as a region, letting context requests bubble past a provider, ignoring late providers, not asking again after a move, not unsubscribing on disconnect, providers not pushing updates, `id()` ignoring the host id, not being form-associated, never clearing validity, ignoring reset) fails at least one test. One guard (a form control disabled before its setup ran) never runs in Chromium and is kept, documented as untested, for engines that order those callbacks differently.
+
+The effect tests were mutation-checked: removing the parent-first sort, the `untrack` around
+child runs, child disposal on re-run, or unwatching on pause each makes at least one test fail.
+
+Later suites cover composition (`composition.test.js`: props passed as values, slotted content from the parent's scope, keyed child components, hydration of nested server markup, other libraries' elements getting properties once defined), events (`events.test.js`: `CustomEvent` shape, cancelable `before…` events, inner same-named events stopped at the host, shadow components' composed events, a parent re-firing a child's event), slots under framework-style DOM calls (`slots.test.js`), and the adapters in real React 19, React 18 and Vue 3 apps (`adapters.test.js`). Each was mutation-checked the same way; mutations that turned out equivalent were removed from the code or documented where they are.

package/dist/production/deep.js

@@ -0,0 +1,88 @@
+// Generated by scripts/build-production.js from src/deep.js: the runtime without hot reloading. 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
+// template (or a computed) reads through the proxy is tracked by its own `Signal.State`, created
+// on first read, and each write through the proxy bumps that property's signal, so only what
+// read the property re-runs. Nested arrays and objects are wrapped lazily, on read. Nothing here
+// is a new runtime concept: it's `Signal.State` per property, over the standard API.
+//
+// What's wrapped: arrays and plain objects (prototype `Object.prototype` or `null`). Class
+// instances, `Map`/`Set`, dates, DOM nodes, functions and promises are left as they are, since a
+// proxy would break their internals. `raw(value)` gives the original object back.
+// (`plan/decisions/deep-reactivity.md`.)
+
+import { Signal } from './signal.js';
+
+const RAW = Symbol('zubra.raw');
+const ITERATE = Symbol('zubra.iterate'); // "the set of keys" (ownKeys, `in`, array length)
+const proxies = new WeakMap(); // raw → proxy
+const signals = new WeakMap(); // raw → Map<key, Signal.State<number>>
+
+const isPlain = (value) => {
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+/** 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)));
+  signal.get();
+}
+
+function trigger(target, key) {
+  const signal = signals.get(target)?.get(key);
+  if (signal) signal.set(signal.get() + 1);
+}
+
+const handler = {
+  get(target, key, receiver) {
+    if (key === RAW) return target;
+    if (typeof key !== 'symbol') track(target, key);
+    return wrap(Reflect.get(target, key, receiver));
+  },
+  has(target, key) {
+    if (typeof key !== 'symbol') track(target, key);
+    return Reflect.has(target, key);
+  },
+  ownKeys(target) {
+    track(target, ITERATE);
+    return Reflect.ownKeys(target);
+  },
+  set(target, key, value, receiver) {
+    value = raw(value);
+    const had = Object.prototype.hasOwnProperty.call(target, key);
+    const before = target[key];
+    const length = Array.isArray(target) ? target.length : -1;
+    const ok = Reflect.set(target, key, value, receiver);
+    if (!had) trigger(target, ITERATE);
+    if (!had || !Object.is(before, value)) trigger(target, key);
+    // Setting an index past the end grows the array without a `length` write.
+    if (length >= 0 && target.length !== length && key !== 'length') trigger(target, 'length');
+    return ok;
+  },
+  deleteProperty(target, key) {
+    const had = Object.prototype.hasOwnProperty.call(target, key);
+    const ok = Reflect.deleteProperty(target, key);
+    if (had) {
+      trigger(target, ITERATE);
+      trigger(target, key);
+    }
+    return ok;
+  },
+};
+
+/** `value` as a reactive proxy, if it's an array or a plain object; otherwise `value`. */
+export function wrap(value) {
+  if (!isPlain(value) || value[RAW]) return value;
+  let proxy = proxies.get(value);
+  if (!proxy) proxies.set(value, (proxy = new Proxy(value, handler)));
+  return proxy;
+}

package/dist/production/effect.js

@@ -0,0 +1,234 @@
+// Generated by scripts/build-production.js from src/effect.js: the runtime without hot reloading. 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.
+// It follows the pattern from the proposal's README (one Watcher, flushed in a microtask) and
+// adds what components need:
+//
+//   effect(fn)        run fn now, re-run it (batched) when what it read changes; returns dispose
+//   scope(fn)         an ownership root: effects created inside belong to it
+//   flush() / tick()  apply pending re-runs now / await them
+//
+// 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.
+//
+// Pausing: a scope can be paused (an element left the DOM) and resumed (it came back). Paused
+// effects are unwatched, so long-lived signals hold no reference to them, but each keeps its
+// cached result and the versions it last saw. On resume it is re-validated and re-runs only if
+// something it depends on changed while it was away — the version check in Signal.Computed does
+// exactly that, so no extra bookkeeping is needed here.
+import { Signal } from './signal.js';
+
+const { untrack } = Signal.subtle;
+const MAX_ROUNDS = 100;
+
+let owner = null;          // the Effect or Scope currently running
+let nextId = 0;
+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(); }
+  }));
+});
+
+// Unwatching is batched: disposing or pausing a subtree (removing a list of 1,000 rows), or
+// anything inside `batch()`, unwatches everything in one pass over the watcher's signals,
+// instead of one pass per effect. Outside a batch it happens at once.
+const unwatching = new Set();
+let batching = 0;
+
+function unwatchLater(computed) {
+  if (batching) unwatching.add(computed);
+  else watcher.unwatch(computed);
+}
+
+/** Run `fn`, unwatching what it disposes or pauses in one pass at the end. */
+export function batch(fn) {
+  batching++;
+  try {
+    return fn();
+  } finally {
+    if (--batching === 0 && unwatching.size) {
+      const all = [...unwatching];
+      unwatching.clear();
+      for (let i = 0; i < all.length; i += 10000) watcher.unwatch(...all.slice(i, i + 10000));
+    }
+  }
+}
+
+/** Watch again (a resumed effect): if its unwatch is still pending, just cancel that. */
+function watchAgain(computed) {
+  if (!unwatching.delete(computed)) watcher.watch(computed);
+}
+
+function report(error) {
+  if (typeof globalThis.reportError === 'function') globalThis.reportError(error);
+  else console.error(error);
+}
+
+class Owner {
+  constructor(parent) {
+    this.parent = parent;
+    this.children = new Set();
+    this.disposed = false;
+    this.paused = false;
+    parent?.children.add(this);
+  }
+
+  disposeChildren() {
+    batch(() => {
+      for (const child of [...this.children]) child.dispose();
+    });
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.disposeChildren();
+    this.parent?.children.delete(this);
+  }
+
+  pause() {
+    if (this.paused || this.disposed) return;
+    this.paused = true;
+    batch(() => {
+      for (const child of [...this.children]) child.pause();
+    });
+  }
+
+  resume() {
+    if (!this.paused || this.disposed) return;
+    this.paused = false;
+    // Children may be replaced while their parent resumes, so iterate a snapshot and skip
+    // anything that was disposed along the way.
+    for (const child of [...this.children]) if (!child.disposed) child.resume();
+  }
+}
+
+class Effect extends Owner {
+  constructor(fn, parent) {
+    super(parent);
+    this.id = ++nextId;
+    this.cleanup = undefined;
+    this.computed = new Signal.Computed(() => {
+      this.disposeChildren();
+      this.runCleanup();
+      const previous = owner;
+      owner = this;
+      try {
+        const result = fn();
+        this.cleanup = typeof result === 'function' ? result : undefined;
+      } finally {
+        owner = previous;
+      }
+    });
+    effectOf.set(this.computed, this);
+    watcher.watch(this.computed);
+  }
+
+  /** Re-validate: re-runs fn only if a dependency changed since the last run. */
+  run() {
+    // untrack: if this effect was created inside another effect, the parent must not end up
+    // depending on whatever the child reads.
+    untrack(() => this.computed.get());
+  }
+
+  runCleanup() {
+    const cleanup = this.cleanup;
+    this.cleanup = undefined;
+    if (cleanup) untrack(cleanup);
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    super.dispose();
+    unwatchLater(this.computed);
+    try { this.runCleanup(); } catch (error) { report(error); }
+  }
+
+  pause() {
+    if (this.paused || this.disposed) return;
+    super.pause();
+    unwatchLater(this.computed);
+  }
+
+  resume() {
+    if (!this.paused || this.disposed) return;
+    this.paused = false;
+    watchAgain(this.computed);
+    try { this.run(); } catch (error) { report(error); }
+    for (const child of [...this.children]) if (!child.disposed) child.resume();
+  }
+}
+
+class Scope extends Owner {
+  run(fn) {
+    const previous = owner;
+    owner = this;
+    try { return fn(); } finally { owner = previous; }
+  }
+}
+
+/**
+ * Run `fn` now and again whenever a signal it read changes. Re-runs are batched: any number of
+ * writes in one task cause one re-run, in a microtask. `fn` may return a cleanup function, which
+ * runs before the next run and on dispose. Errors thrown by re-runs are reported, not thrown, so
+ * one failing effect doesn't stop the others; an error in the first run is thrown to the caller.
+ */
+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();
+}
+
+/**
+ * Create an ownership root and run `fn` inside it. Returns the scope, whose `dispose()`,
+ * `pause()` and `resume()` apply to every effect created within (now or by later `run()` calls).
+ */
+export function scope(fn) {
+  const s = new Scope(owner);
+  if (fn) s.run(fn);
+  return s;
+}
+
+/**
+ * Like `scope`, but owned by nothing and untracked: for something whose life isn't the running
+ * effect's (an element, which lives as long as it's in the document, even when an effect's run
+ * inserted it).
+ */
+export function root(fn) {
+  const s = new Scope(null);
+  if (fn) untrack(() => s.run(fn));
+  return s;
+}
+
+/** Apply all pending re-runs synchronously, parents before children. */
+export function flush() {
+  if (flushing) return;
+  flushing = true;
+  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 (round >= MAX_ROUNDS) {
+        report(new Error('zubra: effects keep re-triggering each other; stopped after 100 rounds'));
+        return;
+      }
+      const effects = pending.map((computed) => effectOf.get(computed)).sort((a, b) => a.id - b.id);
+      for (const e of effects) {
+        if (e.disposed || e.paused) continue;
+        try { e.run(); } catch (error) { report(error); }
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+}
+
+/** Resolves once pending re-runs have been applied. */
+export const tick = () => scheduled ?? Promise.resolve();