@jxsuite/studio 6.1.0 → 6.1.2

package/src/canvas/iframe-eval.ts

@@ -13,22 +13,39 @@
 
 import { evaluateExpression } from "@jxsuite/runtime/expression";
 import { resolveRef } from "@jxsuite/runtime";
+import { isFunction, isJsonObject, isNonNullObject, isRef } from "@jxsuite/schema/guards";
 import { formatPreviewValue } from "../utils/preview-format";
+import type { PreviewValue } from "../utils/preview-format";
 
-import type { ExpressionNode } from "@jxsuite/runtime/expression";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type {
+  JsonValue,
+  JxDocumentValue,
+  JxExpressionNode,
+  JxMutableNode,
+  JxStateDefinition,
+} from "@jxsuite/schema/types";
 import type { EvalExprResult } from "./iframe-protocol";
 
-type Scope = Record<string, unknown>;
+/**
+ * Whether the raw (document) state entry is a pure named-formula (`$expression` + parameters).
+ *
+ * Looser than `isNamedFormulaDef`: an empty `parameters` array, or an `$expression` that is not an
+ * object, still qualifies.
+ */
+function isNamedFormulaEntry(
+  entry: JxStateDefinition | undefined,
+): entry is JxStateDefinition & { parameters: JxDocumentValue[] } {
+  return isJsonObject(entry) && "$expression" in entry && Array.isArray(entry["parameters"]);
+}
 
