@scriptc/compiler 0.1.4 → 0.1.6

package/dist/frontend/lowering/lower-containers.js

@@ -14,8 +14,36 @@ import { islandPrimitiveExit, lowerDynDispatchMethodCall } from "./lower-calls.j
 import { buildArraySortFn } from "./lower-array-sort.js";
 import { arrayIndexPresent, arrayValueRead, arrayValueStore, arrayValueType, currentArrayIndexPresent } from "./array-values.js";
 import { typeKey } from "../type-mapper.js";
-import { boolLit, countedFor, numLit, varRef } from "../../ir/build.js";
-import { lowerOptionalArgument } from "./optional-arguments.js";
+import { boolLit, countedFor, numLit, strLit, varRef } from "../../ir/build.js";
+import { defaultAfterUndefined, lowerPositionArgument, lowerStaticallyUndefinedArgument, positionNumber } from "./optional-arguments.js";
+import { lowerArrayCopyWithin, lowerArrayFill } from "./array-indexed-mutation.js";
+function primitivePositionType(lowerer, type) {
+    if (type.kind === "union") {
+        return lowerer.unions.get(type.unionId)?.arms.every((arm) => primitivePositionType(lowerer, arm)) ?? false;
+    }
+    return type.kind === "f64" || type.kind === "string" || type.kind === "bool" ||
+        type.kind === "nullT" || type.kind === "undefinedT";
+}
+function lowerArrayPosition(lowerer, node, defaultValue, subject) {
+    if (!node)
+        return defaultValue;
+    if (ts.isSpreadElement(node))
+        lowerer.noLowering(`${subject} with a spread argument`, node);
+    const value = lowerPositionArgument(lowerer, node, defaultValue);
+    if (!primitivePositionType(lowerer, value.type)) {
+        lowerer.noLowering(`${subject} of '${lowerer.fmt(value.type)}' values`, node);
+    }
+    const loc = locOf(node);
+    const local = lowerer.declareHiddenLocal("%arrayPosition", value.type);
+    const ref = varRef(local.id, value.type, loc);
+    return {
+        kind: "seqExpr",
+        stmts: [{ kind: "varDecl", localId: local.id, init: value, loc }],
+        result: positionNumber(lowerer, ref, defaultValue, node, subject),
+        type: F64,
+        loc,
+    };
+}
 /** Build the argument array for a mutating/copying operation while keeping
  * the receiver's scalar payload ABI. A missing read is represented as the
  * present UNDEFINED state in this temporary, so push/unshift and toSpliced
@@ -42,6 +70,68 @@ function lowerArrayValueItems(lowerer, values, elem, arrType, loc) {
     }
     return { kind: "seqExpr", stmts: body, result: outRef, type: arrType, loc };
 }
+function lowerArraySpreadItems(lowerer, nodes, elem, arrType, loc) {
+    const out = lowerer.declareHiddenLocal("%arrayItems", arrType);
+    const outRef = varRef(out.id, arrType, loc);
+    const length = () => ({ kind: "arrIntrinsic", method: "length", receiver: outRef, args: [], type: F64, loc });
+    const body = [
+        { kind: "varDecl", localId: out.id, init: { kind: "arrayLit", elems: [], type: arrType, loc }, loc },
+    ];
+    for (const node of nodes) {
+        if (ts.isSpreadElement(node)) {
+            const source = lowerer.lowerExpr(node.expression);
+            if (!typeEquals(source.type, arrType)) {
+                lowerer.noLowering(`Array insertion spread from '${lowerer.fmt(source.type)}'`, node);
+            }
+            body.push({
+                kind: "exprStmt",
+                expr: { kind: "arrIntrinsic", method: "pushSpread", receiver: outRef, args: [source], type: F64, loc },
+                loc,
+            });
+        }
+        else {
+            const value = lowerer.lowerExpr(node);
+            const stored = lowerer.runtimeOptionalWidening(value.type, elem) !== null
+                ? value : lowerer.coerceInto(node, value, elem);
+            body.push(arrayValueStore(lowerer, outRef, length(), stored, elem, loc));
+        }
+    }
+    return { kind: "seqExpr", stmts: body, result: outRef, type: arrType, loc };
+}
+function lowerArrayJoinSeparator(lowerer, node, loc) {
+    const comma = strLit(",", loc);
+    if (!node)
+        return comma;
+    const undefinedValue = lowerStaticallyUndefinedArgument(lowerer, node);
+    if (undefinedValue)
+        return defaultAfterUndefined(undefinedValue, comma);
+    const value = lowerer.lowerExpr(node);
+    if (value.type.kind === "nullT")
+        return defaultAfterUndefined(value, strLit("null", loc));
+    if (value.type.kind === "union") {
+        const undefinedTag = lowerer.armTag(value.type.unionId, UNDEFINED_T);
+        if (undefinedTag >= 0) {
+            const local = lowerer.declareHiddenLocal("%joinSeparator", value.type);
+            const ref = varRef(local.id, value.type, loc);
+            return {
+                kind: "seqExpr",
+                stmts: [{ kind: "varDecl", localId: local.id, init: value, loc }],
+                result: {
+                    kind: "ternary",
+                    cond: { kind: "unionIsTag", unionId: value.type.unionId, tag: undefinedTag, value: ref, negated: false, type: BOOL, loc },
+                    then: comma,
+                    else_: lowerer.ensureString(ref, node),
+                    type: STRING, loc,
+                },
+                type: STRING, loc,
+            };
+        }
+    }
+    if (value.type.kind === "dyn" || value.type.kind === "jsval") {
+        lowerer.noLowering(".join separator with a runtime-dependent undefined value", node);
+    }
+    return lowerer.ensureString(value, node);
+}
 /** Callback-driven array producers bypass mapType's ordinary T[] mapping:
  * the callback is lowered first, then the helper's result array is built
  * directly from its IR return type. Fence element kinds ScrArr cannot hold
@@ -181,24 +271,51 @@ export function lowerArrayMethodCall(lowerer, call, access) {
             loc,
         };
     }
+    if (name === "fill") {
+        if (call.arguments.length > 3 || call.arguments.some(ts.isSpreadElement)) {
+            lowerer.noLowering(`.fill with ${call.arguments.length} arguments`, call);
+        }
+        const value = call.arguments[0] ? lowerer.lowerExpr(call.arguments[0]) : null;
+        if (value && (value.type.kind === "dyn" || value.type.kind === "jsval") &&
+            isRefCounted(elem) && elem.kind !== "string" && !typeEquals(value.type, elem)) {
+            lowerer.noLowering(".fill of a checked-dynamic reference into a static array", call.arguments[0]);
+        }
+        const writeUndefined = value === null || value.type.kind === "undefinedT";
+        return lowerArrayFill(lowerer, lowerer.lowerExpr(access.expression), value, writeUndefined, lowerArrayPosition(lowerer, call.arguments[1], numLit(0, loc), "array fill start"), lowerArrayPosition(lowerer, call.arguments[2], numLit(Infinity, loc), "array fill end"), receiverIr, loc);
+    }
+    if (name === "copyWithin") {
+        if (call.arguments.length > 3 || call.arguments.some(ts.isSpreadElement)) {
+            lowerer.noLowering(`.copyWithin with ${call.arguments.length} arguments`, call);
+        }
+        return lowerArrayCopyWithin(lowerer, lowerer.lowerExpr(access.expression), lowerArrayPosition(lowerer, call.arguments[0], numLit(0, loc), "array copyWithin target"), lowerArrayPosition(lowerer, call.arguments[1], numLit(0, loc), "array copyWithin start"), lowerArrayPosition(lowerer, call.arguments[2], numLit(Infinity, loc), "array copyWithin end"), receiverIr, loc);
+    }
     if (name === "with") {
         if (call.arguments.length !== 2 || call.arguments.some(ts.isSpreadElement)) {
             lowerer.noLowering(`.with with ${call.arguments.length} arguments`, call);
         }
         const receiver = lowerer.lowerExpr(access.expression);
-        const index = lowerer.lowerExprExpecting(call.arguments[0], F64);
+        const index = lowerPositionArgument(lowerer, call.arguments[0], numLit(0, loc));
+        if (!primitivePositionType(lowerer, index.type)) {
+            lowerer.noLowering(`.with index of '${lowerer.fmt(index.type)}' values`, call.arguments[0]);
+        }
         const value = lowerer.lowerExpr(call.arguments[1]);
+        const receiverLocal = lowerer.declareHiddenLocal("%withRecv", receiverIr);
+        const indexLocal = lowerer.declareHiddenLocal("%withIndex", index.type);
+        const valueLocal = lowerer.declareHiddenLocal("%withValue", value.type);
+        const receiverRef = varRef(receiverLocal.id, receiverIr, loc);
+        const indexRef = varRef(indexLocal.id, index.type, loc);
+        const valueRef = varRef(valueLocal.id, value.type, loc);
+        const numericIndex = positionNumber(lowerer, indexRef, numLit(0, loc), call.arguments[0], "array with index");
+        const stmts = [
+            { kind: "varDecl", localId: receiverLocal.id, init: receiver, loc },
+            { kind: "varDecl", localId: indexLocal.id, init: index, loc },
+            { kind: "varDecl", localId: valueLocal.id, init: value, loc },
+        ];
         if (value.type.kind === "union" && lowerer.runtimeOptionalWidening(value.type, elem) !== null) {
             // `.with()` validates its index and returns a fresh copy. Stabilize
             // all three operands, then select the scalar replacement or the
             // present-undefined copy without evaluating a read twice.
-            const receiverLocal = lowerer.declareHiddenLocal("%withRecv", receiverIr);
-            const indexLocal = lowerer.declareHiddenLocal("%withIndex", F64);
-            const valueLocal = lowerer.declareHiddenLocal("%withValue", value.type);
             const unionId = value.type.unionId;
-            const receiverRef = varRef(receiverLocal.id, receiverIr, loc);
-            const indexRef = varRef(indexLocal.id, F64, loc);
-            const valueRef = varRef(valueLocal.id, value.type, loc);
             const undefTag = lowerer.armTag(unionId, UNDEFINED_T);
             const condition = {
                 kind: "unionIsTag",
@@ -213,7 +330,7 @@ export function lowerArrayMethodCall(lowerer, call, access) {
                 kind: "arrIntrinsic",
                 method: "withUndefined",
                 receiver: receiverRef,
-                args: [indexRef],
+                args: [numericIndex],
                 type: receiverIr,
                 loc,
             };
@@ -221,62 +338,45 @@ export function lowerArrayMethodCall(lowerer, call, access) {
                 kind: "arrIntrinsic",
                 method: "with",
                 receiver: receiverRef,
-                args: [indexRef, lowerer.coerceToExpected(valueRef, elem)],
+                args: [numericIndex, lowerer.coerceToExpected(valueRef, elem)],
                 type: receiverIr,
                 loc,
             };
             return {
                 kind: "seqExpr",
-                stmts: [
-                    { kind: "varDecl", localId: receiverLocal.id, init: receiver, loc },
-                    { kind: "varDecl", localId: indexLocal.id, init: index, loc },
-                    { kind: "varDecl", localId: valueLocal.id, init: value, loc },
-                ],
+                stmts,
                 result: { kind: "ternary", cond: condition, then: missing, else_: present, type: receiverIr, loc },
                 type: receiverIr,
                 loc,
             };
         }
-        const coercedValue = lowerer.coerceInto(call.arguments[1], value, elem);
+        const coercedValue = lowerer.coerceInto(call.arguments[1], valueRef, elem);
         return {
-            kind: "arrIntrinsic",
-            method: "with",
-            receiver,
-            args: [index, coercedValue],
+            kind: "seqExpr",
+            stmts,
+            result: { kind: "arrIntrinsic", method: "with", receiver: receiverRef, args: [numericIndex, coercedValue], type: receiverIr, loc },
             type: receiverIr,
             loc,
         };
     }
     if (name === "toSpliced") {
-        if (call.arguments.some(ts.isSpreadElement)) {
-            lowerer.unsupported("SC1090", call, "spread arguments to Array.toSpliced");
-        }
         const receiver = lowerer.lowerExpr(access.expression);
-        const start = call.arguments[0]
-            ? lowerer.lowerExprExpecting(call.arguments[0], F64)
-            : { kind: "numLit", value: 0, type: F64, loc };
-        const deleteCountDefault = {
-            kind: "numLit",
-            value: NaN,
-            type: F64,
-            loc,
-        };
-        const deleteCount = call.arguments.length === 0
-            ? { kind: "numLit", value: 0, type: F64, loc }
-            : call.arguments[1]
-                ? lowerOptionalArgument(lowerer, call.arguments[1], F64, deleteCountDefault)
-                : { kind: "numLit", value: Infinity, type: F64, loc };
+        const start = lowerArrayPosition(lowerer, call.arguments[0], numLit(0, loc), "array toSpliced start");
+        const deleteCount = lowerArrayPosition(lowerer, call.arguments[1], numLit(call.arguments.length === 1 ? Infinity : 0, loc), "array toSpliced deleteCount");
         const itemNodes = call.arguments.slice(2);
-        const itemProbes = itemNodes.map((arg) => tryLowerExpression(lowerer, arg));
+        const hasSpread = itemNodes.some(ts.isSpreadElement);
+        const itemProbes = hasSpread ? [] : itemNodes.map((arg) => tryLowerExpression(lowerer, arg));
         const statefulItems = itemProbes.some((probe) => probe !== null && lowerer.runtimeOptionalWidening(probe.type, elem) !== null);
-        const items = statefulItems
-            ? lowerArrayValueItems(lowerer, itemNodes.map((arg) => lowerer.lowerExpr(arg)), elem, receiverIr, loc)
-            : {
-                kind: "arrayLit",
-                elems: itemNodes.map((arg) => lowerer.coerceInto(arg, lowerer.lowerExpr(arg), elem)),
-                type: receiverIr,
-                loc,
-            };
+        const items = hasSpread
+            ? lowerArraySpreadItems(lowerer, itemNodes, elem, receiverIr, loc)
+            : statefulItems
+                ? lowerArrayValueItems(lowerer, itemNodes.map((arg) => lowerer.lowerExpr(arg)), elem, receiverIr, loc)
+                : {
+                    kind: "arrayLit",
+                    elems: itemNodes.map((arg) => lowerer.coerceInto(arg, lowerer.lowerExpr(arg), elem)),
+                    type: receiverIr,
+                    loc,
+                };
         return {
             kind: "arrIntrinsic",
             method: "toSpliced",
@@ -286,32 +386,27 @@ export function lowerArrayMethodCall(lowerer, call, access) {
             loc,
         };
     }
-    // The lib declares wider call forms than the lowered surface —
-    // indexOf/includes take a fromIndex, join's separator is optional, the
+    if (name === "flat")
+        return lowerArrayFlatCall(lowerer, call, access, receiverIr);
+    // The lib declares wider call forms than the lowered surface — the
     // predicate/mapping HOFs take a thisArg. Each unlowered form is fenced
     // per site (SC2020), never silently truncated to the supported
     // arguments. push/unshift lower every declared form (variadic, 0 args
     // included — Node returns the unchanged length); reduce/reduceRight
     // lower both declared forms (with and without an initial value).
     const arity = {
-        push: [0, Number.MAX_SAFE_INTEGER], unshift: [0, Number.MAX_SAFE_INTEGER], pop: [0, 0], indexOf: [1, 1], includes: [1, 1], join: [1, 1],
+        push: [0, Number.MAX_SAFE_INTEGER], unshift: [0, Number.MAX_SAFE_INTEGER], pop: [0, 0], indexOf: [1, 2], lastIndexOf: [1, 2], includes: [0, 2], join: [0, 1],
         concat: [0, Number.MAX_SAFE_INTEGER],
-        slice: [0, 2], shift: [0, 0], splice: [1, 2], at: [1, 1],
+        slice: [0, 2], shift: [0, 0], splice: [0, Number.MAX_SAFE_INTEGER], at: [0, 1],
         map: [1, 1], filter: [1, 1], forEach: [1, 1], find: [1, 1], findIndex: [1, 1], some: [1, 1],
         findLast: [1, 1], findLastIndex: [1, 1],
         every: [1, 1], flatMap: [1, 1], reduce: [1, 2], reduceRight: [1, 2],
     }[name];
     if (call.arguments.length < arity[0] || call.arguments.length > arity[1]) {
-        const hint = name === "splice"
-            ? "the removal forms lower — splice(start, deleteCount?); to insert, build a new array with slice and push"
-            : name === "join"
-                ? 'pass the separator explicitly: join(",")'
-                : name === "indexOf" || name === "includes"
-                    ? "the fromIndex parameter has no lowering — slice first, or loop"
-                    : name === "map" || name === "filter" || name === "forEach" ||
-                        name === "find" || name === "some" || name === "every" || name === "flatMap"
-                        ? "the thisArg parameter has no lowering — use an arrow function"
-                        : undefined;
+        const hint = name === "map" || name === "filter" || name === "forEach" ||
+            name === "find" || name === "some" || name === "every" || name === "flatMap"
+            ? "the thisArg parameter has no lowering — use an arrow function"
+            : undefined;
         lowerer.noLowering(`.${name} with ${call.arguments.length} argument${call.arguments.length === 1 ? "" : "s"}`, call, hint);
     }
     if (name === "push" || name === "unshift") {
@@ -393,7 +488,7 @@ export function lowerArrayMethodCall(lowerer, call, access) {
             loc,
         };
     }
-    if (name === "indexOf" || name === "includes") {
+    if (name === "indexOf" || name === "lastIndexOf" || name === "includes") {
         return lowerArraySearchCall(lowerer, call, access, name, elem);
     }
     if (name === "concat") {
@@ -452,33 +547,37 @@ export function lowerArrayMethodCall(lowerer, call, access) {
         return { kind: "call", callee: helper, args: [receiver, ...args], type: receiverIr, loc };
     }
     if (name === "slice") {
-        // `a.slice(start?, end?)` — a fresh shallow copy of the index range,
-        // JS-exact index handling (ToIntegerOrInfinity, negatives from the
-        // end, clamping; omitted args are omitted from the IR — the backend
-        // fills 0 / +Infinity, the string-slice convention). Ref elements
-        // are RETAINED into the copy: the same references, exactly JS's
-        // shallow copy. Every element kind slices — the receiver's own type
-        // is the result type.
         const receiver = lowerer.lowerExpr(access.expression);
-        const args = call.arguments.map((a) => lowerer.lowerExpr(a));
-        for (let i = 0; i < args.length; i++) {
-            if (args[i].type.kind !== "f64")
-                lowerer.badType(call.arguments[i], lowerer.typeOf(call.arguments[i]));
-        }
+        const args = [
+            lowerArrayPosition(lowerer, call.arguments[0], numLit(0, loc), "array slice start"),
+            lowerArrayPosition(lowerer, call.arguments[1], numLit(Infinity, loc), "array slice end"),
+        ];
         return { kind: "arrIntrinsic", method: "slice", receiver, args, type: receiverIr, loc };
     }
     if (name === "splice") {
-        // The REMOVAL forms: splice(start) and splice(start, deleteCount) —
-        // Node-exact relative/clamped indices, the removed elements back in
-        // order (their ownership moves out of the receiver). Insertion
-        // (3+ args) fenced by arity above.
         const receiver = lowerer.lowerExpr(access.expression);
-        const args = call.arguments.map((a) => lowerer.lowerExpr(a));
-        for (let i = 0; i < args.length; i++) {
-            if (args[i].type.kind !== "f64")
-                lowerer.badType(call.arguments[i], lowerer.typeOf(call.arguments[i]));
+        const args = [
+            lowerArrayPosition(lowerer, call.arguments[0], numLit(0, loc), "array splice start"),
+            lowerArrayPosition(lowerer, call.arguments[1], numLit(call.arguments.length === 1 ? Infinity : 0, loc), "array splice deleteCount"),
+        ];
+        if (call.arguments.length <= 2) {
+            return { kind: "arrIntrinsic", method: "splice", receiver, args, type: receiverIr, loc };
         }
-        return { kind: "arrIntrinsic", method: "splice", receiver, args, type: receiverIr, loc };
+        const itemNodes = call.arguments.slice(2);
+        const hasSpread = itemNodes.some(ts.isSpreadElement);
+        const itemProbes = hasSpread ? [] : itemNodes.map((arg) => tryLowerExpression(lowerer, arg));
+        const statefulItems = itemProbes.some((probe) => probe !== null && lowerer.runtimeOptionalWidening(probe.type, elem) !== null);
+        const items = hasSpread
+            ? lowerArraySpreadItems(lowerer, itemNodes, elem, receiverIr, loc)
+            : statefulItems
+                ? lowerArrayValueItems(lowerer, itemNodes.map((arg) => lowerer.lowerExpr(arg)), elem, receiverIr, loc)
+                : {
+                    kind: "arrayLit",
+                    elems: itemNodes.map((arg) => lowerer.coerceInto(arg, lowerer.lowerExpr(arg), elem)),
+                    type: receiverIr,
+                    loc,
+                };
+        return { kind: "arrIntrinsic", method: "spliceInsert", receiver, args: [...args, items], type: receiverIr, loc };
     }
     if (name === "shift") {
         // JS shift exactly: undefined on an empty array, else the first
@@ -511,7 +610,7 @@ export function lowerArrayMethodCall(lowerer, call, access) {
             lowerer.unsupported("SC1090", call, "'.join()' on arrays of this element type (number, string, and boolean arrays join — unions of those with undefined/null arms too, the units printing empty like JS)");
         }
         const receiver = lowerer.lowerExpr(access.expression);
-        const sep = lowerer.lowerExpr(call.arguments[0]);
+        const sep = lowerArrayJoinSeparator(lowerer, call.arguments[0], loc);
         return { kind: "arrIntrinsic", method: "join", receiver, args: [sep], type: STRING, loc };
     }
     if (name === "map" || name === "filter" || name === "forEach") {
@@ -528,17 +627,99 @@ export function lowerArrayMethodCall(lowerer, call, access) {
     // reduce / reduceRight
     return lowerArrayReduceCall(lowerer, call, access, name, elem);
 }
+function literalFlatDepth(value) {
+    if (value.kind === "numLit")
+        return value.value;
+    if (value.kind === "strLit")
+        return Number(value.value);
+    if (value.kind === "boolLit")
+        return value.value ? 1 : 0;
+    if (value.kind === "unitLit")
+        return value.unit === "undefined" ? 1 : 0;
+    if (value.kind === "unary" && value.op === "-") {
+        const operand = literalFlatDepth(value.operand);
+        return operand === null ? null : -operand;
+    }
+    return null;
+}
+function lowerArrayFlatCall(lowerer, call, access, receiverType) {
+    const loc = locOf(call);
+    if (call.arguments.length > 1 || call.arguments.some(ts.isSpreadElement)) {
+        lowerer.noLowering(`.flat with ${call.arguments.length} arguments`, call);
+    }
+    const elemCouldNest = (elem) => elem.kind === "array" || elem.kind === "jsval" || elem.kind === "dyn" ||
+        (elem.kind === "union" && (lowerer.unions.get(elem.unionId)?.arms.some((arm) => arm.kind === "array" || arm.kind === "jsval" || arm.kind === "dyn") ?? true));
+    if (!elemCouldNest(receiverType.elem) && call.arguments[0]) {
+        const receiver = lowerer.lowerExpr(access.expression);
+        const depth = lowerArrayPosition(lowerer, call.arguments[0], numLit(1, loc), "array flat depth");
+        const local = lowerer.declareHiddenLocal("%flatReceiver", receiverType);
+        const ref = varRef(local.id, receiverType, loc);
+        return {
+            kind: "seqExpr",
+            stmts: [
+                { kind: "varDecl", localId: local.id, init: receiver, loc },
+                { kind: "exprStmt", expr: depth, loc },
+            ],
+            result: {
+                kind: "arrIntrinsic", method: "flatCopy", receiver: ref,
+                args: [{ kind: "arrayLit", elems: [], type: receiverType, loc }],
+                type: receiverType, loc,
+            },
+            type: receiverType, loc,
+        };
+    }
+    const depth = call.arguments[0] ? literalFlatDepth(lowerer.lowerExpr(call.arguments[0])) : 1;
+    if (depth === null)
+        lowerer.noLowering(".flat with a nonconstant depth", call);
+    let remaining = Number.isNaN(depth) || depth <= 0 ? 0 : Math.trunc(depth);
+    let result = lowerer.lowerExpr(access.expression);
+    let currentType = receiverType;
+    let flattened = false;
+    while (remaining > 0) {
+        const elem = currentType.elem;
+        if (elem.kind !== "array" && elemCouldNest(elem)) {
+            lowerer.noLowering(".flat over elements with runtime-dependent array shape", call);
+        }
+        if (elem.kind !== "array")
+            break;
+        result = {
+            kind: "arrIntrinsic", method: "flatOne", receiver: result,
+            args: [{ kind: "arrayLit", elems: [], type: elem, loc }],
+            type: elem, loc,
+        };
+        currentType = elem;
+        remaining--;
+        flattened = true;
+    }
+    if (!flattened) {
+        result = {
+            kind: "arrIntrinsic", method: "flatCopy", receiver: result,
+            args: [{ kind: "arrayLit", elems: [], type: currentType, loc }],
+            type: currentType, loc,
+        };
+    }
+    return result;
+}
 /** `indexOf` and `includes` normally use the runtime's typed search helpers,
  * but an indexed array read is a `T | undefined` value. Keep that union
  * through a small lowered loop so the needle's missing state is observable:
- * indexOf skips holes, while includes treats holes as undefined. The same
- * loop also gives union-element arrays their value equality rather than
- * comparing the compiler's union boxes by pointer. */
+ * indexOf and lastIndexOf skip holes, while includes treats holes as
+ * undefined. The same loop also gives union-element arrays their value
+ * equality rather than comparing the compiler's union boxes by pointer. */
 function lowerArraySearchCall(lowerer, call, access, method, elem) {
     const loc = locOf(call);
     const receiver = lowerer.lowerExpr(access.expression);
-    const argNode = call.arguments[0];
-    let needle = lowerer.lowerExpr(argNode);
+    const argNode = call.arguments[0] ?? call;
+    if (call.arguments.some(ts.isSpreadElement))
+        lowerer.noLowering(`.${method} with spread arguments`, call);
+    let needle = call.arguments[0]
+        ? lowerer.lowerExpr(call.arguments[0])
+        : { kind: "unitLit", unit: "undefined", type: UNDEFINED_T, loc };
+    const fromIndex = call.arguments[1]
+        ? lowerPositionArgument(lowerer, call.arguments[1], numLit(0, loc))
+        : method === "lastIndexOf"
+            ? { kind: "bin", op: "/", left: numLit(1, loc), right: numLit(0, loc), type: F64, loc }
+            : numLit(0, loc);
     // A derived CLASS VALUE against a base-classval element widens (the same
     // pointer — identity search is exact); the coercion path owns the ABI gate.
     if (needle.type.kind === "classval" && elem.kind === "classval" && !typeEquals(needle.type, elem)) {
@@ -546,21 +727,25 @@ function lowerArraySearchCall(lowerer, call, access, method, elem) {
     }
     // Preserve the existing fast path for an ordinary, non-union needle. Its
     // runtime implementation already has exact primitive/reference equality.
-    if (elem.kind !== "union" && elem.kind !== "bigint" && typeEquals(needle.type, elem)) {
+    if (method !== "lastIndexOf" && call.arguments.length === 1 && elem.kind !== "union" && elem.kind !== "bigint" && typeEquals(needle.type, elem)) {
         return {
             kind: "arrIntrinsic",
             method,
             receiver,
             args: [needle],
-            type: method === "indexOf" ? F64 : BOOL,
+            type: method === "includes" ? BOOL : F64,
             loc,
         };
     }
-    const valueT = arrayValueType(lowerer, elem);
+    let valueT = arrayValueType(lowerer, elem);
     // jsval/dyn arrays have a single engine value representation rather than a
     // static undefined arm. Keep their existing runtime path and its explicit
     // type fence; typed static arrays take the state-aware helper below.
     if (valueT.kind !== "union") {
+        if (method === "lastIndexOf")
+            lowerer.noLowering(".lastIndexOf on an array of engine values", call);
+        if (call.arguments.length > 1)
+            lowerer.noLowering(`.${method} with fromIndex on '${lowerer.fmt(elem)}' elements`, call);
         if (!typeEquals(needle.type, elem))
             lowerer.badType(argNode, lowerer.typeOf(argNode));
         return {
@@ -568,15 +753,38 @@ function lowerArraySearchCall(lowerer, call, access, method, elem) {
             method,
             receiver,
             args: [needle],
-            type: method === "indexOf" ? F64 : BOOL,
+            type: method === "includes" ? BOOL : F64,
             loc,
         };
     }
-    const searchNeedle = lowerer.coerceInto(argNode, needle, valueT);
-    if (!typeEquals(searchNeedle.type, valueT))
+    // Search uses strict equality, never conversion to the array's element
+    // type. Retain primitive needles of a different kind in the comparison
+    // union so a nonmatching kind returns a miss instead of throwing.
+    const needleArms = needle.type.kind === "union"
+        ? lowerer.unions.get(needle.type.unionId).arms
+        : [needle.type];
+    const scalarNeedle = needleArms.every((arm) => arm.kind === "f64" || arm.kind === "string" || arm.kind === "bool" ||
+        arm.kind === "bigint" || arm.kind === "symbol" || isUnitType(arm));
+    const valueArms = lowerer.unions.get(valueT.unionId).arms;
+    if (scalarNeedle && !valueArms.some((arm) => arm.kind === "func" || arm.kind === "set")) {
+        const arms = [...valueArms];
+        for (const arm of needleArms)
+            if (!arms.some((existing) => typeEquals(existing, arm)))
+                arms.push(arm);
+        if (arms.length !== valueArms.length)
+            valueT = { kind: "union", unionId: lowerer.unions.intern(arms) };
+    }
+    const directNeedle = method === "lastIndexOf" && elem.kind !== "union" && typeEquals(needle.type, elem);
+    const searchNeedle = directNeedle ? needle : lowerer.coerceInto(argNode, needle, valueT);
+    // Checked dynamic extraction can copy a composite. Its new identity cannot
+    // be compared to an array element as though it were the original value.
+    if (method === "lastIndexOf" && searchNeedle.kind === "dynCheck" && (elem.kind === "record" || elem.kind === "array")) {
+        lowerer.noLowering(".lastIndexOf with a checked dynamic reference needle", call);
+    }
+    if (!directNeedle && !typeEquals(searchNeedle.type, valueT))
         lowerer.badType(argNode, lowerer.typeOf(argNode));
-    const helper = arraySearchHelper(lowerer, method, elem, valueT, loc);
-    return { kind: "call", callee: helper, args: [receiver, searchNeedle], type: method === "indexOf" ? F64 : BOOL, loc };
+    const helper = arraySearchHelper(lowerer, method, elem, valueT, searchNeedle.type, directNeedle, fromIndex.type, call.arguments[1] ?? call, loc);
+    return { kind: "call", callee: helper, args: [receiver, searchNeedle, fromIndex], type: method === "includes" ? BOOL : F64, loc };
 }
 /** SameValueZero over a static value union. `unionEq` supplies strict
  * equality for every arm; the extra f64-arm test is the only difference for
@@ -620,25 +828,65 @@ function arraySearchEquality(lowerer, left, right, sameValueZero, loc) {
     };
     return { kind: "logical", op: "||", left: strict, right: bothNaN, type: BOOL, loc };
 }
-function arraySearchHelper(lowerer, method, elem, valueT, loc) {
-    const key = `${method}:${typeKey(elem)}:${typeKey(valueT)}`;
+function arraySearchHelper(lowerer, method, elem, valueT, needleT, directNeedle, fromT, fromNode, loc) {
+    const key = `${method}:${typeKey(elem)}:${typeKey(valueT)}:${typeKey(needleT)}:${directNeedle}:${typeKey(fromT)}`;
     const existing = lowerer.arrHofHelpers.get(key);
     if (existing)
         return existing;
     const name = `%arr.${method}.${lowerer.arrHofHelpers.size}`;
     lowerer.arrHofHelpers.set(key, name);
     const arrT = arrayOf(elem);
-    const resultT = method === "indexOf" ? F64 : BOOL;
+    const resultT = method === "includes" ? BOOL : F64;
     const arrRef = varRef("a.0", arrT, loc);
     const indexRef = varRef("i.0", F64, loc);
-    const needleRef = varRef("needle.0", valueT, loc);
+    const needleRef = varRef("needle.0", needleT, loc);
     const stateRef = varRef("state.0", F64, loc);
     const nextRef = varRef("next.0", F64, loc);
+    const fromRef = varRef("from.0", fromT, loc);
+    const numberRef = varRef("number.0", F64, loc);
+    const integerRef = varRef("integer.0", F64, loc);
+    // Snapshot length before coercing fromIndex, then apply ToIntegerOrInfinity.
+    const number = positionNumber(lowerer, fromRef, numLit(0, loc), fromNode, "array search position");
+    const integer = {
+        kind: "ternary",
+        cond: { kind: "libCall", fn: "num.isNaN", args: [numberRef], type: BOOL, loc },
+        then: numLit(0, loc),
+        else_: { kind: "libCall", fn: "math.trunc", args: [numberRef], type: F64, loc },
+        type: F64,
+        loc,
+    };
+    const forwardStart = {
+        kind: "ternary",
+        cond: { kind: "bin", op: "<", left: integerRef, right: numLit(0, loc), type: BOOL, loc },
+        then: {
+            kind: "libCall", fn: "math.max",
+            args: [{ kind: "bin", op: "+", left: varRef("n.0", F64, loc), right: integerRef, type: F64, loc }, numLit(0, loc)],
+            type: F64, loc,
+        },
+        // Adding positive zero canonicalizes a truncated negative zero.
+        else_: { kind: "bin", op: "+", left: integerRef, right: numLit(0, loc), type: F64, loc },
+        type: F64,
+        loc,
+    };
+    const start = method === "lastIndexOf" ? {
+        kind: "ternary",
+        cond: { kind: "bin", op: "<", left: integerRef, right: numLit(0, loc), type: BOOL, loc },
+        then: { kind: "bin", op: "+", left: varRef("n.0", F64, loc), right: integerRef, type: F64, loc },
+        else_: {
+            kind: "libCall", fn: "math.min",
+            args: [
+                { kind: "bin", op: "+", left: integerRef, right: numLit(0, loc), type: F64, loc },
+                { kind: "bin", op: "-", left: varRef("n.0", F64, loc), right: numLit(1, loc), type: F64, loc },
+            ],
+            type: F64, loc,
+        },
+        type: F64, loc,
+    } : forwardStart;
     const rawRead = { kind: "arrayGet", arr: arrRef, index: indexRef, type: elem, loc };
     const missing = lowerer.wrappedUndefined(valueT, loc);
     if (!missing)
         throw new InternalCompilerError("array search helper needs an undefined arm");
-    const value = {
+    const optionalValue = {
         kind: "ternary",
         cond: { kind: "bin", op: "===", left: stateRef, right: numLit(1, loc), type: BOOL, loc },
         then: typeEquals(elem, valueT) ? rawRead : lowerer.coerceToExpected(rawRead, valueT),
@@ -646,12 +894,14 @@ function arraySearchHelper(lowerer, method, elem, valueT, loc) {
         type: valueT,
         loc,
     };
-    const equal = arraySearchEquality(lowerer, varRef("value.0", valueT, loc), needleRef, method === "includes", loc);
-    const match = method === "indexOf"
+    const value = directNeedle ? rawRead : optionalValue;
+    const readT = directNeedle ? elem : valueT;
+    const equal = arraySearchEquality(lowerer, varRef("value.0", readT, loc), needleRef, method === "includes", loc);
+    const match = method !== "includes"
         ? {
             kind: "logical",
             op: "&&",
-            left: { kind: "bin", op: "!==", left: stateRef, right: numLit(0, loc), type: BOOL, loc },
+            left: { kind: "bin", op: directNeedle ? "===" : "!==", left: stateRef, right: numLit(directNeedle ? 1 : 0, loc), type: BOOL, loc },
             right: equal,
             type: BOOL,
             loc,
@@ -660,7 +910,7 @@ function arraySearchHelper(lowerer, method, elem, valueT, loc) {
     const undefinedTag = lowerer.armTag(valueT.unionId, UNDEFINED_T);
     if (undefinedTag < 0)
         throw new InternalCompilerError("array search helper needs an undefined tag");
-    const needleIsUndefined = {
+    const needleIsUndefined = directNeedle ? boolLit(false, loc) : {
         kind: "unionIsTag",
         unionId: valueT.unionId,
         tag: undefinedTag,
@@ -672,7 +922,7 @@ function arraySearchHelper(lowerer, method, elem, valueT, loc) {
     const advance = {
         kind: "assign",
         localId: "i.0",
-        value: { kind: "bin", op: "+", left: indexRef, right: numLit(1, loc), type: F64, loc },
+        value: { kind: "bin", op: method === "lastIndexOf" ? "-" : "+", left: indexRef, right: numLit(1, loc), type: F64, loc },
         loc,
     };
     const visitPresent = [
@@ -680,13 +930,13 @@ function arraySearchHelper(lowerer, method, elem, valueT, loc) {
         {
             kind: "if",
             cond: match,
-            then: [{ kind: "return", value: method === "indexOf" ? indexRef : boolLit(true, loc), loc }],
+            then: [{ kind: "return", value: method === "includes" ? boolLit(true, loc) : indexRef, loc }],
             else_: null,
             loc,
         },
         advance,
     ];
-    const skipHole = [
+    const skipHole = method === "lastIndexOf" ? [advance] : [
         {
             kind: "varDecl",
             localId: "next.0",
@@ -712,28 +962,36 @@ function arraySearchHelper(lowerer, method, elem, valueT, loc) {
         name,
         params: [
             { localId: "a.0", name: "a", type: arrT },
-            { localId: "needle.0", name: "needle", type: valueT },
+            { localId: "needle.0", name: "needle", type: needleT },
+            { localId: "from.0", name: "from", type: fromT },
         ],
         returnType: resultT,
         locals: [
             { id: "a.0", name: "a", type: arrT, mutable: true },
-            { id: "needle.0", name: "needle", type: valueT, mutable: true },
+            { id: "needle.0", name: "needle", type: needleT, mutable: true },
+            { id: "from.0", name: "from", type: fromT, mutable: false },
+            { id: "number.0", name: "number", type: F64, mutable: false },
+            { id: "integer.0", name: "integer", type: F64, mutable: false },
             { id: "n.0", name: "n", type: F64, mutable: false },
             { id: "i.0", name: "i", type: F64, mutable: true },
             { id: "state.0", name: "state", type: F64, mutable: false },
             { id: "next.0", name: "next", type: F64, mutable: false },
-            { id: "value.0", name: "value", type: valueT, mutable: false },
+            { id: "value.0", name: "value", type: readT, mutable: false },
         ],
         body: [
             readLenStmt(arrT, loc),
-            { kind: "varDecl", localId: "i.0", init: numLit(0, loc), loc },
+            { kind: "varDecl", localId: "number.0", init: number, loc },
+            { kind: "varDecl", localId: "integer.0", init: integer, loc },
+            { kind: "varDecl", localId: "i.0", init: start, loc },
             {
                 kind: "while",
-                cond: { kind: "bin", op: "<", left: indexRef, right: varRef("n.0", F64, loc), type: BOOL, loc },
+                cond: method === "lastIndexOf"
+                    ? { kind: "bin", op: ">=", left: indexRef, right: numLit(0, loc), type: BOOL, loc }
+                    : { kind: "bin", op: "<", left: indexRef, right: varRef("n.0", F64, loc), type: BOOL, loc },
                 body: loopBody,
                 loc,
             },
-            { kind: "return", value: method === "indexOf" ? numLit(-1, loc) : boolLit(false, loc), loc },
+            { kind: "return", value: method === "includes" ? boolLit(false, loc) : numLit(-1, loc), loc },
         ],
         loc,
     });
@@ -1291,15 +1549,8 @@ export function lowerTupleReadMethodCall(lowerer, call, access) {
     const helper = arrayHofHelper(lowerer, "map", snapshotElem, fnRet, arity, loc, outElem);
     return { kind: "call", callee: helper, args: [snapshot, fnArg], type: arrayOf(outElem), loc };
 }
-/** An OOB-SAFE indexed read: `xs[i]`
-   * answers the interned `elem | undefined` union — the element when `i`
-   * is an integer in [0, len), JS's property-miss undefined otherwise —
-   * instead of the trap divergence 4 documents for program code.
-   * Package JS is inference-typed, guard-style code (`registeredArguments
-   * .slice(-1)[0]`, commander's last-element probe), and the trap would
-   * fire on working Node idioms; program files keep the documented trap
-   * (their annotations can prove bounds). Existing element unions retag
-   * into the canonical union with an added undefined arm. */
+/** An ordinary indexed read: values retain their element type, while
+ * holes, missing properties, and present undefined yield undefined. */
 export function lowerSafeIndexRead(lowerer, arr, index, loc) {
     const elem = arr.type.elem;
     if (elem.kind === "void" || elem.kind === "dyn")
@@ -1328,6 +1579,21 @@ export function lowerSafeIndexRead(lowerer, arr, index, loc) {
     }
     return { kind: "call", callee: name, args: [arr, index], type: resultT, loc };
 }
+/** Fuse only our own f64-array read helper with immediate ToNumber.
+ * Reuse its arguments verbatim so the receiver and index still evaluate
+ * exactly once, in order, before the read. Do not specialize user calls,
+ * union-element arrays, or optional values stored in locals. */
+export function tryLowerNumericIndexRead(lowerer, operand, loc) {
+    if (operand.kind !== "call" || operand.callee !== lowerer.arrHofHelpers.get(`idxOr:${typeKey(F64)}`))
+        return null;
+    const [arr, index] = operand.args;
+    if (operand.args.length !== 2 || arr?.type.kind !== "array" || arr.type.elem.kind !== "f64" || index?.type.kind !== "f64")
+        return null;
+    // The intrinsic owns the evaluated receiver through index evaluation,
+    // then borrows it for one slot lookup. No extra helper parameter or
+    // separate state/getter expressions need to retain the array again.
+    return { kind: "arrIntrinsic", method: "getNumber", receiver: arr, args: [index], type: F64, loc };
+}
 /** Backward-compatible name for the npm-static probe path. */
 export const lowerNpmStaticSafeIndexRead = lowerSafeIndexRead;
 /** Interned synthetic function for one (elem, argument-shape) concat —
@@ -2182,22 +2448,26 @@ function reverseCountedForLoop(loc, body) {
    * through). */
 function lowerArrayAtCall(lowerer, call, access, elem) {
     const loc = locOf(call);
+    if (call.arguments.some(ts.isSpreadElement))
+        lowerer.noLowering(".at with spread arguments", call);
     const receiver = lowerer.lowerExpr(access.expression);
-    const index = lowerer.lowerExprExpecting(call.arguments[0], F64);
+    const indexNode = call.arguments[0];
+    const index = lowerPositionArgument(lowerer, indexNode, numLit(0, loc));
     const resultT = lowerer.irTypeOf(call);
     if (resultT.kind !== "union")
         lowerer.badType(call, lowerer.typeOf(call)); // defensive: T | undefined always maps to a union
     const undefTag = lowerer.armTag(resultT.unionId, UNDEFINED_T);
     if (undefTag < 0)
         lowerer.badType(call, lowerer.typeOf(call));
-    const key = `at:${typeKey(elem)}:${typeKey(resultT)}`;
+    const key = `at:${typeKey(elem)}:${typeKey(resultT)}:${typeKey(index.type)}`;
     let name = lowerer.arrHofHelpers.get(key);
     if (!name) {
         name = `%arr.at.${lowerer.arrHofHelpers.size}`;
         lowerer.arrHofHelpers.set(key, name);
         const arrT = arrayOf(elem);
         const t = varRef("t.0", F64, loc);
-        const i = varRef("i.0", F64, loc);
+        const i = varRef("i.0", index.type, loc);
+        const number = varRef("number.0", F64, loc);
         const n = varRef("n.0", F64, loc);
         const found = lowerer.coerceToExpected(arrayValueRead(lowerer, varRef("a.0", arrT, loc), t, elem, loc), resultT);
         const miss = {
@@ -2212,20 +2482,21 @@ function lowerArrayAtCall(lowerer, call, access, elem) {
         const lt = (l, r) => ({ kind: "bin", op: "<", left: l, right: r, type: BOOL, loc });
         const body = [
             readLenStmt(arrT, loc),
+            { kind: "varDecl", localId: "number.0", init: positionNumber(lowerer, i, numLit(0, loc), indexNode ?? call, "array at position"), loc },
             // ToIntegerOrInfinity: floor is trunc for i >= 0; negatives mirror
             // (trunc(i) = -floor(-i)); NaN becomes 0. ±Infinity floors to
             // itself and falls out of range below, exactly the spec.
-            { kind: "varDecl", localId: "t.0", init: floorOf(i), loc },
+            { kind: "varDecl", localId: "t.0", init: floorOf(number), loc },
             {
                 kind: "if",
-                cond: lt(i, numLit(0, loc)),
-                then: [{ kind: "assign", localId: "t.0", value: { kind: "bin", op: "-", left: numLit(0, loc), right: floorOf({ kind: "bin", op: "-", left: numLit(0, loc), right: i, type: F64, loc }), type: F64, loc }, loc }],
+                cond: lt(number, numLit(0, loc)),
+                then: [{ kind: "assign", localId: "t.0", value: { kind: "bin", op: "-", left: numLit(0, loc), right: floorOf({ kind: "bin", op: "-", left: numLit(0, loc), right: number, type: F64, loc }), type: F64, loc }, loc }],
                 else_: null,
                 loc,
             },
             {
                 kind: "if",
-                cond: { kind: "libCall", fn: "num.isNaN", args: [i], type: BOOL, loc },
+                cond: { kind: "libCall", fn: "num.isNaN", args: [number], type: BOOL, loc },
                 then: [{ kind: "assign", localId: "t.0", value: numLit(0, loc), loc }],
                 else_: null,
                 loc,
@@ -2257,13 +2528,14 @@ function lowerArrayAtCall(lowerer, call, access, elem) {
             name,
             params: [
                 { localId: "a.0", name: "a", type: arrT },
-                { localId: "i.0", name: "i", type: F64 },
+                { localId: "i.0", name: "i", type: index.type },
             ],
             returnType: resultT,
             locals: [
                 { id: "a.0", name: "a", type: arrT, mutable: true },
-                { id: "i.0", name: "i", type: F64, mutable: true },
+                { id: "i.0", name: "i", type: index.type, mutable: false },
                 { id: "n.0", name: "n", type: F64, mutable: false },
+                { id: "number.0", name: "number", type: F64, mutable: false },
                 { id: "t.0", name: "t", type: F64, mutable: true },
             ],
             body,
@@ -2272,6 +2544,84 @@ function lowerArrayAtCall(lowerer, call, access, elem) {
     }
     return { kind: "call", callee: name, args: [receiver, index], type: resultT, loc };
 }
+/** The Array constructor's element and count forms, shared by calls and new. */
+export function lowerArrayConstructor(lowerer, expr, args) {
+    const loc = locOf(expr);
+    if (args.some(ts.isSpreadElement)) {
+        lowerer.noLowering("Array constructor with spread arguments", expr);
+    }
+    let result = lowerer.mapTypeOf(lowerer.typeOf(expr));
+    if (result?.kind !== "array") {
+        const contextual = lowerer.checker.getContextualType(expr);
+        if (contextual)
+            result = lowerer.mapTypeOf(contextual);
+    }
+    if (result?.kind !== "array" || !isSupportedArrayElem(result.elem)) {
+        lowerer.badType(expr, lowerer.typeOf(expr));
+    }
+    const argType = args.length === 1 ? lowerer.mapTypeOf(lowerer.typeOf(args[0])) : null;
+    if (argType?.kind === "dyn" || argType?.kind === "jsval") {
+        lowerer.noLowering("Array constructor with a dynamically typed sole argument", args[0]);
+    }
+    if (args.length === 1 && (argType?.kind === "f64" ||
+        (argType?.kind === "union" && lowerer.armTag(argType.unionId, F64) >= 0))) {
+        const count = lowerer.lowerExpr(args[0]);
+        const numberTag = count.type.kind === "union" ? lowerer.armTag(count.type.unionId, F64) : -1;
+        if (count.type.kind !== "f64" && numberTag < 0) {
+            lowerer.noLowering("Array constructor length with a value that may be missing", args[0]);
+        }
+        const input = count.type.kind === "union" ? lowerer.declareHiddenLocal("%arrayCtorArg", count.type) : null;
+        const inputRef = input ? varRef(input.id, count.type, loc) : null;
+        const local = lowerer.declareHiddenLocal("%arrayLengthCtor", result);
+        const ref = varRef(local.id, result, loc);
+        const length = inputRef && count.type.kind === "union"
+            ? { kind: "unionNarrow", unionId: count.type.unionId, tag: numberTag, value: inputRef, type: F64, loc }
+            : count;
+        const resize = { kind: "arraySetLength", arr: ref, length, loc };
+        return {
+            kind: "seqExpr",
+            stmts: [
+                ...(input ? [{ kind: "varDecl", localId: input.id, init: count, loc }] : []),
+                { kind: "varDecl", localId: local.id, init: { kind: "arrayLit", elems: [], type: result, loc }, loc },
+                ...(inputRef && count.type.kind === "union"
+                    ? [{ kind: "if",
+                            cond: { kind: "unionIsTag", unionId: count.type.unionId, tag: numberTag, value: inputRef, negated: false, type: BOOL, loc },
+                            then: [resize],
+                            else_: [arrayValueStore(lowerer, ref, numLit(0, loc), lowerer.coerceInto(args[0], inputRef, result.elem), result.elem, loc)],
+                            loc }]
+                    : [resize]),
+            ],
+            result: ref,
+            type: result,
+            loc,
+        };
+    }
+    return { kind: "arrayLit", elems: args.map((arg) => lowerer.lowerExprExpecting(arg, result.elem)), type: result, loc };
+}
+/** `Array.of` creates an array of its arguments, including a lone number. */
+export function lowerArrayOfCall(lowerer, call, access) {
+    if (call.questionDotToken || access.questionDotToken || access.name.text !== "of" ||
+        !lowerer.isStdlibGlobal(access.expression, "Array"))
+        return null;
+    let result = lowerer.mapTypeOf(lowerer.typeOf(call));
+    if (result?.kind !== "array") {
+        const contextual = lowerer.checker.getContextualType(call);
+        if (contextual)
+            result = lowerer.mapTypeOf(contextual);
+    }
+    if (result?.kind !== "array" || !isSupportedArrayElem(result.elem)) {
+        lowerer.badType(call, lowerer.typeOf(call));
+    }
+    if (call.arguments.some(ts.isSpreadElement)) {
+        return lowerArraySpreadItems(lowerer, call.arguments, result.elem, result, locOf(call));
+    }
+    return {
+        kind: "arrayLit",
+        elems: call.arguments.map((arg) => lowerer.lowerExprExpecting(arg, result.elem)),
+        type: result,
+        loc: locOf(call),
+    };
+}
 /** `Array.from({ length: n }, mapfn)` — the counted-generation idiom — on
    * THE stdlib Array global. The source must be an OBJECT LITERAL whose
    * single property is `length` (the shape the idiom always spells; the
@@ -2281,8 +2631,10 @@ function lowerArrayAtCall(lowerer, call, access, elem) {
    * checker's own `unknown` for it — and pushing each result. The loop
    * bound is `i <= n - 1`, which IS ToLength for the finite lengths that
    * terminate (fractional lengths truncate, negative/NaN produce an empty
-   * array — Node-exact). Every other Array.from shape (arrays, iterables,
-   * no mapper) keeps the fence. Null when the callee isn't an
+   * array — Node-exact). Array inputs copy through the iterator's indexed
+   * values, including holes as present undefined, and may map each value.
+   * Set inputs copy their values; strings iterate by code point and may map.
+   * Other iterable shapes keep the fence. Null when the callee isn't an
    * Array-static access. */
 export function lowerArrayFromCall(lowerer, call, access) {
     if (call.questionDotToken || access.questionDotToken)
@@ -2317,23 +2669,70 @@ export function lowerArrayFromCall(lowerer, call, access) {
             return { kind: "arrayNewLen", length: n, type: arrT, loc };
         }
     }
-    // `Array.from(s)` on a STRING: the string iterator's code-point walk
-    // into a fresh string[] (astral characters stay whole, where a
-    // charAt/index walk would truncate the surrogate halves) — the same
-    // interned helper `[...s]` lowers through.
-    if (args.length === 1 && !ts.isObjectLiteralExpression(args[0])) {
-        const src = lowerer.lowerExpr(args[0]);
-        if (src.type.kind === "string")
+    // Array iteration reads length again after every mapper call. Without
+    // a mapper, a dense reversed copy followed by reversal preserves order
+    // and materializes holes while keeping element reference identity.
+    if ((args.length === 1 || args.length === 2) && !ts.isObjectLiteralExpression(args[0])) {
+        const source = lowerer.lowerExpr(args[0]);
+        const src = source.type.kind === "string" && args.length === 2 ? strCharsCall(lowerer, source, loc) : source;
+        if (src.type.kind === "array") {
+            const arrT = src.type;
+            if (args.length === 1) {
+                const dense = { kind: "arrIntrinsic", method: "toReversed", receiver: src, args: [], type: arrT, loc };
+                return { kind: "arrIntrinsic", method: "reverse", receiver: dense, args: [], type: arrT, loc };
+            }
+            const mapper = args[1];
+            const valueT = arrayValueType(lowerer, arrT.elem);
+            const firstParam = ts.isArrowFunction(mapper) || ts.isFunctionExpression(mapper)
+                ? mapper.parameters[0]?.name : undefined;
+            const paramSymbol = firstParam && ts.isIdentifier(firstParam)
+                ? lowerer.checker.getSymbolAtLocation(firstParam) : undefined;
+            const previous = paramSymbol ? lowerer.runtimeOptionalBindingTypes.get(paramSymbol) : undefined;
+            if (paramSymbol)
+                lowerer.runtimeOptionalBindingTypes.set(paramSymbol, valueT);
+            let callback;
+            try {
+                callback = hofCallbackArg(lowerer, mapper, [valueT], arrT);
+            }
+            finally {
+                if (paramSymbol) {
+                    if (previous === undefined)
+                        lowerer.runtimeOptionalBindingTypes.delete(paramSymbol);
+                    else
+                        lowerer.runtimeOptionalBindingTypes.set(paramSymbol, previous);
+                }
+            }
+            const { fnArg, arity } = callback;
+            if (arity > 2)
+                lowerer.noLowering("Array.from mapper with an array parameter", args[1]);
+            const fnRet = fnArg.type.ret;
+            if (fnRet.kind === "void" || fnRet.kind === "func")
+                lowerer.badType(call, lowerer.typeOf(call));
+            fenceProducedArrayElem(lowerer, call, "'Array.from(array, mapper)'", fnRet);
+            const outElem = callbackArrayElem(lowerer, call, fnRet);
+            const key = `fromArray:${typeKey(arrT.elem)}:${typeKey(outElem)}:${typeKey(fnRet)}:${arity}`;
+            let helper = lowerer.arrHofHelpers.get(key);
+            if (!helper) {
+                helper = `%arr.fromArray.${lowerer.arrHofHelpers.size}`;
+                lowerer.arrHofHelpers.set(key, helper);
+                lowerer.liftedFns.push(buildArrayFromArrayFn(lowerer, helper, arrT.elem, outElem, fnRet, arity, loc));
+            }
+            return { kind: "call", callee: helper, args: [src, fnArg], type: arrayOf(outElem), loc };
+        }
+        if (src.type.kind === "set" && args.length === 1) {
+            return { kind: "setIntrinsic", method: "toArray", receiver: src, args: [], type: arrayOf(src.type.elem), loc };
+        }
+        // String iteration advances by code point; the same helper serves
+        // `[...s]` and both Array.from(s) forms.
+        if (src.type.kind === "string" && args.length === 1)
             return strCharsCall(lowerer, src, loc);
-        lowerer.noLowering("Array.from with this argument shape", call, "Array.from({ length: n }, (v, i) => ...) and Array.from(aString) are the lowered " +
-            "forms — copy arrays with [...a] and drain Map/Set iterators where they are made");
+        lowerer.noLowering("Array.from with this argument shape", call, "Array.from(array), Array.from(array, mapper), Array.from(aString), Array.from(aString, mapper), and Array.from({ length: n }, mapper) are the lowered forms");
     }
     const n = args.length === 2 && ts.isObjectLiteralExpression(args[0]) && args[0].properties.length === 1
         ? lowerLengthProp(lowerer, args[0].properties[0])
         : null;
     if (!n) {
-        lowerer.noLowering("Array.from with this argument shape", call, "Array.from({ length: n }, (v, i) => ...) is the lowered form — copy arrays " +
-            "with [...a] and drain Map/Set iterators where they are made");
+        lowerer.noLowering("Array.from with this argument shape", call, "Array.from(array), Array.from(array, mapper), Array.from(aString), Array.from(aString, mapper), and Array.from({ length: n }, mapper) are the lowered forms");
     }
     if (n.type.kind !== "f64")
         lowerer.badType(args[0], lowerer.typeOf(args[0]));
@@ -2362,6 +2761,49 @@ export function lowerArrayFromCall(lowerer, call, access) {
     }
     return { kind: "call", callee: helper, args: [n, fnArg], type: arrayOf(fnRet), loc };
 }
+/** Map an array iterator to a fresh dense array. The source length remains
+ * live so mapper mutations affect which later indexes are visited. */
+function buildArrayFromArrayFn(lowerer, name, elem, outElem, fnRet, arity, loc) {
+    const arrT = arrayOf(elem);
+    const outT = arrayOf(outElem);
+    const fnT = funcOf([arrayValueType(lowerer, elem), F64].slice(0, arity), fnRet);
+    const a = varRef("a.0", arrT, loc);
+    const i = varRef("i.0", F64, loc);
+    const out = varRef("out.0", outT, loc);
+    const mapped = {
+        kind: "callValue",
+        callee: varRef("f.0", fnT, loc),
+        args: [arrayValueRead(lowerer, a, i, elem, loc), i].slice(0, arity),
+        type: fnRet,
+        loc,
+    };
+    return {
+        name,
+        params: [{ localId: "a.0", name: "a", type: arrT }, { localId: "f.0", name: "f", type: fnT }],
+        returnType: outT,
+        locals: [
+            { id: "a.0", name: "a", type: arrT, mutable: true },
+            { id: "f.0", name: "f", type: fnT, mutable: true },
+            { id: "out.0", name: "out", type: outT, mutable: false },
+            { id: "i.0", name: "i", type: F64, mutable: true },
+        ],
+        body: [
+            { kind: "varDecl", localId: "out.0", init: { kind: "arrayLit", elems: [], type: outT, loc }, loc },
+            { kind: "varDecl", localId: "i.0", init: numLit(0, loc), loc },
+            {
+                kind: "while",
+                cond: { kind: "bin", op: "<", left: i, right: { kind: "arrIntrinsic", method: "length", receiver: a, args: [], type: F64, loc }, type: BOOL, loc },
+                body: [
+                    arrayValueStore(lowerer, out, i, mapped, outElem, loc),
+                    { kind: "assign", localId: "i.0", value: { kind: "bin", op: "+", left: i, right: numLit(1, loc), type: F64, loc }, loc },
+                ],
+                loc,
+            },
+            { kind: "return", value: out, loc },
+        ],
+        loc,
+    };
+}
 /** `Array.from(s)` / `[...s]` on a STRING: the code-point split into a
    * fresh string[], through one interned helper per module. */
 export function strCharsCall(lowerer, src, loc) {