@jxsuite/runtime 6.0.2 → 6.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "6.0.2",
+  "version": "6.2.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^5.1.0",
+    "@jxsuite/schema": "^5.3.0",
     "@vue/reactivity": "3.5.44"
   },
   "devDependencies": {

package/src/runtime.ts

@@ -388,6 +388,19 @@ export async function resolve(source: string | JxDocument, ctx?: JxContext): Pro
           `app shell (a single-page fallback), so this path is not served.`,
       );
     }
+    /* A site origin answers `.jxn` as JSON, so only an editing server or a bare file host gets here
+       with KDL, and the parser is the host's to supply: a lazy import here would be inlined by any
+       host that bundles the runtime into one file, and ship the parser to every reader. */
+    if (JXN_URL.test(source) && !contentType.includes("json")) {
+      if (!_documentParser) {
+        throw new Error(
+          `Jx: ${source} is a .jxn file and this page has no parser for it. Serve it from a Jx ` +
+            `site, which answers JSON, or call setDocumentParser(parseJxn) with parseJxn from ` +
+            `@jxsuite/schema/jxn.`,
+        );
+      }
+      return _documentParser(await res.text(), source);
+    }
     /* SAFETY: trust boundary. `resolve` fetches only URLs that name a Jx document (a `Jx()` source,
        an `$elements` entry, a `$switch` case), and the host answered 2xx with a non-HTML body, so
        the JSON is that document; the runtime does not schema-validate documents by design. */
@@ -399,6 +412,28 @@ export async function resolve(source: string | JxDocument, ctx?: JxContext): Pro
 
 // ─── Step 2: Build scope ──────────────────────────────────────────────────────
 