-/** Whether the raw (document) state entry is a pure named-formula (`$expression` + parameters). */
-function isNamedFormulaEntry(entry: unknown): boolean {
-  return (
-    typeof entry === "object" &&
-    entry !== null &&
-    !Array.isArray(entry) &&
-    "$expression" in entry &&
-    Array.isArray((entry as { parameters?: unknown }).parameters)
-  );
+/** A structured clone of `value`, or null when it holds something uncloneable (a function, a node). */
+function cloneOrNull<T>(value: T): T | null {
+  try {
+    return structuredClone(value);
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -38,21 +55,27 @@ function isNamedFormulaEntry(entry: unknown): boolean {
  * callable (event handlers, structured-body functions, server fns) is dropped so a stray `call`
  * can't run a side effect against the live canvas.
  */
-export function cloneLiveScope(defs: Scope, rawState: Record<string, unknown> | null): Scope {
-  const out: Scope = {};
+export function cloneLiveScope(
+  defs: JxScope,
+  rawState: Record<string, JxStateDefinition> | null,
+): JxScope {
+  const out: JxScope = {};
   for (const key of Object.keys(defs)) {
     try {
       // Reading through the reactive proxy auto-unwraps a top-level ref/computed — and can throw (a
       // Computed getter that throws), which maps the key to null instead of aborting the clone.
       const value = defs[key];
-      if (typeof value === "function") {
+      if (isFunction(value)) {
         if (isNamedFormulaEntry(rawState?.[key])) {
           out[key] = value; // A pure formula callable — safe (and needed) for `call` nodes.
         }
         continue;
       }
-      const json = JSON.stringify(value);
-      out[key] = json === undefined ? null : (JSON.parse(json) as unknown);
+      /* SAFETY: A widening. `JSON.stringify` answers undefined for undefined, a symbol or a function,
+         which lib.d.ts's `string` return type leaves out. */
+      const json = JSON.stringify(value) as string | undefined;
+      // SAFETY: `json` is JSON.stringify's own output above, so it parses back to JSON data.
+      out[key] = json === undefined ? null : (JSON.parse(json) as JsonValue);
     } catch {
       out[key] = null;
     }
@@ -69,44 +92,41 @@ export function cloneLiveScope(defs: Scope, rawState: Record<string, unknown> |
  * chain naturally (an inner `items` ref may read the outer `$map/item`).
  */
 export function bindRepeaterContext(
-  scope: Scope,
-  shadowDoc: unknown,
+  scope: JxScope,
+  shadowDoc: JxMutableNode | null,
   contextPath: (string | number)[] | null,
-): Scope {
+): JxScope {
   if (!contextPath || contextPath.length === 0) {
     return scope;
   }
-  let node: unknown = shadowDoc;
+  let node: JxDocumentValue | undefined = shadowDoc;
   let bound = scope;
   for (const seg of contextPath) {
-    if (!node || typeof node !== "object") {
+    if (!isNonNullObject(node)) {
       break;
     }
-    const rec = node as Record<string, unknown>;
-    if (rec.$prototype === "Array" && seg === "map") {
+    /* SAFETY: The shadow doc is JSON, so every non-null object on the walk is a document object or
+       array, and indexing either by a path segment yields another document value or undefined. */
+    const rec = node as Record<string, JxDocumentValue | undefined>;
+    if (rec["$prototype"] === "Array" && seg === "map") {
       // Entering the repeater's template — bind the first item's context before descending.
-      const itemsDef = rec.items;
-      const items: unknown =
-        itemsDef && typeof itemsDef === "object" && "$ref" in itemsDef
-          ? resolveRef((itemsDef as { $ref: string }).$ref, bound)
-          : itemsDef;
+      const itemsDef = rec["items"];
+      const items = isRef(itemsDef) ? resolveRef(itemsDef.$ref, bound) : itemsDef;
       if (Array.isArray(items) && items.length > 0) {
-        let item: unknown;
-        try {
-          // Items resolved from the shadow doc (a literal array) must not be mutable through the
-          // Preview scope — clone; scope-resolved items are already clone data, so this is free.
-          item = structuredClone(items[0]);
-        } catch {
-          item = null;
-        }
-        const child = Object.create(bound) as Scope;
-        child.$map = { index: 0, item };
+        const [first] = items;
+        // Items resolved from the shadow doc (a literal array) must not be mutable through the
+        // Preview scope — clone; scope-resolved items are already clone data, so this is free.
+        const item = cloneOrNull(first);
+        /* SAFETY: `Object.create(bound)` is an empty object whose prototype is the scope built so far,
+           so it is a scope that reads every outer key through and owns only the three set below. */
+        const child = Object.create(bound) as JxScope;
+        child["$map"] = { index: 0, item };
         child["$map/item"] = item;
         child["$map/index"] = 0;
         bound = child;
       }
     }
-    node = rec[seg as keyof typeof rec];
+    node = rec[seg];
   }
   return bound;
 }
@@ -118,30 +138,34 @@ export function bindRepeaterContext(
  */
 export function evaluateLiveExprs(
   exprs: { id: string; node: unknown }[],
-  defs: Scope,
-  shadowDoc: unknown,
+  defs: JxScope,
+  shadowDoc: JxMutableNode | null,
   contextPath: (string | number)[] | null,
 ): EvalExprResult[] {
-  const rawState =
-    shadowDoc && typeof shadowDoc === "object"
-      ? ((shadowDoc as { state?: Record<string, unknown> }).state ?? null)
-      : null;
+  const rawState = shadowDoc?.state ?? null;
   return exprs.map(({ id, node }) => {
     const values = new Map<string, string>();
     // A fresh scope per expression: a mutating operator writes into this clone only, and can never
     // Leak into the next expression's evaluation (or the live canvas).
-    let scope: Scope;
+    let scope: JxScope;
     try {
       scope = bindRepeaterContext(cloneLiveScope(defs, rawState), shadowDoc, contextPath);
     } catch (error) {
       return { error: error instanceof Error ? error.message : String(error), id, values: [] };
     }
     try {
-      if (!node || typeof node !== "object" || !("operator" in node)) {
+      if (!isNonNullObject(node) || !("operator" in node)) {
         throw new Error("not an expression node");
       }
-      evaluateExpression(node as ExpressionNode, scope, null, undefined, {
-        report: (path, value) => values.set(path.join("/"), formatPreviewValue(value)),
+      /* SAFETY: `operator` is the key every expression node carries, and `evaluateExpression`
+         validates the operator itself, throwing on an unknown one into the catch below. */
+      void evaluateExpression(node as JxExpressionNode, scope, null, undefined, {
+        report: (path, value) => {
+          /* SAFETY: the trace reports raw runtime values, and PreviewValue names every category a JS
+             value falls in (primitive, bigint, symbol, function, array, record); formatting relies on
+             nothing beyond what JSON.stringify and String() accept for any value. */
+          values.set(path.join("/"), formatPreviewValue(value as PreviewValue));
+        },
       });
       return { id, values: [...values.entries()] };
     } catch (error) {