@jxsuite/runtime 1.3.1 → 2.0.0

package/src/runtime.ts

@@ -23,7 +23,8 @@ import {
   ref,
   toRaw,
 } from "@vue/reactivity";
-import { evaluateExpression, isMutating } from "./expression.ts";
+import { evaluateExpression, evaluateOperand, isMutating } from "./expression.ts";
+import { readPath } from "./pointer.ts";
 import type { DynamicClass, JxEventHandler, JxPath, JxRenderOptions, JxScope } from "./types.ts";
 import {
   bodyReturnsValue,
@@ -33,13 +34,16 @@ import {
   isJsonObject,
   isMappedArray,
   isNamedFormulaDef,
+  isPrivateStateKey,
   isPrototypeDef,
   isRef as isRefValue,
   isServerFnDef,
+  isTagExpression,
   isTemplateString,
   paramNames,
 } from "@jxsuite/schema/guards";
 import { runStatements } from "./statements.ts";
+import { readCookie, serializeCookie } from "./cookie.ts";
 import type {
   JxAttributeValue,
   JxClassDef,
@@ -170,6 +174,25 @@ export function setSkipServerFunctions(v: boolean) {
   _serverFnConfig.skip = v;
 }
 
+/** @type {{ skip: boolean }} */
+const _autoRequestConfig = { skip: false };
+/**
+ * Set to true to suppress AUTOMATIC `$prototype: "Request"` fetches — the sibling of
+ * {@link setSkipServerFunctions}, and used by Studio for the same reason.
+ *
+ * `buildScope` re-resolves every `state` entry on each full canvas render, so an auto-request
+ * re-issued its HTTP call every time the canvas rebuilt. In edit/design mode that meant authoring
+ * actions — a signal edit, or pressing Enter inside component-wrapped content, both of which force
+ * a full render — fired network requests. Live data belongs to preview and to the deployed site.
+ *
+ * Only non-`manual` requests are gated: a `manual` one fires from an event handler, and edit mode
+ * strips handlers before rendering. The returned ref is unchanged either way — it simply stays at
+ * its initial `null`, which is the same state bindings observe before any fetch resolves.
+ */
+export function setSkipAutoRequests(v: boolean) {
+  _autoRequestConfig.skip = v;
+}
+
 // ─── Dev-proxy auth token (Studio cross-origin canvas) ────────────────────────
 // The Studio canvas iframe is served from a token-gated loopback origin (createProjectServer): its
 // POST /__jx_resolve__ + /__jx_server__ routes 403 without ?token=<rpcToken>. The iframe boot reads
@@ -764,8 +787,18 @@ export function renderNode(
     }
   }
 
-  // Custom element with $props: set JS properties on the element instance
-  const tagName = def.tagName ?? "div";
+  /* RESOLVED ONCE, HERE, before anything branches on it.
+     A tag may be a name or a choice between names (`ElementTagName`). Resolving at the top means
+     every test below — the hyphen check that routes to the custom-element path, `customElements.get`,
+     `createElement` itself — sees a literal, exactly as it did when a tag could only be written out.
+
+     It is not tracked. `tagName` is in RESERVED_KEYS so no binding sweep reaches it, and a tag that
+     changed after mount would mean replacing the node: the subtree's listeners, its focus, its typed
+     input values and its component instances all go with it, and this runtime has no dispose walk to
+     pay that bill (renderSwitch, two hundred lines up, still leaks its previous case's effects).
+     `jx validate` warns when a tag discriminant is also an assignment target, so the case where this
+     rule bites is caught before it ships rather than found as a `<div>` that never became an `<a>`. */
+  const tagName = resolveTagName(def.tagName, localState);
   const isCustomEl = tagName.includes("-") && customElements.get(tagName);
 
   if (def.$props && isCustomEl) {
@@ -1230,6 +1263,34 @@ function renderMappedArrayInto(
   });
 }
 