+/** The path part of a URL naming a `.jxn` file. */
+const JXN_URL = /\.jxn(?:[?#]|$)/iu;
+
+/** What reads a `.jxn` file's text. Absent, the runtime refuses one rather than guessing. */
+let _documentParser: ((text: string, source: string) => JxDocument | Promise<JxDocument>) | null =
+  null;
+
+/**
+ * Supply what reads a `.jxn` file, for a host that serves one as its text.
+ *
+ * A compiled site never needs this, and a `$ref` from a Jx site origin does not: both get JSON.
+ * Studio's canvas does, because an editing server answers a file as it is.
+ *
+ * @param parser `parseJxn` from `@jxsuite/schema/jxn`, or a function that loads it first, or null
+ *   to take it away again.
+ */
+export function setDocumentParser(
+  parser: ((text: string, source: string) => JxDocument | Promise<JxDocument>) | null,
+): void {
+  _documentParser = parser;
+}
+
 /** JSON Schema keywords used to identify pure type definitions (Shape 2b). */
 const SCHEMA_KEYWORDS = new Set([
   "type",
@@ -1163,6 +1198,69 @@ export function setTemplateErrorHandler(
   _templateErrorHandler = handler;
 }
 
+/** Warn about a throwing template, once per source. */
+function warnTemplateError(source: string, error: Error): void {
+  if (!reportedTemplates.has(source)) {
+    reportedTemplates.add(source);
+    console.warn(`jx: template ${JSON.stringify(source)} threw:`, error);
+  }
+}
+
+/** Lookups in flight whose answers can make a throwing template valid (§6.1). */
+let pendingLookups = 0;
+
+/** Each binding still throwing while a lookup is in flight, by its `run`, with its latest throw. */
+const heldTemplateErrors = new Map<() => void, { error: Error; source: string }>();
+
+/** Who {@link lookupsSettled} has yet to answer. */
+const lookupWaiters: (() => void)[] = [];
+
+/**
+ * Hold template warnings until `lookup` and every other lookup in flight have settled.
+ *
+ * `lookup` must write its answer to state before it settles: the write re-runs the bindings waiting
+ * on it, so whatever is still held when the last one settles is a template the data did not fix,
+ * and only that is reported. A lookup its own answer starts is counted before this one is
+ * released.
+ *
+ * @param {Promise<void>} lookup - Never rejects: it reports its own failure
+ */
+function holdTemplateErrorsFor(lookup: Promise<void>): void {
+  pendingLookups += 1;
+  void lookup.finally(() => {
+    pendingLookups -= 1;
+    if (pendingLookups === 0) {
+      /* The console, even if a handler was installed meanwhile: these throws happened outside that
+         handler's render, and Studio's render critic would refuse its page for them. */
+      for (const { error, source } of heldTemplateErrors.values()) {
+        warnTemplateError(source, error);
+      }
+      heldTemplateErrors.clear();
+      for (const wake of lookupWaiters.splice(0)) {
+        wake();
+      }
+    }
+  });
+}
+
+/**
+ * Answers once no lookup the runtime started is in flight (embedding.md §5.2).
+ *
+ * A host whose question is whether a document renders awaits this between `buildScope` and
+ * `renderNode`, so its templates read the data rather than the `null` before it. A lookup can hang,
+ * and this waits for it, so bounding the wait is the host's job.
+ *
+ * @returns {Promise<void>}
+ */
+export function lookupsSettled(): Promise<void> {
+  if (pendingLookups === 0) {
+    return Promise.resolve();
+  }
+  return new Promise((wake) => {
+    lookupWaiters.push(wake);
+  });
+}
+
 /**
  * Run a template binding as an effect that survives its expression throwing.
  *
@@ -1172,7 +1270,8 @@ export function setTemplateErrorHandler(
  * and the throw unwound the whole `renderNode` above it: one early read blanked the page. Caught
  * INSIDE the effect, every dependency read before the throw stays tracked, so the binding re-runs
  * on the change that makes it valid. Until then it shows `fallback`'s answer (nothing written, by
- * default), and the error is reported once per source.
+ * default), and the error is reported once per source, after any lookup in flight has settled: a
+ * template that only needed that lookup's answer is not reported at all.
  *
  * @param {string} source - The template, for the report
  * @param {() => void} run - Evaluates the template and writes it
@@ -1182,12 +1281,15 @@ function bindTemplate(source: string, run: () => void, fallback?: () => void): v
   effect(() => {
     try {
       run();
+      heldTemplateErrors.delete(run);
     } catch (error) {
+      const thrown = error instanceof Error ? error : new Error(String(error));
       if (_templateErrorHandler) {
-        _templateErrorHandler(error instanceof Error ? error : new Error(String(error)), source);
-      } else if (!reportedTemplates.has(source)) {
-        reportedTemplates.add(source);
-        console.warn(`jx: template ${JSON.stringify(source)} threw:`, error);
+        _templateErrorHandler(thrown, source);
+      } else if (pendingLookups > 0) {
+        heldTemplateErrors.set(run, { error: thrown, source });
+      } else {
+        warnTemplateError(source, thrown);
       }
       fallback?.();
     }
@@ -1619,7 +1721,15 @@ export const RESERVED_KEYS = new Set([
 ]);
 
 /**
- * A child scope: reads fall through to `parent`, writes land on the child.
+ * A child scope: a `$map` row, or a node carrying `$`-prefixed local bindings or `$props`. Reads
+ * fall through to `parent`, and so does a write to any key the chain above already holds.
+ *
+ * The write is the half a bare `Object.create(parent)` gets wrong, and it gets it wrong silently.
+ * An assignment that reaches the reactive proxy through a prototype chain arrives with the child as
+ * its receiver, so the proxy defines the value on the child and triggers nothing: the handler's
+ * `count += 1` shadows `count`, the root never changes, and the bindings reading it never re-run. A
+ * compiled document assigns to the root directly, so the same document counted there and sat still
+ * here. A value this scope owns is declared with {@link bindLocal}, which is what shadows.
  *
  * @param {JxScope} parent
  * @returns {JxScope}
@@ -1627,7 +1737,35 @@ export const RESERVED_KEYS = new Set([
 function inheritScope(parent: JxScope): JxScope {
   /* SAFETY: `Object.create` is typed `any`, but what it returns is a plain object whose prototype
      is `parent`, so it is keyed by string exactly as the scope it extends is. */
-  return Object.create(parent) as JxScope;
+  const local = Object.create(parent) as JxScope;
+  return new Proxy(local, {
+    set(target, key: string, value: JxScopeValue) {
+      if (Object.hasOwn(target, key)) {
+        return Reflect.set(target, key, value);
+      }
+      if (key in parent) {
+        return Reflect.set(parent, key, value);
+      }
+      bindLocal(target, key, value);
+      return true;
+    },
+  });
+}
+
+/**
+ * Declare `key` on a child scope itself, shadowing whatever its parents hold under that name.
+ *
+ * @param {JxScope} scope
+ * @param {string} key
+ * @param {JxScopeValue} value
+ */
+function bindLocal(scope: JxScope, key: string, value: JxScopeValue): void {
+  Object.defineProperty(scope, key, {
+    configurable: true,
+    enumerable: true,
+    value,
+    writable: true,
+  });
 }
 
 /**
@@ -1752,7 +1890,7 @@ export function renderNode(
       if (localState === state) {
         localState = inheritScope(state);
       }
-      localState[key] = isRefValue(val) ? resolveRef(val.$ref, state) : val;
+      bindLocal(localState, key, isRefValue(val) ? resolveRef(val.$ref, state) : val);
     }
   }
 
@@ -1857,11 +1995,74 @@ export function renderNode(
         el.append(renderNode(child, localState, childOpts));
       }
     }
+  } else if (isTemplateString(kids)) {
+    renderComputedChildren(el, kids, localState, {
+      ...options,
+      _ns: childNs,
+      _path: [...path, "children"],
+    });
   }
 
   return el;
 }
 
+/**
+ * Draw a whole-`children` template, the way the site build's template pass expands one (spec.md
+ * §8.4). This is what an item's or an entry's parsed body looks like to something that renders the
+ * source document rather than the build's output: Studio's Preview, chiefly.
+ *
+ * A result that is not an array draws nothing, because a plain string is not a `children` value.
+ * The children are rendered in a detached scope of their own, replaced when the template's value
+ * changes (a collection that was still loading), and with tracking paused for the reason
+ * {@link renderSwitch} gives: the bindings inside track for themselves.
+ *
+ * @param {Element} el - The element whose children these are
+ * @param {string} template - The `children` value
+ * @param {JxScope} state
+ * @param {JxRenderOptions} options - `_path` is the `children` position of `el`
+ */
+function renderComputedChildren(
+  el: Element,
+  template: string,
+  state: JxScope,
+  options: JxRenderOptions,
+): void {
+  const path = options._path ?? [];
+  let live: EffectScope | null = null;
+  const retire = (): void => {
+    // Detached before it is stopped, for the reason `teardown` in `renderMappedArray` gives.
+    el.replaceChildren();
+    live?.stop();
+    live = null;
+  };
+  bindTemplate(
+    template,
+    () => {
+      const nodes = evaluateValueTemplate(template, state);
+      retire();
+      if (!Array.isArray(nodes)) {
+        return;
+      }
+      const scope = effectScope(true);
+      live = scope;
+      pauseTracking();
+      try {
+        scope.run(() => {
+          /* SAFETY: a children template that yields an array stands for the child list itself, the
+             same reading the site build's template pass gives it. */
+          for (const [i, child] of (nodes as (JxElement | string)[]).entries()) {
+            el.append(renderNode(child, state, { ...options, _path: [...path, i] }));
+          }
+        });
+      } finally {
+        resetTracking();
+      }
+    },
+    retire,
+  );
+  onScopeDispose(() => live?.stop(), true);
+}
+
 // ─── Template string utilities ────────────────────────────────────────────────
 
 /**
@@ -2930,7 +3131,7 @@ function renderMappedArrayInto(
   ): MappedRow => {
     const map = shallowReactive({ index, item });
     const child = inheritScope(state);
-    child.$map = map;
+    bindLocal(child, "$map", map);
     // The flat aliases stay readable by legacy readers, and follow the reactive context.
     Object.defineProperty(child, "$map/item", { enumerable: true, get: () => map.item });
     Object.defineProperty(child, "$map/index", { enumerable: true, get: () => map.index });
@@ -3297,29 +3498,32 @@ export async function resolvePrototype(
             }
           });
 
-          const doFetch = () =>
-            fetch(url, {
-              method: def.method ?? "GET",
-              signal: controller.signal,
-              ...(def.headers && { headers: def.headers }),
-              ...(def.body && {
-                body: isNonNullObject(def.body) ? JSON.stringify(def.body) : def.body,
-              }),
-            })
-              .then((r): Promise<JsonValue> => (r.ok ? r.json() : Promise.reject(r.statusText)))
-              .then((d) => {
-                s.value = d;
+          const doFetch = () => {
+            holdTemplateErrorsFor(
+              fetch(url, {
+                method: def.method ?? "GET",
+                signal: controller.signal,
+                ...(def.headers && { headers: def.headers }),
+                ...(def.body && {
+                  body: isNonNullObject(def.body) ? JSON.stringify(def.body) : def.body,
+                }),
               })
-              .catch((error) => {
-                if (!(error instanceof Error && error.name === "AbortError")) {
-                  s.value = { error: String(error) };
-                }
-              });
+                .then((r): Promise<JsonValue> => (r.ok ? r.json() : Promise.reject(r.statusText)))
+                .then((d) => {
+                  s.value = d;
+                })
+                .catch((error) => {
+                  if (!(error instanceof Error && error.name === "AbortError")) {
+                    s.value = { error: String(error) };
+                  }
+                }),
+            );
+          };
 
           if (debounceMs > 0) {
             debounceTimer = setTimeout(doFetch, debounceMs);
           } else {
-            void doFetch();
+            doFetch();
           }
         });
       }
@@ -3850,24 +4054,25 @@ async function resolveViaDevProxy(def: JxPrototypeDef, state: JxScope, key: stri
 
   // Always wrap in ref for reactivity
   const s: Ref<JxScopeValue> = ref(null);
+  const resolveInto = (resolvedConfig: JxScope) => {
+    holdTemplateErrorsFor(
+      doResolve(resolvedConfig)
+        .then((value) => {
+          s.value = value;
+        })
+        .catch((error) => console.error("Jx dev proxy:", error)),
+    );
+  };
   if (hasTemplates) {
     effect(() => {
       const resolvedConfig: JxScope = {};
       for (const [k, v] of Object.entries(config)) {
         resolvedConfig[k] = isTemplateString(v) ? evaluateTemplate(v, state) : v;
       }
-      doResolve(resolvedConfig)
-        .then((value) => {
-          s.value = value;
-        })
-        .catch((error) => console.error("Jx dev proxy:", error));
+      resolveInto(resolvedConfig);
     });
   } else {
-    doResolve(config)
-      .then((value) => {
-        s.value = value;
-      })
-      .catch((error) => console.error("Jx dev proxy:", error));
+    resolveInto(config);
   }
   return s;
 }
@@ -3900,19 +4105,21 @@ function latestServerCall(
     const n = seq;
     /* The executor runs before the constructor returns, so the call still starts synchronously,
        and a throw inside it rejects this promise instead of escaping to the caller. */
-    new Promise<JsonValue>((settle) => {
-      settle(invoke(args));
-    })
-      .then((result) => {
-        if (n === seq) {
-          s.value = result;
-        }
+    holdTemplateErrorsFor(
+      new Promise<JsonValue>((settle) => {
+        settle(invoke(args));
       })
-      .catch((error) => {
-        if (n === seq) {
-          console.error(label, error);
-        }
-      });
+        .then((result) => {
+          if (n === seq) {
+            s.value = result;
+          }
+        })
+        .catch((error) => {
+          if (n === seq) {
+            console.error(label, error);
+          }
+        }),
+    );
   };
 }
 
@@ -4281,7 +4488,7 @@ function mergeProps(def: JxElement, parentState: JxScope): JxScope {
     if (refusePrivateProp(k, "$props")) {
       continue;
     }
-    child[k] = isRefValue(v) ? resolveRef(v.$ref, parentState) : v;
+    bindLocal(child, k, isRefValue(v) ? resolveRef(v.$ref, parentState) : v);
   }
   return child;
 }