@cortex-js/compute-engine 0.57.0 → 0.58.0

package/dist/compile.umd.cjs

@@ -1,4 +1,4 @@
-/** Compile 0.57.0 */
+/** Compile 0.58.0 */
     (function(global,factory){typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) : typeof define === 'function' && define.amd ? define(['exports'],factory):(global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.Compile = {}));})(this, (function (exports) { 'use strict';
 var Compile = (() => {
   var __defProp = Object.defineProperty;
@@ -3568,7 +3568,42 @@ var Compile = (() => {
     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";
@@ -3642,7 +3677,7 @@ var Compile = (() => {
     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)))}>`
@@ -5544,15 +5579,16 @@ var Compile = (() => {
       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",
@@ -5563,7 +5599,7 @@ var Compile = (() => {
       latexTrigger: "\\colon",
       kind: "infix",
       associativity: "right",
-      precedence: 250,
+      precedence: 240,
       parse: "Colon"
     },
     {
@@ -7133,7 +7169,10 @@ var Compile = (() => {
         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 = [];
@@ -7174,6 +7213,25 @@ var Compile = (() => {
       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);
@@ -7387,6 +7445,17 @@ var Compile = (() => {
     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
@@ -7645,18 +7714,58 @@ var Compile = (() => {
       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") {
@@ -9630,7 +9739,8 @@ var Compile = (() => {
         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];
     };
   }
@@ -11753,10 +11863,17 @@ var Compile = (() => {
     // 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
@@ -12947,6 +13064,15 @@ ${lines.join("\n")}`;
     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;
@@ -12996,6 +13122,19 @@ ${lines.join("\n")}`;
         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,
@@ -13249,10 +13388,12 @@ ${lines.join("\n")}`;
           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) => {
@@ -13271,6 +13412,8 @@ ${lines.join("\n")}`;
               !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: () => {
@@ -13279,7 +13422,7 @@ ${lines.join("\n")}`;
               index += 1;
               return {
                 value: expr.engine.number(
-                  lower + (upper - lower) * (index - 1 - 1) / totalCount
+                  lower + (upper - lower) * (index - 1 - 1) / denom
                 ),
                 done: false
               };
@@ -13295,9 +13438,14 @@ ${lines.join("\n")}`;
           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;
         }
       }
     },
@@ -13622,10 +13770,12 @@ ${lines.join("\n")}`;
       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];
@@ -13636,12 +13786,39 @@ ${lines.join("\n")}`;
           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;
@@ -13652,7 +13829,7 @@ ${lines.join("\n")}`;
       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);
@@ -13699,7 +13876,7 @@ ${lines.join("\n")}`;
       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) => {
@@ -13895,7 +14072,9 @@ ${lines.join("\n")}`;
       ],
       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) => {
@@ -14227,16 +14406,26 @@ ${lines.join("\n")}`;
     },
     // 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);
       }
@@ -14303,7 +14492,9 @@ ${lines.join("\n")}`;
         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 }) => {
@@ -14319,7 +14510,7 @@ ${lines.join("\n")}`;
       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]);
@@ -14331,7 +14522,7 @@ ${lines.join("\n")}`;
       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);
@@ -14505,32 +14696,74 @@ ${lines.join("\n")}`;
         }
       }
     },
-    // 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;
         }
       }
@@ -15239,6 +15472,13 @@ ${lines.join("\n")}`;
      *    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");
@@ -20326,6 +20566,7 @@ ${lines.join("\n")}`;
         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])})`;
@@ -20484,7 +20725,20 @@ ${lines.join("\n")}`;
       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])})`;
@@ -20512,6 +20766,7 @@ ${lines.join("\n")}`;
       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",
@@ -20544,6 +20799,7 @@ ${lines.join("\n")}`;
         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);
@@ -21823,6 +22079,14 @@ ${lines.join("\n")}`;
       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])})`;
@@ -22300,6 +22564,39 @@ ${lines.join("\n")}`;
     // 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");
@@ -22328,6 +22625,134 @@ ${lines.join("\n")}`;
   ${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(
@@ -22926,6 +23351,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) {
@@ -23604,6 +24235,12 @@ fn _gpu_apca(lch_bg: vec3f, lch_fg: vec3f) -> f32 {
       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;
       }
@@ -25942,7 +26579,7 @@ ${code}`;
   }
 
   // src/compile.ts
-  var version = "0.57.0";
+  var version = "0.58.0";
   return __toCommonJS(compile_exports);
 })();
 /*! Bundled license information: