@opentf/web 0.7.0 → 0.9.0

package/core/signals.js

@@ -15,6 +15,8 @@ import { reportError } from "./errors.js";
 
 /** The consumer (effect or computed) currently executing, if any. */
 let activeConsumer = null;
+/** Disposer collector of the innermost `scope()` currently building, if any. */
+let activeScope = null;
 /** Depth of nested `batch()` calls; effects flush when this returns to 0. */
 let batchDepth = 0;
 /** Re-entrancy guard for the flush loop. */
@@ -149,6 +151,36 @@ export function computed(fn) {
   };
 }
 
+/**
+ * Collect ownership of the effects created while `fn` runs. Returns
+ * `{ result, dispose }`: `dispose()` stops every effect `fn` created (including
+ * ones created in nested calls, unless an inner `scope()` claimed them first).
+ *
+ * This is how dynamic regions own their bindings: a keyed-list item, a
+ * conditional branch, or a mounted page builds its DOM inside a scope, and
+ * evicting/swapping/unmounting disposes the scope — otherwise the bindings'
+ * effects would stay subscribed to their signals forever (a leak that also
+ * makes every later write pay for dead subscribers).
+ */
+export function scope(fn) {
+  const disposers = [];
+  const prev = activeScope;
+  activeScope = disposers;
+  let result;
+  try {
+    result = fn();
+  } finally {
+    activeScope = prev;
+  }
+  return {
+    result,
+    dispose() {
+      for (const d of disposers) d();
+      disposers.length = 0;
+    },
+  };
+}
+
 /**
  * Run `fn` immediately, tracking the signals it reads, and re-run it whenever
  * any of them change. `fn` may return a cleanup function, which runs before the
@@ -166,22 +198,31 @@ export function effect(fn) {
       runCleanup(node);
       clearSources(node);
       const prev = activeConsumer;
+      const prevScope = activeScope;
+      // Effects created during a run belong to whoever the run's body says they
+      // do (an explicit inner scope()), never to whatever scope happens to be
+      // ambient — a flush-time re-run must not donate its children to an
+      // unrelated scope that was open when the write occurred.
       activeConsumer = node;
+      activeScope = null;
       try {
         const result = node.fn();
         if (typeof result === "function") node.cleanup = result;
       } finally {
         activeConsumer = prev;
+        activeScope = prevScope;
       }
     },
   };
   node.run();
-  return function dispose() {
+  const dispose = function dispose() {
     if (node.disposed) return;
     node.disposed = true;
     runCleanup(node);
     clearSources(node);
   };
+  if (activeScope) activeScope.push(dispose);
+  return dispose;
 }
 
 function runCleanup(node) {

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@opentf/web",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "The native-first OTF Web runtime — signal-based reactivity and zero-VDOM DOM operations, paired with the IR-based compiler.",
   "type": "module",
   "exports": {
     ".": "./index.js",
     "./signals": "./core/signals.js",
     "./runtime": "./runtime/index.js",
-    "./server": "./server/index.js"
+    "./server": {
+      "types": "./server/index.d.ts",
+      "default": "./server/index.js"
+    },
+    "./server/adapters/node": {
+      "types": "./server/adapters/node.d.ts",
+      "default": "./server/adapters/node.js"
+    }
   },
   "files": [
     "index.js",

package/runtime/dom.js

@@ -2,7 +2,7 @@
 // also back runtime-driven updates (reactive text/attributes). No virtual DOM,
 // no diffing — just direct, fine-grained DOM writes wired to signals.
 
-import { effect, signal } from "../core/signals.js";
+import { effect, scope, signal } from "../core/signals.js";
 import { claimRegionEnd, claimRegionStart } from "./hydrate.js";
 
 // Attribute names that must be assigned as JS properties (not setAttribute) for
@@ -147,6 +147,26 @@ export function setAttr(el, name, value) {
  * component picks it up from `getAttribute` when it upgrades.
  */
 export function setProp(el, name, value) {
+  // A component prop must land as a *property* (carrying the rich value), never a
+  // stringified attribute. A server-parsed custom element that a parent's adopt walk
+  // reaches while it is still inert — its own `customElements.define`-driven upgrade
+  // hasn't run yet (synchronous upgrades fire in document order, so a parent upgrades
+  // and runs this before its later-in-DOM children) — has no accessors, so `name in el`
+  // is false. Falling back to `setAttr` would stringify an object to "[object Object]"
+  // and, via `attributeChangedCallback`, clobber the child's payload-hydrated signal —
+  // flipping conditional branches and desyncing the adopt walk. Force the pending upgrade
+  // first so the property setter exists; it's a no-op for already-upgraded or non-custom
+  // elements. (A client CSR build creates already-upgraded instances, so this never fires
+  // there.)
+  if (
+    !(name in el) &&
+    el.tagName &&
+    el.tagName.includes("-") &&
+    typeof customElements !== "undefined" &&
+    customElements.get(el.tagName.toLowerCase())
+  ) {
+    customElements.upgrade(el);
+  }
   if (name in el) el[name] = value;
   else setAttr(el, name, value);
 }