+/**
+ * An element's tag: a name, or the branch of a {@link JxTagExpression} the state selects.
+ *
+ * Every branch of the expression is itself a `TagName`, so this can only ever return something the
+ * schema already held to the tag-name pattern — the property that lets the compiler enumerate the
+ * candidates and lets `createElement` be called without a second thought here.
+ *
+ * @param {unknown} tagName The element's declared tag.
+ * @param {JxScope} scope The state the discriminant reads.
+ * @returns {string} A literal tag name; `"div"` when nothing is declared.
+ */
+export function resolveTagName(tagName: unknown, scope: JxScope): string {
+  if (typeof tagName === "string") {
+    return tagName;
+  }
+  if (!isTagExpression(tagName)) {
+    return "div";
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    // `evaluateOperand`, not `evaluateExpression`: the discriminant is an OPERAND — a pointer, a
+    // Literal or a nested node — exactly as it is for a `$switch`, whose docstring names this.
+    return evaluateOperand(expression.target, scope, null) ? expression.value : expression.initial;
+  }
+  const key = evaluateOperand(expression.target, scope, null);
+  return expression.cases[String(key)] ?? expression.default;
+}
+
 // ─── $switch ──────────────────────────────────────────────────────────────────
 
 /**
@@ -1240,7 +1301,7 @@ function renderMappedArrayInto(
  */
 function renderSwitch(def: JxElement, state: JxScope, options?: JxRenderOptions) {
   const path = options?._path ?? [];
-  const container = document.createElement(def.tagName ?? "div");
+  const container = document.createElement(resolveTagName(def.tagName, state));
 
   if (options?.onNodeCreated) {
     options.onNodeCreated(container, path, def, state);
@@ -1252,7 +1313,11 @@ function renderSwitch(def: JxElement, state: JxScope, options?: JxRenderOptions)
   let generation = 0;
 
   effect(() => {
-    container.innerHTML = "";
+    /* `replaceChildren()` rather than `innerHTML = ""`: identical semantics, and it is not a
+       Trusted Types injection sink — under `require-trusted-types-for 'script'` an innerHTML write
+       needs a policy even when the string is empty. Four sinks that were never injecting anything
+       is four fewer things a policy has to be permissive about. */
+    container.replaceChildren();
     if (!isRefObj(def.$switch)) {
       return;
     }
@@ -1264,7 +1329,8 @@ function renderSwitch(def: JxElement, state: JxScope, options?: JxRenderOptions)
 
     if (isRefObj(caseDef)) {
       // External $ref — fetch and render asynchronously
-      const gen = (generation += 1);
+      generation += 1;
+      const gen = generation;
       const { href } = new URL(caseDef.$ref, location.href);
       resolve(href)
         .then(async (doc) => {
@@ -1275,7 +1341,7 @@ function renderSwitch(def: JxElement, state: JxScope, options?: JxRenderOptions)
           if (gen !== generation) {
             return;
           }
-          container.innerHTML = "";
+          container.replaceChildren();
           const childOpts = options ? { ...options, _path: [...path, "cases", key] } : undefined;
           container.append(renderNode(doc, childScope, childOpts));
         })
@@ -1323,7 +1389,7 @@ export async function resolvePrototype(
       const debounceMs = def.debounce ?? 0;
       let debounceTimer: ReturnType<typeof setTimeout> | null = null;
 
-      if (!def.manual) {
+      if (!def.manual && !_autoRequestConfig.skip) {
         effect(() => {
           let url: string | undefined;
           if (isTemplateString(def.url)) {
@@ -1422,38 +1488,21 @@ export async function resolvePrototype(
     case "Cookie": {
       const name = def.name ?? key;
       const read = () => {
-        const m = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
-        if (!m) {
+        const raw = readCookie(document.cookie, name);
+        if (raw === null) {
           return null;
         }
         try {
-          return JSON.parse(decodeURIComponent(m[1]!));
+          return JSON.parse(decodeURIComponent(raw));
         } catch {
-          return m[1];
+          return raw;
         }
       };
       const cookieState: Ref<unknown> = ref(read() ?? def.default ?? null);
       // Persist on change
       effect(() => {
-        const v = cookieState.value;
-        let s = `${name}=${encodeURIComponent(JSON.stringify(v))}`;
-        if (def.maxAge !== undefined) {
-          s += `; Max-Age=${def.maxAge}`;
-        }
-        if (def.path) {
-          s += `; Path=${def.path}`;
-        }
-        if (def.domain) {
-          s += `; Domain=${def.domain}`;
-        }
-        if (def.secure) {
-          s += `; Secure`;
-        }
-        if (def.sameSite) {
-          s += `; SameSite=${def.sameSite}`;
-        }
         // oxlint-disable-next-line unicorn/no-document-cookie -- the Cookie $prototype IS the cookie store binding
-        document.cookie = s;
+        document.cookie = serializeCookie(name, cookieState.value, def);
       });
       return cookieState;
     }
@@ -2050,15 +2099,16 @@ export function resolveRef(refPath: string, state: JxScope) {
     return parts.length > 2 ? getPath(base, parts.slice(2).join("/")) : base;
   }
   if (refPath.startsWith("#/state/")) {
-    const sub = refPath.slice("#/state/".length);
-    const slash = sub.indexOf("/");
-    if (slash === -1) {
-      return state[sub];
-    }
-    return getPath(state[sub.slice(0, slash)], sub.slice(slash + 1));
+    // One call, not a hand-split leading token: slicing at the first `/` skipped unescaping it, so
+    // `#/state/a~1b/c` looked for a member called `a~1b` rather than `a/b`.
+    return readPath(state, refPath.slice("#/state/".length));
   }
   if (refPath.startsWith("parent#/")) {
-    return state[refPath.slice("parent#/".length)];
+    /*
+     * A prop name may be a path into the prop. This read the whole path as one key and returned
+     * undefined for `parent#/user/name`, while the compiler lowered it to a walk.
+     */
+    return readPath(state, refPath.slice("parent#/".length));
   }
   if (refPath.startsWith("window#/")) {
     return getPath(globalThis.window, refPath.slice("window#/".length));
@@ -2066,7 +2116,7 @@ export function resolveRef(refPath: string, state: JxScope) {
   if (refPath.startsWith("document#/")) {
     return getPath(globalThis.document, refPath.slice("document#/".length));
   }
-  return state[refPath] ?? null;
+  return readPath(state, refPath) ?? null;
 }
 
 // ─── Utilities ────────────────────────────────────────────────────────────────
@@ -2098,16 +2148,51 @@ function isNestedSelector(k: string) {
 }
 
 /**
+ * Walk a path off a value. Delegates to the one tokenizer (`pointer.ts`) — this used to split on
+ * `/[./]/`, which no other path in the codebase agreed with.
+ *
  * @param {unknown} obj
  * @param {string} path
  * @returns {unknown}
  */
 function getPath(obj: unknown, path: string) {
-  let current: unknown = obj;
-  for (const k of path.split(/[./]/)) {
-    current = (current as Record<string, unknown>)?.[k];
+  return readPath(obj, path);
+}
+
+/** Keys already reported, so a component rendered in a loop warns once rather than per instance. */
+const _privatePropWarned = new Set<string>();
+
+/**
+ * Refuse a `$props` write against a private (`#`) state key — `spec.md` §5.6.
+ *
+ * Ignored rather than thrown. A `$props` block naming a private entry is an authoring mistake, not
+ * a broken document: the rest of the instance is well-formed and refusing to render it would turn a
+ * typo into a blank page. But silence was the previous behavior and it is the wrong kind — the
+ * author sees a prop that looks accepted and does nothing — so the write is dropped and named.
+ *
+ * @param {string} key
+ * @param {string} [where] - The site refusing it, for a message that points somewhere
+ * @returns {boolean} True when the key is private and the caller must skip it
+ */
+function refusePrivateProp(key: string, where?: string): boolean {
+  if (!isPrivateStateKey(key)) {
+    return false;
   }
-  return current;
+  const seen = where === undefined ? key : `${where}:${key}`;
+  if (!_privatePropWarned.has(seen)) {
+    _privatePropWarned.add(seen);
+    console.warn(
+      `Jx: "${key}" is private state (spec.md §5.6) and cannot be set through $props` +
+        `${where === undefined ? "" : ` (${where})`}. The write was ignored; rename the entry ` +
+        "without the leading # to make it part of the component's interface.",
+    );
+  }
+  return true;
+}
+
+/** Tests only — the warn-once set outlives a single render by design. */
+export function _resetPrivatePropWarnings(): void {
+  _privatePropWarned.clear();
 }
 
 /**
@@ -2118,6 +2203,9 @@ function getPath(obj: unknown, path: string) {
 function mergeProps(def: JxElement, parentState: JxScope): JxScope {
   const child = Object.create(parentState) as JxScope;
   for (const [k, v] of Object.entries(def.$props ?? {})) {
+    if (refusePrivateProp(k, "$props")) {
+      continue;
+    }
     child[k] = isRefObj(v) ? resolveRef(v.$ref, parentState) : v;
   }
   return child;
@@ -2306,7 +2394,12 @@ function injectHead(entries: JxHeadEntry[], _base: string) {
       el.setAttribute(k, String(v));
     }
     if (entry.textContent) {
-      el.textContent = entry.textContent;
+      // An object is a structured data block (JSON-LD, site-architecture.md §8.5). The compiler
+      // Serializes it the same way, so the interpreted page and the built page agree.
+      el.textContent =
+        typeof entry.textContent === "object"
+          ? JSON.stringify(entry.textContent, null, 2)
+          : entry.textContent;
     }
     document.head.append(el);
   }
@@ -2383,6 +2476,9 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
         try {
           const props = JSON.parse(propsAttr) as Record<string, unknown>;
           for (const [key, val] of Object.entries(props)) {
+            if (refusePrivateProp(key, "data-jx-props")) {
+              continue;
+            }
             if (key in (def.state ?? {})) {
               state[key] = val;
             }
@@ -2400,6 +2496,10 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
       );
       for (const name of propAttrNames) {
         const key = name.slice("props.".length);
+        if (refusePrivateProp(key, "props.* attribute")) {
+          this.removeAttribute(name);
+          continue;
+        }
         if (key in (def.state ?? {})) {
           state[key] = this.getAttribute(name);
           this.removeAttribute(name);
@@ -2408,12 +2508,22 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
 
       // Merge $props set as JS properties by parent before connection
       for (const key of Object.keys(def.state ?? {})) {
+        if (isPrivateStateKey(key)) {
+          continue;
+        }
         if (key in this && (this as Record<string, unknown>)[key] !== undefined) {
           state[key] = (this as Record<string, unknown>)[key];
         }
       }
-      // Set up property getters/setters that forward into reactive state
+      /*
+       * Set up property getters/setters that forward into reactive state. Private entries get NO
+       * accessor: the property-first interface IS the props mechanism, so defining one would leave
+       * `el["#cache"] = x` writing straight through everything above.
+       */
       for (const key of Object.keys(def.state ?? {})) {
+        if (isPrivateStateKey(key)) {
+          continue;
+        }
         if (!(key in HTMLElement.prototype)) {
           Object.defineProperty(this, key, {
             configurable: true,
@@ -2429,7 +2539,7 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
 
       // Capture light DOM children (for slot distribution) before rendering
       const slottedChildren = [...this.childNodes];
-      this.innerHTML = "";
+      this.replaceChildren();
 
       // Custom elements default to display:inline — use block so they behave as
       // Containers (matching <div> semantics).  The component's own style can
@@ -2503,7 +2613,7 @@ function renderCustomElementWithProps(
   options?: JxRenderOptions,
   path?: JxPath,
 ) {
-  const el = document.createElement(def.tagName ?? "div");
+  const el = document.createElement(resolveTagName(def.tagName, state));
 
   if (options?.onNodeCreated) {
     options.onNodeCreated(el, path ?? [], def, state);
@@ -2511,6 +2621,9 @@ function renderCustomElementWithProps(
 
   // Set JS properties from $props (before connection)
   for (const [key, val] of Object.entries(def.$props ?? {})) {
+    if (refusePrivateProp(key, "$props")) {
+      continue;
+    }
     if (isRefObj(val)) {
       const refVal = val;
       const resolved = resolveRef(refVal.$ref, state);
@@ -2577,7 +2690,7 @@ function distributeSlots(host: HTMLElement, slottedChildren: ChildNode[]) {
     const name = slot.getAttribute("name");
     const matches = name ? (named.get(name) ?? []) : unnamed;
     if (matches.length > 0) {
-      slot.innerHTML = "";
+      slot.replaceChildren();
       for (const child of matches) {
         slot.append(child);
       }