@cortex-js/compute-engine 0.57.0 → 0.58.0

package/dist/compile.esm.js

@@ -1,4 +1,4 @@
-/** Compute Engine 0.57.0 */
+/** Compute Engine 0.58.0 */
 
 // src/compute-engine/numerics/richardson.ts
 function extrapolate(f, x0, options = {}) {
@@ -3535,7 +3535,42 @@ function widen2(a, b) {
   if (b === "nothing") return a;
   if (isSubtype(a, b)) return b;
   if (isSubtype(b, a)) return a;
-  return superType(a, b);
+  const sup = superType(a, b);
+  if (LOSSY_SUPERTYPE.has(sup)) return unionTypes(a, b);
+  return sup;
+}
+var LOSSY_SUPERTYPE = /* @__PURE__ */ new Set([
+  "scalar",
+  "value",
+  "function",
+  "expression",
+  "collection",
+  "indexed_collection",
+  "list",
+  "set",
+  "tuple",
+  "record",
+  "dictionary",
+  "map",
+  "any"
+]);
+function unionTypes(a, b) {
+  const members = [];
+  const push = (t) => {
+    if (typeof t === "object" && t.kind === "union") {
+      for (const m of t.types) push(m);
+      return;
+    }
+    const key = typeof t === "string" ? t : JSON.stringify(t);
+    if (!members.some(
+      (m) => (typeof m === "string" ? m : JSON.stringify(m)) === key
+    ))
+      members.push(t);
+  };
+  push(a);
+  push(b);
+  if (members.length === 1) return members[0];
+  return { kind: "union", types: members };
 }
 function narrow(...types) {
   if (types.length === 0) return "nothing";
@@ -3609,7 +3644,7 @@ function collectionElementType(type) {
   if (type.kind === "set") return type.elements;
   if (type.kind === "tuple") return widen(...type.elements.map((x) => x.type));
   if (type.kind === "dictionary")
-    return parseType(`tuple<string, ${type.values}>`);
+    return parseType(`tuple<string, ${typeToString(type.values)}>`);
   if (type.kind === "record") {
     return parseType(
       `tuple<string, ${typeToString(widen(...Object.values(type.elements)))}>`
@@ -5511,15 +5546,16 @@ var DEFINITIONS_CORE = [
     precedence: ASSIGNMENT_PRECEDENCE,
     parse: parseAssign
   },
-  // General colon operator (type annotation, mapping notation)
-  // Precedence below assignment (260) so `:=` takes priority,
-  // and below arrows (270) so `f: A \to B` parses as `Colon(f, To(A, B))`
+  // General colon operator (type annotation, mapping notation, Desmos piecewise)
+  // Precedence below comparisons (245) so `cond : val` (Desmos compact piecewise)
+  // parses as `Colon(cond, val)`, and below arrows (270) so
+  // `f: A \to B` parses as `Colon(f, To(A, B))`.
   {
     name: "Colon",
     latexTrigger: ":",
     kind: "infix",
     associativity: "right",
-    precedence: 250,
+    precedence: 240,
     serialize: (serializer, expr) => joinLatex([
       serializer.serialize(operand(expr, 1)),
       "\\colon",
@@ -5530,7 +5566,7 @@ var DEFINITIONS_CORE = [
     latexTrigger: "\\colon",
     kind: "infix",
     associativity: "right",
-    precedence: 250,
+    precedence: 240,
     parse: "Colon"
   },
   {
@@ -7100,7 +7136,10 @@ function parseForComprehension(parser, lhs, until) {
       p.skipVisualSpace();
       const isComma = p.peek === ",";
       p.index = saved;
-      return isComma;
+      if (isComma) return true;
+      if (peekKeyword(p, "where")) return true;
+      if (peekKeyword(p, "with")) return true;
+      return false;
     }
   };
   const elements = [];
@@ -7141,6 +7180,25 @@ function parseWhereExpression(parser, lhs, until) {
     parser.skipVisualSpace();
   } while (parser.match(","));
   if (bindings.length === 0) return null;
+  const forStart = parser.index;
+  if (matchKeyword(parser, "for")) {
+    const loop = parseForComprehension(parser, lhs, until);
+    if (loop) {
+      const block2 = [];
+      for (const b of bindings) {
+        const normalized = normalizeLocalAssign(b);
+        if (operator(normalized) === "Assign") {
+          block2.push(["Declare", operand(normalized, 1)]);
+          block2.push(normalized);
+        } else {
+          block2.push(normalized);
+        }
+      }
+      block2.push(loop);
+      return ["Block", ...block2];
+    }
+    parser.index = forStart;
+  }
   const block = [];
   for (const b of bindings) {
     const normalized = normalizeLocalAssign(b);
@@ -7354,6 +7412,17 @@ function parseIntervalBody(body, openLeft, openRight) {
   const upperExpr = openRight ? ["Open", upper] : upper;
   return ["Interval", lowerExpr, upperExpr];
 }
+var COMPARISON_HEADS = /* @__PURE__ */ new Set([
+  "Less",
+  "LessEqual",
+  "Greater",
+  "GreaterEqual",
+  "Equal",
+  "NotEqual",
+  "And",
+  "Or",
+  "Not"
+]);
 var DEFINITIONS_SETS = [
   //
   // Constants
@@ -7612,18 +7681,58 @@ var DEFINITIONS_SETS = [
     closeTrigger: "}",
     parse: (_parser, body) => {
       if (isEmptySequence(body)) return "EmptySet";
+      if (operator(body) == "Delimiter" && stringValue(operand(body, 2)) === ",") {
+        body = operand(body, 1);
+      }
       const h = operator(body);
-      if (h === "Divides" || h === "Colon") {
+      if (h === "Divides") {
         const expr = operand(body, 1);
         const condition = operand(body, 2);
         if (expr !== null && condition !== null)
           return ["Set", expr, ["Condition", condition]];
       }
-      if (operator(body) == "Delimiter" && stringValue(operand(body, 2)) === ",") {
-        body = operand(body, 1);
+      if (h === "Colon") {
+        const lhs = operand(body, 1);
+        const rhs = operand(body, 2);
+        if (lhs !== null && rhs !== null) {
+          const lhsOp = operator(lhs);
+          if (lhsOp !== null && COMPARISON_HEADS.has(lhsOp)) {
+            return ["Which", lhs, rhs];
+          }
+          return ["Set", lhs, ["Condition", rhs]];
+        }
       }
-      if (operator(body) !== "Sequence") return ["Set", body];
-      return ["Set", ...operands(body)];
+      if (h === "Sequence") {
+        const elements = operands(body);
+        const colonElements = elements.filter((el) => operator(el) === "Colon");
+        const allPiecewise = colonElements.length > 0 && colonElements.every((el) => {
+          const lhs = operand(el, 1);
+          const lhsOp = lhs !== null ? operator(lhs) : null;
+          return lhsOp !== null && COMPARISON_HEADS.has(lhsOp);
+        });
+        if (allPiecewise) {
+          const whichOps = [];
+          for (let i = 0; i < elements.length; i++) {
+            const el = elements[i];
+            if (operator(el) === "Colon") {
+              const cond = operand(el, 1);
+              const val = operand(el, 2);
+              if (cond === null || val === null) {
+                return ["Set", ...elements];
+              }
+              whichOps.push(cond, val);
+            } else {
+              if (i !== elements.length - 1) {
+                return ["Set", ...elements];
+              }
+              whichOps.push("True", el);
+            }
+          }
+          return ["Which", ...whichOps];
+        }
+        return ["Set", ...elements];
+      }
+      return ["Set", body];
     },
     serialize: (serializer, expr) => {
       if (nops(expr) === 2 && operator(operand(expr, 2)) === "Condition") {
@@ -9597,7 +9706,8 @@ function parseTrig(op) {
       minPrec: MULTIPLICATION_PRECEDENCE,
       condition: (parser2) => trigCommands[parser2.peek] || (until?.condition?.(parser2) ?? false)
     });
-    const appliedFn = args === null ? fn : typeof fn === "string" ? [fn, ...args] : ["Apply", fn, ...args];
+    const head = fn === "Arctan" && args?.length === 2 ? "Arctan2" : fn;
+    const appliedFn = args === null ? fn : typeof head === "string" ? [head, ...args] : ["Apply", head, ...args];
     return sup === null ? appliedFn : ["Power", appliedFn, sup];
   };
 }
@@ -11720,10 +11830,17 @@ var DEFINITIONS_OTHERS = [
   // The capitalized library entries already exist; these are pure parse
   // aliases so the lowercase names don't land in `unsupported-operator`.
   // ---------------------------------------------------------------------------
+  { latexTrigger: "\\operatorname{count}", parse: "Length" },
   { latexTrigger: "\\operatorname{random}", parse: "Random" },
   { latexTrigger: "\\operatorname{shuffle}", parse: "Shuffle" },
   { latexTrigger: "\\operatorname{repeat}", parse: "Repeat" },
   { latexTrigger: "\\operatorname{join}", parse: "Join" },
+  { latexTrigger: "\\operatorname{range}", parse: "Range" },
+  // Note: `\operatorname{with}` (Desmos's local-binding clause) is intentionally
+  // NOT registered here. Use the math-notation equivalent `\operatorname{where}`
+  // (with `\coloneq` for bindings), or register `with` as a custom dictionary
+  // entry at the integration layer — see the "Desmos-Specific Syntax — Prefer
+  // Custom LaTeX Dictionary" section in COMPUTE_ENGINE.md for a worked example.
   // ---------------------------------------------------------------------------
   // Geometric primitive heads. Registered as known typed heads so consumers
   // can branch on the operator name; CE itself doesn't render them. The
@@ -12914,6 +13031,15 @@ function interval(expr) {
   return void 0;
 }
 
+// src/compute-engine/numerics/random.ts
+function deterministicRandom(seed) {
+  const v = Math.sin(seed * 12.9898) * 43758.5453;
+  return v - Math.floor(v);
+}
+function nextSeed(seed) {
+  return seed + 0.6180339887498949;
+}
+
 // src/compute-engine/boxed-expression/canonical-utils.ts
 function canonical(ce, xs, scope) {
   if (xs.every((x) => x.isCanonical)) return xs;
@@ -12963,6 +13089,19 @@ var COLLECTIONS_LIBRARY = {
       indexWhere: void 0
     }
   },
+  Length: {
+    description: "Number of elements in a collection. Returns undefined for non-collections and for infinite collections.",
+    complexity: 4e3,
+    signature: "(any) -> integer",
+    type: () => "integer",
+    evaluate: ([xs], { engine }) => {
+      if (!xs.isCollection) return void 0;
+      if (xs.isEmptyCollection) return engine.Zero;
+      const n = xs.count;
+      if (n === void 0 || !isFinite(n)) return void 0;
+      return engine.number(n);
+    }
+  },
   Tuple: {
     description: "A fixed number of heterogeneous elements",
     complexity: 8200,
@@ -13216,10 +13355,12 @@ var COLLECTIONS_LIBRARY = {
         const upper = expr.op2.re;
         let count = expr.op3.re;
         if (!isFinite(count)) count = DEFAULT_LINSPACE_COUNT;
+        count = Math.floor(count);
         if (!isFinite(lower) || !isFinite(upper)) return void 0;
         if (index < 1 || index > count) return void 0;
+        if (count === 1) return expr.engine.number(lower);
         return expr.engine.number(
-          lower + (upper - lower) * (index - 1) / count
+          lower + (upper - lower) * (index - 1) / (count - 1)
         );
       },
       iterator: (expr) => {
@@ -13238,6 +13379,8 @@ var COLLECTIONS_LIBRARY = {
             !isFinite(expr.op3.re) ? DEFAULT_LINSPACE_COUNT : expr.op3.re
           );
         }
+        totalCount = Math.floor(totalCount);
+        const denom = totalCount > 1 ? totalCount - 1 : 1;
         let index = 1;
         return {
           next: () => {
@@ -13246,7 +13389,7 @@ var COLLECTIONS_LIBRARY = {
             index += 1;
             return {
               value: expr.engine.number(
-                lower + (upper - lower) * (index - 1 - 1) / totalCount
+                lower + (upper - lower) * (index - 1 - 1) / denom
               ),
               done: false
             };
@@ -13262,9 +13405,14 @@ var COLLECTIONS_LIBRARY = {
         if (t < lower || t > upper) return false;
         let count = expr.op3.re;
         if (!isFinite(count)) count = DEFAULT_LINSPACE_COUNT;
+        count = Math.floor(count);
         if (count === 0) return false;
-        const step = (upper - lower) / count;
-        return (t - lower) % step === 0;
+        if (count === 1) return t === lower;
+        const step = (upper - lower) / (count - 1);
+        const k = (t - lower) / step;
+        const tol = expr.engine.tolerance;
+        const kRounded = Math.round(k);
+        return kRounded >= 0 && kRounded <= count - 1 && Math.abs(k - kRounded) < tol;
       }
     }
   },
@@ -13589,10 +13737,12 @@ var COLLECTIONS_LIBRARY = {
     description: [
       "Access an element of an indexed collection.",
       "If the index is negative, it is counted from the end.",
-      "Multiple indices can be provided to access nested collections (e.g., matrices)."
+      "Multiple indices can be provided to access nested collections (e.g., matrices).",
+      "If the index is a finite collection of booleans, returns the elements where the mask is True.",
+      "If the index is a finite collection of integers, returns the elements at those indices."
     ],
     complexity: 8200,
-    signature: "(value: indexed_collection, index: (number|string)+) -> unknown",
+    signature: "(value: indexed_collection, index: (number|string|indexed_collection)+) -> unknown",
     type: ([xs]) => xs.operatorDefinition?.collection?.elttype?.(xs) ?? collectionElementType(xs.type.type) ?? "any",
     evaluate: (ops, { engine: ce }) => {
       let expr = ops[0];
@@ -13603,12 +13753,39 @@ var COLLECTIONS_LIBRARY = {
         if (!at) return void 0;
         const opAtIndex = ops[index];
         const s = isString(opAtIndex) ? opAtIndex.string : void 0;
-        if (s !== void 0) expr = at(expr, s) ?? ce.Nothing;
-        else {
-          const i = ops[index].re;
-          if (!Number.isInteger(i)) return void 0;
-          expr = at(expr, i) ?? ce.Nothing;
+        if (s !== void 0) {
+          expr = at(expr, s) ?? ce.Nothing;
+          index += 1;
+          continue;
         }
+        if (opAtIndex.isCollection && opAtIndex.isFiniteCollection) {
+          const indices = Array.from(opAtIndex.each());
+          const isMask = indices.every((m) => {
+            const name = sym(m);
+            return name === "True" || name === "False";
+          });
+          const picked = [];
+          if (isMask) {
+            indices.forEach((m, i2) => {
+              if (sym(m) !== "True") return;
+              const v = at(expr, i2 + 1);
+              if (v !== void 0) picked.push(v);
+            });
+          } else {
+            for (const m of indices) {
+              const k = m.re;
+              if (!Number.isInteger(k)) return void 0;
+              const v = at(expr, k);
+              if (v !== void 0) picked.push(v);
+            }
+          }
+          expr = ce._fn("List", picked);
+          index += 1;
+          continue;
+        }
+        const i = opAtIndex.re;
+        if (!Number.isInteger(i)) return void 0;
+        expr = at(expr, i) ?? ce.Nothing;
         index += 1;
       }
       return expr;
@@ -13619,7 +13796,7 @@ var COLLECTIONS_LIBRARY = {
     description: ["Return `n` elements from a collection."],
     complexity: 8200,
     signature: "(xs: indexed_collection, count: number) -> indexed_collection",
-    type: ([xs]) => `list<${collectionElementType(xs.type.type)}>`,
+    type: ([xs]) => `list<${typeToString(collectionElementType(xs.type.type) ?? "any")}>`,
     evaluate: (ops, { engine, materialization: eager }) => {
       if (!eager) return void 0;
       const takeExpr = engine._fn("Take", ops);
@@ -13666,7 +13843,7 @@ var COLLECTIONS_LIBRARY = {
     description: ["Return the collection without the first n elements."],
     complexity: 8200,
     signature: "(xs: indexed_collection, count: number) -> indexed_collection",
-    type: ([xs]) => `list<${collectionElementType(xs.type.type)}>`,
+    type: ([xs]) => `list<${typeToString(collectionElementType(xs.type.type) ?? "any")}>`,
     collection: {
       isLazy: (_expr) => true,
       count: (expr) => {
@@ -13862,7 +14039,9 @@ var COLLECTIONS_LIBRARY = {
     ],
     complexity: 8200,
     signature: "(value: indexed_collection, start: number, end: number) -> list",
-    type: ([xs]) => parseType(`list<${collectionElementType(xs.type.type)}>`),
+    type: ([xs]) => parseType(
+      `list<${typeToString(collectionElementType(xs.type.type) ?? "any")}>`
+    ),
     collection: {
       isLazy: (_expr) => true,
       count: (expr) => {
@@ -14194,16 +14373,26 @@ var COLLECTIONS_LIBRARY = {
   },
   // Randomize the order of the elements in the collection.
   Shuffle: {
-    description: "Randomize the order of the elements in the collection.",
+    description: "Randomize the order of the elements in the collection. With an optional `seed` argument, the shuffle is deterministic.",
     complexity: 8200,
-    signature: "(indexed_collection) -> indexed_collection",
+    signature: "(indexed_collection, real?) -> indexed_collection",
     type: (ops) => ops[0].type,
-    evaluate: ([xs], { engine: ce }) => {
+    evaluate: ([xs, seedOp], { engine: ce }) => {
       if (!xs.isFiniteCollection) return void 0;
       const data = Array.from(xs.each());
-      for (let i = data.length - 1; i > 0; i--) {
-        const j = Math.floor(Math.random() * (i + 1));
-        [data[i], data[j]] = [data[j], data[i]];
+      const seed = seedOp?.re;
+      if (seed !== void 0 && !Number.isNaN(seed)) {
+        let s = seed;
+        for (let i = data.length - 1; i > 0; i--) {
+          const j = Math.floor(deterministicRandom(s) * (i + 1));
+          [data[i], data[j]] = [data[j], data[i]];
+          s = nextSeed(s);
+        }
+      } else {
+        for (let i = data.length - 1; i > 0; i--) {
+          const j = Math.floor(Math.random() * (i + 1));
+          [data[i], data[j]] = [data[j], data[i]];
+        }
       }
       return ce.function(xs.operator, data);
     }
@@ -14270,7 +14459,9 @@ var COLLECTIONS_LIBRARY = {
       if (t === "string")
         return parseType(`tuple<list<string>, list<integer>>`);
       return parseType(
-        `tuple<list<${collectionElementType(t)}>, list<integer>>`
+        `tuple<list<${typeToString(
+          collectionElementType(t) ?? "any"
+        )}>, list<integer>>`
       );
     },
     evaluate: (ops, { engine: ce }) => {
@@ -14286,7 +14477,7 @@ var COLLECTIONS_LIBRARY = {
     description: "Return a list of the unique elements of the collection.",
     complexity: 8200,
     signature: "(collection) -> list",
-    type: ([xs]) => `list<${collectionElementType(xs.type.type)}>`,
+    type: ([xs]) => `list<${typeToString(collectionElementType(xs.type.type) ?? "any")}>`,
     evaluate: (ops, { engine: ce }) => {
       if (!ops[0].isFiniteCollection) return void 0;
       const [values, _counts] = tally(ops[0]);
@@ -14298,7 +14489,7 @@ var COLLECTIONS_LIBRARY = {
     wikidata: "Q381060",
     complexity: 8200,
     signature: "(collection, integer | function) -> list",
-    type: ([xs]) => `list<${collectionElementType(xs.type.type)}>`,
+    type: ([xs]) => `list<${typeToString(collectionElementType(xs.type.type) ?? "any")}>`,
     evaluate: ([xs, arg], { engine: ce }) => {
       if (!xs.isFiniteCollection) return void 0;
       const k = toInteger(arg);
@@ -14472,32 +14663,74 @@ var COLLECTIONS_LIBRARY = {
       }
     }
   },
-  // Repeat(x) -> [x, x, ...]
-  // This is an infinite series. Can use Take(Repeat(x), n) to get a finite series
-  // x is evaluated once. Although could use Hold()?
-  // So that First(Repeat(Hold(Random(5))), 10) would return 10 random numbers...
+  // Repeat(x) -> [x, x, ...]        — infinite sequence
+  // Repeat(x, n) -> [x, x, ..., x]  — finite list of n copies
   Repeat: {
-    description: "Produce an infinite sequence by repeating a single value.",
+    description: "Produce a sequence by repeating a single value. With 1 argument, returns an infinite sequence; with 2 arguments (value, count), returns a finite list of `count` copies.",
     complexity: 8200,
-    signature: "(value: any) -> list",
+    signature: "(value: any, count: integer?) -> list",
+    evaluate: (ops, { engine }) => {
+      if (ops.length !== 2) return void 0;
+      const raw = toInteger(ops[1]);
+      if (raw === null) return void 0;
+      const n = Math.max(0, raw);
+      if (n > engine.maxCollectionSize) return void 0;
+      return engine._fn("List", Array(n).fill(ops[0]));
+    },
     collection: {
-      isLazy: (_expr) => true,
-      count: () => Infinity,
-      isEmpty: (_expr) => false,
-      // Never empty
-      isFinite: () => false,
-      // Infinite collection
+      isLazy: (expr) => isFunction2(expr) && expr.ops?.length === 1,
+      count: (expr) => {
+        if (!isFunction2(expr)) return void 0;
+        if (expr.ops?.length === 2) {
+          const n = toInteger(expr.op2);
+          return n !== null ? Math.max(0, n) : void 0;
+        }
+        return Infinity;
+      },
+      isEmpty: (expr) => {
+        if (!isFunction2(expr)) return void 0;
+        if (expr.ops?.length === 2) {
+          const n = toInteger(expr.op2);
+          return n !== null ? n <= 0 : void 0;
+        }
+        return false;
+      },
+      isFinite: (expr) => isFunction2(expr) && expr.ops?.length === 2,
       contains: (expr, target) => {
         if (!isFunction2(expr)) return false;
+        if (expr.ops?.length === 2) {
+          const n = toInteger(expr.op2);
+          if (n !== null && n <= 0) return false;
+        }
         return expr.op1.isSame(target);
       },
       iterator: (expr) => {
         if (!isFunction2(expr))
           return { next: () => ({ value: void 0, done: true }) };
+        if (expr.ops?.length === 2) {
+          const n = toInteger(expr.op2);
+          if (n === null) {
+            return { next: () => ({ value: void 0, done: true }) };
+          }
+          const count = Math.max(0, n);
+          let i = 0;
+          return {
+            next: () => i++ < count ? { value: expr.op1, done: false } : { value: void 0, done: true }
+          };
+        }
         return { next: () => ({ value: expr.op1, done: false }) };
       },
-      at: (expr, _index) => {
+      // at is 1-based (consistent with Range, Take, and other collection handlers)
+      at: (expr, index) => {
         if (!isFunction2(expr)) return void 0;
+        if (typeof index !== "number") return void 0;
+        if (expr.ops?.length === 2) {
+          const n = toInteger(expr.op2);
+          const count = n !== null ? Math.max(0, n) : 0;
+          if (index < 1 || index > count) return void 0;
+        } else {
+          if (index < 1) return void 0;
+        }
         return expr.op1;
       }
     }
@@ -15206,6 +15439,13 @@ var BaseCompiler = class _BaseCompiler {
    *    GLSL (no dynamic arrays, no push).  A compile-time error is thrown.
    *    TODO(E3-GLSL): support GLSL multi-Element via a pre-declared fixed-size
    *    array or by unrolling when bounds are known at compile time.
+   *
+   * Known issue (imperative form): the IIFE generated by form (1) has no
+   * `return` statement, so `Loop(body, Element(i, Range(lo, hi)))` compiled
+   * to JS evaluates to `undefined` at runtime, while CE evaluation returns a
+   * `List` of body values. See `test/compute-engine/a1-c1-compile-parity.test.ts`
+   * ("Loop compiles in JS") for the verify-only test that locks in the
+   * current behavior.
    */
   static compileForLoop(args, target) {
     if (!args[0]) throw new Error("Loop: no body");
@@ -20293,6 +20533,7 @@ var JAVASCRIPT_FUNCTIONS = {
       return `_SYS.cexp(${compile2(args[0])})`;
     return `Math.exp(${compile2(args[0])})`;
   },
+  First: (args, compile2) => `${compile2(args[0])}[0]`,
   Floor: (args, compile2) => {
     if (BaseCompiler.isIntegerValued(args[0])) return compile2(args[0]);
     return `Math.floor(${compile2(args[0])})`;
@@ -20451,7 +20692,20 @@ var JAVASCRIPT_FUNCTIONS = {
     if (nConst !== void 0) return `Math.pow(${compile2(arg)}, ${1 / nConst})`;
     return `Math.pow(${compile2(arg)}, 1 / (${compile2(exp3)}))`;
   },
-  Random: "Math.random",
+  Random: (args, compile2) => {
+    if (args.length === 0) return "Math.random()";
+    if (args.length === 2) {
+      const m = compile2(args[0]);
+      const n = compile2(args[1]);
+      return `((${m}) + Math.floor(Math.random() * ((${n}) - (${m}))))`;
+    }
+    const arg = args[0];
+    if (BaseCompiler.isIntegerValued(arg)) {
+      return `Math.floor(Math.random() * (${compile2(arg)}))`;
+    }
+    const a = compile2(arg);
+    return `(() => { const _s = (${a}) * 12.9898; const _v = Math.sin(_s) * 43758.5453; return _v - Math.floor(_v); })()`;
+  },
   Round: (args, compile2) => {
     if (BaseCompiler.isIntegerValued(args[0])) return compile2(args[0]);
     return `Math.round(${compile2(args[0])})`;
@@ -20479,6 +20733,7 @@ var JAVASCRIPT_FUNCTIONS = {
     if (BaseCompiler.isComplexValued(arg)) return `_SYS.csech(${compile2(arg)})`;
     return `1 / Math.cosh(${compile2(arg)})`;
   },
+  Second: (args, compile2) => `${compile2(args[0])}[1]`,
   Heaviside: "_SYS.heaviside",
   Sign: "Math.sign",
   Sinc: "_SYS.sinc",
@@ -20511,6 +20766,7 @@ var JAVASCRIPT_FUNCTIONS = {
       return `_SYS.ctanh(${compile2(args[0])})`;
     return `Math.tanh(${compile2(args[0])})`;
   },
+  Third: (args, compile2) => `${compile2(args[0])}[2]`,
   Mod: ([a, b], compile2) => {
     if (a === null || b === null) throw new Error("Mod: missing argument");
     const ca = compile2(a);
@@ -21790,6 +22046,14 @@ var GPU_FUNCTIONS = {
     return `exp(${compile2(args[0])})`;
   },
   Exp2: "exp2",
+  // Component access — assumes the argument compiles to a vec2/vec3/vec4
+  // (the common case for 2D/3D points). For 5+-element tuples that compile
+  // to `float[N]` arrays, swizzle access is invalid GLSL and the shader
+  // will fail to compile; that's an edge case `First`/`Second`/`Third`
+  // aren't designed for. Vec swizzles are identical between GLSL and WGSL.
+  First: (args, compile2) => `${compile2(args[0])}.x`,
+  Second: (args, compile2) => `${compile2(args[0])}.y`,
+  Third: (args, compile2) => `${compile2(args[0])}.z`,
   Floor: (args, compile2) => {
     if (BaseCompiler.isIntegerValued(args[0])) return compile2(args[0]);
     return `floor(${compile2(args[0])})`;
@@ -22267,6 +22531,39 @@ var GPU_FUNCTIONS = {
   // Sum/Product — unrolled or for-loop
   Sum: (args, compile2, target) => compileGPUSumProduct("Sum", args, compile2, target),
   Product: (args, compile2, target) => compileGPUSumProduct("Product", args, compile2, target),
+  // Range — inline constant array literal (bounds must be compile-time constants)
+  Range: (args, _compile, target) => {
+    if (args.length < 2 || args.length > 3) {
+      throw new Error(
+        "Range: GPU compile expects 2 or 3 arguments (lo, hi, step?)"
+      );
+    }
+    const lo = args[0].re;
+    const hi = args[1].re;
+    const step = args.length === 3 ? args[2].re : 1;
+    if (!Number.isFinite(lo) || !Number.isFinite(hi) || !Number.isFinite(step)) {
+      throw new Error(
+        "Range: GPU compile requires constant numeric bounds (non-constant ranges must be materialized at JS host then uploaded as a uniform)"
+      );
+    }
+    if (step === 0) throw new Error("Range: step cannot be zero");
+    const count = Math.max(0, Math.floor((hi - lo) / step) + 1);
+    if (count === 0) {
+      throw new Error(
+        "Range: empty range (lo > hi for positive step, or lo < hi for negative step)"
+      );
+    }
+    if (count > 256) {
+      throw new Error(
+        `Range: GPU compile inlines ranges up to 256 elements (got ${count})`
+      );
+    }
+    const values = [];
+    for (let i = 0; i < count; i++) values.push(lo + i * step);
+    const isWGSL = target.language === "wgsl";
+    const arrayType = isWGSL ? `array<f32, ${count}>` : `float[${count}]`;
+    return `${arrayType}(${values.map(formatGPUNumber).join(", ")})`;
+  },
   // Loop — GPU for-loop (no IIFE, no let)
   Loop: (args, _compile, target) => {
     if (!args[0]) throw new Error("Loop: no body");
@@ -22295,6 +22592,134 @@ var GPU_FUNCTIONS = {
   ${bodyCode};
 }`;
   },
+  // Statistical functions
+  /**
+   * GCD of two scalar arguments.
+   *
+   * Uses a preamble helper `_gpu_gcd` (Euclidean algorithm via `mod`).
+   * Only two-argument form is supported in GPU targets.
+   */
+  GCD: (args, compile2) => {
+    if (args.length < 2) throw new Error("GCD: need at least two arguments");
+    if (args.length > 2)
+      throw new Error("GCD: GPU target supports only two-argument GCD");
+    const a = args[0];
+    const b = args[1];
+    if (a === null || b === null) throw new Error("GCD: missing argument");
+    return `_gpu_gcd(${compile2(a)}, ${compile2(b)})`;
+  },
+  /**
+   * Variance of a compile-time-known list.
+   *
+   * Accepts either a single `List(...)` argument or N scalar arguments.
+   * Generates fully inline code: computes mean then sum of squared deviations,
+   * divided by (N-1) for sample variance (matches JS `_SYS.variance`).
+   */
+  Variance: (args, compile2) => {
+    let elems;
+    if (args.length === 1 && isFunction2(args[0], "List")) {
+      elems = args[0].ops;
+    } else if (args.length >= 2) {
+      elems = args;
+    } else {
+      throw new Error(
+        "Variance: GPU target requires a List argument or at least 2 scalar arguments"
+      );
+    }
+    const n = elems.length;
+    if (n < 2) throw new Error("Variance: need at least 2 elements");
+    const compiled = elems.map((e) => compile2(e));
+    const sum = compiled.join(" + ");
+    const mean2 = `((${sum}) / ${formatGPUNumber(n)})`;
+    const sqDiffs = compiled.map((c) => `(${c} - ${mean2}) * (${c} - ${mean2})`).join(" + ");
+    return `((${sqDiffs}) / ${formatGPUNumber(n - 1)})`;
+  },
+  /**
+   * Median of a compile-time-known list.
+   *
+   * Accepts either a single `List(...)` argument or N scalar arguments.
+   * For N ≤ 8: generates a fully unrolled inline sorting network followed by
+   * a middle-element pick. For larger N, throws (too large to inline cleanly).
+   *
+   * The sorting network uses the "odd-even merge sort" comparator pattern
+   * inlined as `min`/`max` calls — no GPU statements required.
+   */
+  Median: (args, compile2) => {
+    let elems;
+    if (args.length === 1 && isFunction2(args[0], "List")) {
+      elems = args[0].ops;
+    } else if (args.length >= 1) {
+      elems = args;
+    } else {
+      throw new Error(
+        "Median: GPU target requires a List argument or at least 1 scalar argument"
+      );
+    }
+    const n = elems.length;
+    if (n === 0) throw new Error("Median: empty list");
+    if (n > 8) {
+      throw new Error(
+        `Median: GPU target supports up to 8 elements via inline sorting network (got ${n}). For larger lists, compute on the CPU and pass the result as a uniform.`
+      );
+    }
+    const compiled = elems.map((e) => compile2(e));
+    if (n === 1) return compiled[0];
+    return `_gpu_median_${n}(${compiled.join(", ")})`;
+  },
+  /**
+   * Deterministic pseudorandom for GPU.
+   *
+   * All emitted forms return a GLSL `float` (or WGSL `f32`) so the result
+   * composes with surrounding float arithmetic without explicit casts. The
+   * "integer-bound" forms return an integer-valued float (the result of
+   * `floor`), matching the convention used by `Floor` and other ostensibly
+   * integer-returning operators in this target.
+   *
+   * - 0 args (GLSL only): fall back to a fragment-coord-derived seed.
+   *   Only meaningful in fragment shaders (gl_FragCoord is FS-only).
+   * - 0 args (WGSL): throws — WGSL has no built-in fragment coordinate;
+   *   caller must provide an explicit seed.
+   * - 1 arg, real-typed: `_gpu_random(seed)` — deterministic float in [0, 1)
+   * - 1 arg, integer-typed: `floor(_gpu_random(float(n)) * float(n))` —
+   *   integer-valued float in {0, 1, ..., n-1}. The seed is derived from
+   *   `n` itself, so the result is per-pixel-and-n deterministic in GLSL.
+   * - 2 args (integer m, n): float in [m, n), seeded from gl_FragCoord.
+   *
+   * JS-side `Random` has matching semantics (see `library/core.ts`'s
+   * polymorphic dispatch). JS↔GLSL parity is approximate — same seed yields
+   * a similar value, not bit-identical, due to fp64 vs fp32 and platform
+   * `sin` differences.
+   */
+  Random: (args, compile2, target) => {
+    if (args.length === 0) {
+      if (target.language === "wgsl") {
+        throw new Error(
+          "Random(): WGSL compile requires an explicit seed argument. WGSL has no gl_FragCoord built-in outside fragment entry points, so the no-arg fallback used in GLSL is unavailable. Use Random(seed) where seed is a deterministic per-invocation value."
+        );
+      }
+      return "_gpu_random(gl_FragCoord.x + gl_FragCoord.y * 1024.0)";
+    }
+    if (args.length === 1) {
+      const arg = args[0];
+      if (BaseCompiler.isIntegerValued(arg)) {
+        const compiled = compile2(arg);
+        return `floor(_gpu_random(float(${compiled})) * float(${compiled}))`;
+      }
+      return `_gpu_random(${compile2(arg)})`;
+    }
+    if (args.length === 2) {
+      if (target.language === "wgsl") {
+        throw new Error(
+          "Random(m, n): WGSL compile requires explicit seeding. Use a seeded variant or compute the integer range manually."
+        );
+      }
+      const m = compile2(args[0]);
+      const n = compile2(args[1]);
+      const seed = "_gpu_random(gl_FragCoord.x + gl_FragCoord.y * 1024.0)";
+      return `(float(${m}) + floor(${seed} * float((${n}) - (${m}))))`;
+    }
+    throw new Error("Random: GPU compile expects 0, 1, or 2 arguments");
+  },
   // Function (lambda) — not supported in GPU
   Function: () => {
     throw new Error(
@@ -22894,6 +23319,212 @@ fn _fractal_julia(z_in: vec2f, c: vec2f, maxIter: i32) -> f32 {
   return 1.0;
 }
 `;
+var GPU_GCD_PREAMBLE_GLSL = `
+float _gpu_gcd(float a, float b) {
+  a = abs(a); b = abs(b);
+  for (int i = 0; i < 32; i++) {
+    if (b < 0.5) break;
+    float t = mod(a, b);
+    a = b;
+    b = t;
+  }
+  return a;
+}
+`;
+var GPU_GCD_PREAMBLE_WGSL = `
+fn _gpu_gcd(a_in: f32, b_in: f32) -> f32 {
+  var a = abs(a_in); var b = abs(b_in);
+  for (var i: i32 = 0; i < 32; i++) {
+    if (b < 0.5) { break; }
+    let t = a % b;
+    a = b;
+    b = t;
+  }
+  return a;
+}
+`;
+var GPU_RANDOM_PREAMBLE_GLSL = `
+// Deterministic pseudorandom in [0, 1) from a float seed.
+// Standard fract-sin hash; reproducible across runs for the same seed.
+// Note: this hash exhibits visible banding near seed \u2248 k\u03C0 for integer k.
+// For high-quality shader random, callers should use a more robust hash
+// (e.g. PCG or xxHash) and pre-seed it appropriately.
+float _gpu_random(float seed) {
+  return fract(sin(seed * 12.9898) * 43758.5453);
+}
+`;
+var GPU_RANDOM_PREAMBLE_WGSL = `
+// Deterministic pseudorandom in [0, 1) from a float seed.
+// Standard fract-sin hash; reproducible across runs for the same seed.
+// Note: this hash exhibits visible banding near seed \u2248 k\u03C0 for integer k.
+// For high-quality shader random, callers should use a more robust hash
+// (e.g. PCG or xxHash) and pre-seed it appropriately.
+fn _gpu_random(seed: f32) -> f32 {
+  return fract(sin(seed * 12.9898) * 43758.5453);
+}
+`;
+var GPU_MEDIAN_PREAMBLE_GLSL = `
+float _gpu_median_2(float a, float b) {
+  return (a + b) * 0.5;
+}
+float _gpu_median_3(float a, float b, float c) {
+  return max(min(a, b), min(max(a, b), c));
+}
+float _gpu_median_4(float a, float b, float c, float d) {
+  float lo = max(min(a, b), min(c, d));
+  float hi = min(max(a, b), max(c, d));
+  return (lo + hi) * 0.5;
+}
+float _gpu_median_5(float a, float b, float c, float d, float e) {
+  // 9-comparator Bose-Nelson sort; v2 holds the median.
+  float t; float v0=a,v1=b,v2=c,v3=d,v4=e;
+  t=min(v0,v1); v1=max(v0,v1); v0=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  t=min(v2,v4); v4=max(v2,v4); v2=t;
+  t=min(v2,v3); v3=max(v2,v3); v2=t;
+  t=min(v0,v3); v3=max(v0,v3); v0=t;
+  t=min(v0,v2); v2=max(v0,v2); v0=t;
+  t=min(v1,v4); v4=max(v1,v4); v1=t;
+  t=min(v1,v3); v3=max(v1,v3); v1=t;
+  t=min(v1,v2); v2=max(v1,v2); v1=t;
+  return v2;
+}
+float _gpu_median_6(float a, float b, float c, float d, float e, float f) {
+  float t; float v0=a,v1=b,v2=c,v3=d,v4=e,v5=f;
+  t=min(v0,v1); v1=max(v0,v1); v0=t;
+  t=min(v2,v3); v3=max(v2,v3); v2=t;
+  t=min(v4,v5); v5=max(v4,v5); v4=t;
+  t=min(v0,v2); v2=max(v0,v2); v0=t;
+  t=min(v1,v3); v3=max(v1,v3); v1=t;
+  t=min(v0,v4); v4=max(v0,v4); v0=t;
+  t=min(v1,v5); v5=max(v1,v5); v1=t;
+  t=min(v2,v4); v4=max(v2,v4); v2=t;
+  t=min(v1,v2); v2=max(v1,v2); v1=t;
+  t=min(v3,v5); v5=max(v3,v5); v3=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  return (v2 + v3) * 0.5;
+}
+float _gpu_median_7(float a, float b, float c, float d, float e, float f, float g) {
+  float t; float v0=a,v1=b,v2=c,v3=d,v4=e,v5=f,v6=g;
+  t=min(v0,v1); v1=max(v0,v1); v0=t;
+  t=min(v2,v3); v3=max(v2,v3); v2=t;
+  t=min(v4,v5); v5=max(v4,v5); v4=t;
+  t=min(v0,v2); v2=max(v0,v2); v0=t;
+  t=min(v1,v3); v3=max(v1,v3); v1=t;
+  t=min(v4,v6); v6=max(v4,v6); v4=t;
+  t=min(v0,v4); v4=max(v0,v4); v0=t;
+  t=min(v1,v5); v5=max(v1,v5); v1=t;
+  t=min(v2,v6); v6=max(v2,v6); v2=t;
+  t=min(v1,v2); v2=max(v1,v2); v1=t;
+  t=min(v3,v5); v5=max(v3,v5); v3=t;
+  t=min(v2,v4); v4=max(v2,v4); v2=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  return v3;
+}
+float _gpu_median_8(float a, float b, float c, float d, float e, float f, float g, float h) {
+  float t; float v0=a,v1=b,v2=c,v3=d,v4=e,v5=f,v6=g,v7=h;
+  t=min(v0,v1); v1=max(v0,v1); v0=t;
+  t=min(v2,v3); v3=max(v2,v3); v2=t;
+  t=min(v4,v5); v5=max(v4,v5); v4=t;
+  t=min(v6,v7); v7=max(v6,v7); v6=t;
+  t=min(v0,v2); v2=max(v0,v2); v0=t;
+  t=min(v1,v3); v3=max(v1,v3); v1=t;
+  t=min(v4,v6); v6=max(v4,v6); v4=t;
+  t=min(v5,v7); v7=max(v5,v7); v5=t;
+  t=min(v0,v4); v4=max(v0,v4); v0=t;
+  t=min(v1,v5); v5=max(v1,v5); v1=t;
+  t=min(v2,v6); v6=max(v2,v6); v2=t;
+  t=min(v3,v7); v7=max(v3,v7); v3=t;
+  t=min(v1,v2); v2=max(v1,v2); v1=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  t=min(v5,v6); v6=max(v5,v6); v5=t;
+  t=min(v3,v5); v5=max(v3,v5); v3=t;
+  t=min(v2,v4); v4=max(v2,v4); v2=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  return (v3 + v4) * 0.5;
+}
+`;
+var GPU_MEDIAN_PREAMBLE_WGSL = `
+fn _gpu_median_2(a: f32, b: f32) -> f32 {
+  return (a + b) * 0.5;
+}
+fn _gpu_median_3(a: f32, b: f32, c: f32) -> f32 {
+  return max(min(a, b), min(max(a, b), c));
+}
+fn _gpu_median_4(a: f32, b: f32, c: f32, d: f32) -> f32 {
+  let lo = max(min(a, b), min(c, d));
+  let hi = min(max(a, b), max(c, d));
+  return (lo + hi) * 0.5;
+}
+fn _gpu_median_5(a: f32, b: f32, c: f32, d: f32, e: f32) -> f32 {
+  // 9-comparator Bose-Nelson sort; v2 holds the median.
+  var v0=a; var v1=b; var v2=c; var v3=d; var v4=e; var t: f32;
+  t=min(v0,v1); v1=max(v0,v1); v0=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  t=min(v2,v4); v4=max(v2,v4); v2=t;
+  t=min(v2,v3); v3=max(v2,v3); v2=t;
+  t=min(v0,v3); v3=max(v0,v3); v0=t;
+  t=min(v0,v2); v2=max(v0,v2); v0=t;
+  t=min(v1,v4); v4=max(v1,v4); v1=t;
+  t=min(v1,v3); v3=max(v1,v3); v1=t;
+  t=min(v1,v2); v2=max(v1,v2); v1=t;
+  return v2;
+}
+fn _gpu_median_6(a: f32, b: f32, c: f32, d: f32, e: f32, f: f32) -> f32 {
+  var v0=a; var v1=b; var v2=c; var v3=d; var v4=e; var v5=f; var t: f32;
+  t=min(v0,v1); v1=max(v0,v1); v0=t;
+  t=min(v2,v3); v3=max(v2,v3); v2=t;
+  t=min(v4,v5); v5=max(v4,v5); v4=t;
+  t=min(v0,v2); v2=max(v0,v2); v0=t;
+  t=min(v1,v3); v3=max(v1,v3); v1=t;
+  t=min(v0,v4); v4=max(v0,v4); v0=t;
+  t=min(v1,v5); v5=max(v1,v5); v1=t;
+  t=min(v2,v4); v4=max(v2,v4); v2=t;
+  t=min(v1,v2); v2=max(v1,v2); v1=t;
+  t=min(v3,v5); v5=max(v3,v5); v3=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  return (v2 + v3) * 0.5;
+}
+fn _gpu_median_7(a: f32, b: f32, c: f32, d: f32, e: f32, f: f32, g: f32) -> f32 {
+  var v0=a; var v1=b; var v2=c; var v3=d; var v4=e; var v5=f; var v6=g; var t: f32;
+  t=min(v0,v1); v1=max(v0,v1); v0=t;
+  t=min(v2,v3); v3=max(v2,v3); v2=t;
+  t=min(v4,v5); v5=max(v4,v5); v4=t;
+  t=min(v0,v2); v2=max(v0,v2); v0=t;
+  t=min(v1,v3); v3=max(v1,v3); v1=t;
+  t=min(v4,v6); v6=max(v4,v6); v4=t;
+  t=min(v0,v4); v4=max(v0,v4); v0=t;
+  t=min(v1,v5); v5=max(v1,v5); v1=t;
+  t=min(v2,v6); v6=max(v2,v6); v2=t;
+  t=min(v1,v2); v2=max(v1,v2); v1=t;
+  t=min(v3,v5); v5=max(v3,v5); v3=t;
+  t=min(v2,v4); v4=max(v2,v4); v2=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  return v3;
+}
+fn _gpu_median_8(a: f32, b: f32, c: f32, d: f32, e: f32, f: f32, g: f32, h: f32) -> f32 {
+  var v0=a; var v1=b; var v2=c; var v3=d; var v4=e; var v5=f; var v6=g; var v7=h; var t: f32;
+  t=min(v0,v1); v1=max(v0,v1); v0=t;
+  t=min(v2,v3); v3=max(v2,v3); v2=t;
+  t=min(v4,v5); v5=max(v4,v5); v4=t;
+  t=min(v6,v7); v7=max(v6,v7); v6=t;
+  t=min(v0,v2); v2=max(v0,v2); v0=t;
+  t=min(v1,v3); v3=max(v1,v3); v1=t;
+  t=min(v4,v6); v6=max(v4,v6); v4=t;
+  t=min(v5,v7); v7=max(v5,v7); v5=t;
+  t=min(v0,v4); v4=max(v0,v4); v0=t;
+  t=min(v1,v5); v5=max(v1,v5); v1=t;
+  t=min(v2,v6); v6=max(v2,v6); v2=t;
+  t=min(v3,v7); v7=max(v3,v7); v3=t;
+  t=min(v1,v2); v2=max(v1,v2); v1=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  t=min(v5,v6); v6=max(v5,v6); v5=t;
+  t=min(v3,v5); v5=max(v3,v5); v3=t;
+  t=min(v2,v4); v4=max(v2,v4); v2=t;
+  t=min(v3,v4); v4=max(v3,v4); v3=t;
+  return (v3 + v4) * 0.5;
+}
+`;
 var GPU_COLOR_PREAMBLE_GLSL = `
 float _gpu_srgb_to_linear(float c) {
   if (c <= 0.04045) return c / 12.92;
@@ -23571,6 +24202,12 @@ var GPUShaderTarget = class {
     if (code.includes("_fractal_")) {
       preamble += this.languageId === "wgsl" ? GPU_FRACTAL_PREAMBLE_WGSL : GPU_FRACTAL_PREAMBLE_GLSL;
     }
+    if (code.includes("_gpu_random"))
+      preamble += this.languageId === "wgsl" ? GPU_RANDOM_PREAMBLE_WGSL : GPU_RANDOM_PREAMBLE_GLSL;
+    if (code.includes("_gpu_gcd"))
+      preamble += this.languageId === "wgsl" ? GPU_GCD_PREAMBLE_WGSL : GPU_GCD_PREAMBLE_GLSL;
+    if (code.includes("_gpu_median_"))
+      preamble += this.languageId === "wgsl" ? GPU_MEDIAN_PREAMBLE_WGSL : GPU_MEDIAN_PREAMBLE_GLSL;
     if (code.includes("_gpu_srgb_to") || code.includes("_gpu_oklab") || code.includes("_gpu_oklch") || code.includes("_gpu_color_mix") || code.includes("_gpu_apca")) {
       preamble += this.languageId === "wgsl" ? GPU_COLOR_PREAMBLE_WGSL : GPU_COLOR_PREAMBLE_GLSL;
     }
@@ -25909,7 +26546,7 @@ function compileToIntervalTarget(expr, target) {
 }
 
 // src/compile.ts
-var version = "0.57.0";
+var version = "0.58.0";
 export {
   BaseCompiler,
   GLSLTarget,