@@ -269,32 +289,47 @@ export function bindChild(anchor, fn) {
  */
 export function hydrateChild(cur, adoptFn, buildFn) {
   claimRegionStart(cur);
-  const adopted = toNodes(adoptFn(cur));
+  // Adopt inside a scope so the adopted branch owns its bindings' effects; the
+  // region disposes it when a reactive change swaps the branch out.
+  const adoptedScope = scope(() => toNodes(adoptFn(cur)));
   const anchor = claimRegionEnd(cur);
   // Seed with the adopted nodes and skip the first effect run's DOM write: the branch is
   // already in place. The first run still evaluates `buildFn` to subscribe to its reactive
   // deps (the built nodes are discarded); from the second run on it swaps normally.
-  return childEffect(anchor, buildFn, adopted, true);
+  return childEffect(anchor, buildFn, adoptedScope.result, true, adoptedScope);
 }
 
 /** The child-region effect shared by {@link bindChild} (empty seed, no skip) and
  * {@link hydrateChild} (seeded with adopted nodes, first DOM write skipped). On each run
- * the previous nodes are replaced with the new ones, inserted before `anchor`. */
-function childEffect(anchor, fn, current, skipFirst) {
+ * the previous nodes are replaced with the new ones, inserted before `anchor`; the
+ * previous branch's scope is disposed so its bindings' effects don't outlive it. */
+function childEffect(anchor, fn, current, skipFirst, currentScope = null) {
   let first = skipFirst;
-  return effect(() => {
-    const next = toNodes(fn());
+  const disposeEffect = effect(() => {
+    // Build in a scope: the branch's nested bindings (text/attr/list effects)
+    // belong to this run and are disposed when the branch is replaced.
+    const built = scope(() => toNodes(fn()));
     if (first) {
       first = false;
-      return; // hydration: keep the adopted DOM on first paint (subscribe only)
+      // Hydration first run subscribes the region effect only; the discarded
+      // build's own effects must not stay live alongside the adopted branch.
+      built.dispose();
+      return; // keep the adopted DOM on first paint
     }
+    const next = built.result;
     const host = anchor.parentNode;
     for (const n of current) {
       if (n.parentNode === host) host.removeChild(n);
     }
     if (host) for (const n of next) host.insertBefore(n, anchor);
+    if (currentScope) currentScope.dispose();
+    currentScope = built;
     current = next;
   });
+  return () => {
+    disposeEffect();
+    if (currentScope) currentScope.dispose();
+  };
 }
 
 /**
@@ -333,8 +368,10 @@ export function hydrateList(cur, sourceFn, adoptItem, renderItem, keyFn) {
     const item = items[index];
     const key = keyFn ? keyFn(item, index) : index;
     const sig = signal(item);
-    const node = adoptItem(cur, sig, index); // claims one item subtree off `cur`
-    cache.set(key, { sig, node });
+    // Adopt inside a scope so the item owns its bindings' effects; eviction
+    // disposes them (same ownership as CSR-built items in reconcileList).
+    const s = scope(() => adoptItem(cur, sig, index)); // claims one item subtree off `cur`
+    cache.set(key, { sig, node: s.result, dispose: s.dispose });
     prevKeys.push(key);
   }
   const anchor = claimRegionEnd(cur);
@@ -350,7 +387,7 @@ export function hydrateList(cur, sourceFn, adoptItem, renderItem, keyFn) {
  * order) carry reconciliation state across runs. Returns the effect disposer.
  */
 function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
-  return effect(() => {
+  const disposeEffect = effect(() => {
     const data = sourceFn();
     const items = Array.isArray(data) ? data : [];
     const next = new Map();
@@ -373,7 +410,12 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
         prevIndex[index] = prevPos.has(key) ? prevPos.get(key) : -1;
       } else {
         const sig = signal(item);
-        entry = { sig, node: renderItem(sig, index) };
+        // Build inside a scope: the item owns its bindings' effects, so
+        // evicting it detaches them from shared signals (e.g. a selection
+        // signal every row's class reads). Without this every discarded row
+        // leaves a zombie effect that all later writes keep re-running.
+        const s = scope(() => renderItem(sig, index));
+        entry = { sig, node: s.result, dispose: s.dispose };
         prevIndex[index] = -1;
       }
       next.set(key, entry);
@@ -381,8 +423,9 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
       nodes[index] = entry.node;
     }
 
-    // Remove nodes whose keys disappeared.
+    // Remove nodes whose keys disappeared, and dispose their bindings.
     for (const entry of cache.values()) {
+      if (entry.dispose) entry.dispose();
       if (entry.node.parentNode) entry.node.parentNode.removeChild(entry.node);
     }
     cache = next;
@@ -403,6 +446,13 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
       if (nodes[i].nextSibling !== ref) host.insertBefore(nodes[i], ref);
     }
   });
+  return () => {
+    disposeEffect();
+    for (const entry of cache.values()) {
+      if (entry.dispose) entry.dispose();
+    }
+    cache.clear();
+  };
 }
 
 /**

package/runtime/hydrate.js

@@ -58,13 +58,55 @@ export class HydrationMismatch extends Error {
 // `firstChild`, so the structural test alone can't tell "adopt the server DOM" from
 // "build and slot these children" (it mis-adopts on plain SPA navigation). The flag is
 // the unambiguous signal — it is only ever set during the one-shot first-paint pass.
-let _hydrating = false;
+//
+// Why it initializes from the DOM sentinel, not `false`: a custom element upgrades — and
+// its `connectedCallback` runs the build-vs-adopt switch — the instant its class is
+// `customElements.define`d. Framework components imported *eagerly* by the app entry
+// (e.g. `<Link>` from `@opentf/web`) are therefore defined and upgraded during the entry
+// bundle's evaluation, **before** `mountApp` runs `beginHydration()`. If the flag were
+// still `false` then, every server-rendered `<web-link>` would take the *build* arm —
+// re-wrapping the server subtree it should have adopted (a silent `<a><a>` double-build)
+// — long before the router ever starts hydrating. So the flag is seeded synchronously
+// at module load from the server sentinel (`[data-otfw-hydrate]`, stamped only when the
+// page shipped adoptable server markup): the deferred entry module evaluates after the
+// HTML is parsed, so the sentinel is present, and this module is a transitive dependency
+// of every component (via the runtime), so it evaluates before any component's `define`.
+// `mountApp` still brackets the pass with `beginHydration`/`endHydration`, and clears the
+// flag when it decides *not* to hydrate (no sentinel / empty root), so a CSR mount and
+// every subsequent SPA navigation build fresh.
+let _hydrating =
+  typeof document !== "undefined" && !!document.querySelector("[data-otfw-hydrate]");
 
 /** Is the client mid-hydration right now? */
 export function isHydrating() {
   return _hydrating;
 }
 
+/**
+ * Run `fn` with the hydration flag *cleared*, restoring the prior value (nesting-safe).
+ *
+ * The build/adopt decision hangs on one module-global flag, but the invariant it must
+ * encode is narrower: `isHydrating()` may be true only while the DOM being processed is
+ * the server's. The moment a component builds fresh DOM — because its view isn't
+ * adoptable (`RebuildIfServerChildren`), or its adopt hit a mismatch and it's recovering,
+ * or it's a nested build — that fresh subtree is *not* server-rendered. Its child custom
+ * elements upgrade synchronously during `appendChild` inside this build, and if they still
+ * saw `isHydrating()` true they'd try to *adopt* content their parent just `createElement`'d
+ * → a guaranteed `HydrationMismatch` cascade (a non-adoptable layout would tear the whole
+ * page's islands into rebuild-storms). Bracketing every build path with this makes the
+ * children build too, matching the DOM they're actually handed. Synchronous only — builds
+ * never await — so a plain global save/restore is correct even when builds nest.
+ */
+export function runBuild(fn) {
+  const prev = _hydrating;
+  _hydrating = false;
+  try {
+    return fn();
+  } finally {
+    _hydrating = prev;
+  }
+}
+
 /** Run `fn` with the hydration flag set, restoring the prior value (nesting-safe).
  * Synchronous only — for the async first-paint pass use {@link beginHydration} /
  * {@link endHydration}, which span the route module's `import()`. */

package/runtime/index.js

@@ -14,6 +14,8 @@ export * from "./mount.js";
 export * from "./hydrate.js";
 export * from "./lifecycle.js";
 export * from "./router.js";
+export * from "./route-data.js";
+export * from "./resource.js";
 export * from "./context.js";
 export * from "./error-boundary.js";
 export * from "./portal.js";

package/runtime/mount.js

@@ -2,6 +2,7 @@
 // SPEC §2.2). Components compile to Custom Elements and mount via the DOM.
 
 import { reportError } from "../core/errors.js";
+import { scope } from "../core/signals.js";
 
 /**
  * Mount a view into `target`. `view` is either a factory function returning a
@@ -11,9 +12,21 @@ import { reportError } from "../core/errors.js";
  * built from `onMount`/`onCleanup`. After insertion we run the `onMount` callbacks,
  * collecting any returned disposer into `cleanups` so a caller (e.g. the router)
  * can tear the page down on navigation.
+ *
+ * A factory build runs inside a reactive `scope`, and the scope's disposer joins
+ * the cleanups: teardown (router navigation) stops every binding effect the page
+ * created, so a replaced page's subscriptions don't outlive it.
  */
 export function mount(view, target) {
-  const node = typeof view === "function" ? view() : view;
+  let node;
+  if (typeof view === "function") {
+    const s = scope(view);
+    node = s.result;
+    const lc = (node.__lifecycle ??= { mounts: [], cleanups: [] });
+    lc.cleanups.push(s.dispose);
+  } else {
+    node = view;
+  }
   target.appendChild(node);
   runMount(node);
   return node;

package/runtime/resource.js

@@ -0,0 +1,139 @@
+// `resource()` — the client-side async-data primitive (SPEC §7.4, docs/DATA.md).
+// Components are strictly synchronous (SPEC §5.5), so async data lives *next to*
+// the view: a resource wraps a fetcher in signals and the view renders its
+// reactive `loading` / `error` / `data` states:
+//
+//   const users = resource(() => fetch("/api/users").then((r) => r.json()));
+//   // in JSX: {users.loading ? <Spinner /> : users.data.map(...)}
+//
+// With a reactive source, the fetch re-runs whenever the source changes, and a
+// `null`/`false` source pauses it (conditional fetching):
+//
+//   const user = resource(() => router.params.id, (id, { signal }) =>
+//     fetch(`/api/users/${id}`, { signal }).then((r) => r.json()));
+//
+// Staleness: each run bumps a token and aborts the previous run's AbortController
+// (passed to the fetcher as `{ signal }`), so an out-of-order resolution can never
+// overwrite newer data — even for fetchers that ignore the signal.
+//
+// Server (SSG/SSR): no effect is created and nothing is fetched — `loading` stays
+// `true`, so the prerendered HTML shows the loading branch. That is exactly what
+// the client's first paint renders before its own fetch resolves, keeping
+// hydration adoption aligned.
+
+import { batch, effect, signal, untracked } from "../core/signals.js";
+
+// Test override: bun tests run under happy-dom (a `document` always exists), so
+// server behavior is opted into explicitly.
+let serverOverride = null;
+
+/** Force server (true) / client (false) behavior for new resources — tests only. */
+export function __setResourceServer(v) {
+  serverOverride = v;
+}
+
+const isServer = () => serverOverride ?? typeof document === "undefined";
+
+/**
+ * Create a resource. Two call shapes:
+ *
+ *   resource(fetcher, options?)          — fetch once (and on refetch())
+ *   resource(source, fetcher, options?)  — re-fetch when the reactive `source`
+ *                                          changes; `null`/`false` pauses
+ *
+ * @param {Function} source  reactive source read inside the tracking effect; its
+ *        value is passed to the fetcher.
+ * @param {Function} fetcher  `(sourceValue, { signal }) => data | Promise<data>`.
+ * @param {{ initial?: unknown }} [options]  `initial` seeds `data` before the
+ *        first resolution.
+ * @returns {{ data: unknown, loading: boolean, error: unknown,
+ *             refetch: () => Promise<unknown> | undefined }}  reactive getters —
+ *        read them inside bindings/effects to subscribe.
+ */
+export function resource(source, fetcher, options = {}) {
+  if (typeof fetcher !== "function") {
+    options = fetcher ?? {};
+    fetcher = source;
+    source = null;
+  }
+  const src = typeof source === "function" ? source : () => true;
+  const data = signal(options.initial);
+  const error = signal(undefined);
+  const loading = signal(true); // a fetch is intended; the server leaves it true
+  let token = 0;
+  let controller = null;
+
+  function run(value) {
+    controller?.abort();
+    // Captured per-run: by the time a superseded run's promise settles, the
+    // module-level `controller` already belongs to a newer run.
+    const c = (controller = typeof AbortController !== "undefined" ? new AbortController() : null);
+    const t = ++token;
+    batch(() => {
+      loading.value = true;
+      error.value = undefined;
+    });
+    // The async IIFE starts the fetcher *synchronously* (no wasted microtask)
+    // while converting a synchronous throw into a rejection.
+    return (async () => fetcher(value, { signal: c?.signal }))()
+      .then(
+        (v) => {
+          if (t !== token) return; // superseded — a newer run owns the signals
+          batch(() => {
+            data.value = v;
+            loading.value = false;
+          });
+          return v;
+        },
+        (e) => {
+          if (t !== token) return;
+          // Keep the last good `data` (stale-while-error); only `error` flips.
+          batch(() => {
+            error.value = e;
+            loading.value = false;
+          });
+        },
+      );
+  }
+
+  if (!isServer()) {
+    effect(() => {
+      const value = src(); // the effect's ONLY tracked read
+      if (value == null || value === false) {
+        // Paused: cancel anything in flight and settle as "not loading".
+        untracked(() => {
+          token++;
+          controller?.abort();
+          controller = null;
+          loading.value = false;
+        });
+        return;
+      }
+      untracked(() => run(value));
+      // Before a re-run (source changed) and on scope dispose: invalidate + abort,
+      // so a torn-down region's fetch can neither land nor leak a connection.
+      return () => {
+        token++;
+        controller?.abort();
+      };
+    });
+  }
+
+  return {
+    get data() {
+      return data.value;
+    },
+    get loading() {
+      return loading.value;
+    },
+    get error() {
+      return error.value;
+    },
+    /** Re-run the fetcher with the current source value (no-op while paused). */
+    refetch() {
+      const value = untracked(src);
+      if (value == null || value === false) return undefined;
+      return run(value);
+    },
+  };
+}

package/runtime/route-data.js

@@ -0,0 +1,64 @@
+// Route-loader data on the client (docs/DATA.md). A page with a sibling
+// `loader.{js,ts}` gets its data three ways, all converging on `router.data`:
+//
+//   • first paint over server HTML — the payload is inlined as
+//     `<script type="application/json" id="__otfw_data">` and read here;
+//   • SPA navigation — fetched from `<path>/__data.json` (the same URL a static
+//     host serves as a literal file written at SSG time, and the serve/dev
+//     servers answer dynamically);
+//   • dev/CSR first load — the same fetch, since there is no server markup.
+//
+// The endpoint returns the raw loader JSON (no envelope): 404 means "no data for
+// this route" (no loader, or the loader called `notFound()`) and maps to
+// `undefined` so the page renders its empty state.
+
+/** The reserved per-route data filename/URL suffix (`/todos` → `/todos/__data.json`). */
+export const DATA_FILE = "__data.json";
+
+// Match the router's path normalization (a trailing slash must hit the same URL).
+const normalize = (p) => (p || "/").replace(/(.)\/+$/, "$1");
+
+/** The data-endpoint URL for a page path: `"/"` → `/__data.json`,
+ *  `"/todos"` → `/todos/__data.json`, preserving the query string. */
+export function dataUrlFor(pathname, search = "") {
+  const path = normalize(pathname);
+  return (path === "/" ? `/${DATA_FILE}` : `${path}/${DATA_FILE}`) + (search || "");
+}
+
+/**
+ * Fetch a route's loader data. 200 → the parsed JSON; 404 → `undefined` (no
+ * loader / `notFound()`); anything else throws (the router reports it and
+ * commits the navigation with no data).
+ */
+export async function fetchRouteData(pathname, search = "") {
+  const res = await fetch(dataUrlFor(pathname, search));
+  if (res.status === 404) return undefined;
+  if (!res.ok) throw new Error(`route data request for ${pathname} failed (${res.status})`);
+  return res.json();
+}
+
+// The inline first-paint payload, read once and cached (mirrors the island-props
+// payload reader in hydrate.js). `undefined` data serializes to *no script at all*
+// (the toolchain skips injection), so a missing element simply reads as undefined.
+let _read = false;
+let _value;
+
+/** The loader data inlined by the server for the current document, or `undefined`. */
+export function readInlineRouteData() {
+  if (!_read) {
+    _read = true;
+    const el = typeof document !== "undefined" ? document.getElementById("__otfw_data") : null;
+    try {
+      _value = el ? JSON.parse(el.textContent || "null") : undefined;
+    } catch {
+      _value = undefined;
+    }
+  }
+  return _value;
+}
+
+/** Reset the cached inline payload (tests only — a fresh document between cases). */
+export function __resetInlineRouteData() {
+  _read = false;
+  _value = undefined;
+}