@jxsuite/runtime 6.1.0 → 6.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "6.1.0",
+  "version": "6.2.1",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^5.2.0",
+    "@jxsuite/schema": "^5.4.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",
@@ -1686,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}
@@ -1694,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,
+  });
 }
 
 /**
@@ -1819,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);
     }
   }
 
@@ -3060,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 });
@@ -4417,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;
 }