redscript-mc 2.4.0 → 2.5.0

package/dist/types/entity-hierarchy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Entity Type Hierarchy
+ *
+ * Closed inheritance tree mapping to Minecraft's entity registry.
+ * Used for type narrowing (is checks), selector<T> annotations,
+ * and W_IMPOSSIBLE_AS warnings.
+ */
+export interface EntityTypeNode {
+    name: string;
+    mcId: string | null;
+    abstract: boolean;
+    parent: string | null;
+}
+export declare const ENTITY_TYPES: EntityTypeNode[];
+/** Map from lowercase name → EntityTypeNode */
+export declare const ENTITY_TYPE_MAP: Map<string, EntityTypeNode>;
+/** Map from mcId (without namespace) → EntityTypeNode */
+export declare const ENTITY_TYPE_BY_MCID: Map<string, EntityTypeNode>;
+/** Check if typeA is a subtype of typeB (recursive ancestry) */
+export declare function isSubtype(typeA: string, typeB: string): boolean;
+/** True if one type is a subtype of the other (in either direction) */
+export declare function areCompatibleTypes(outerType: string, innerType: string): boolean;
+/** Get all non-abstract leaf types under a given node */
+export declare function getConcreteSubtypes(typeName: string): EntityTypeNode[];
+/** Parse "type=zombie" from a selector string, return the entity type name or null */
+export declare function getSelectorEntityType(selector: string): string | null;
+/** Determine the base entity type from a selector kind:
+ *  @a/@p/@r → "Player", @e → "Entity" or from type filter, @s → null */
+export declare function getBaseSelectorType(selector: string): string | null;

package/dist/types/entity-hierarchy.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Entity Type Hierarchy
+ *
+ * Closed inheritance tree mapping to Minecraft's entity registry.
+ * Used for type narrowing (is checks), selector<T> annotations,
+ * and W_IMPOSSIBLE_AS warnings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTITY_TYPE_BY_MCID = exports.ENTITY_TYPE_MAP = exports.ENTITY_TYPES = void 0;
+exports.isSubtype = isSubtype;
+exports.areCompatibleTypes = areCompatibleTypes;
+exports.getConcreteSubtypes = getConcreteSubtypes;
+exports.getSelectorEntityType = getSelectorEntityType;
+exports.getBaseSelectorType = getBaseSelectorType;
+exports.ENTITY_TYPES = [
+    // Root
+    { name: 'Entity', mcId: null, abstract: true, parent: null },
+    // Direct children of Entity
+    { name: 'Player', mcId: 'minecraft:player', abstract: false, parent: 'Entity' },
+    { name: 'ArmorStand', mcId: 'minecraft:armor_stand', abstract: false, parent: 'Entity' },
+    { name: 'Item', mcId: 'minecraft:item', abstract: false, parent: 'Entity' },
+    { name: 'Arrow', mcId: 'minecraft:arrow', abstract: false, parent: 'Entity' },
+    // Mob hierarchy
+    { name: 'Mob', mcId: null, abstract: true, parent: 'Entity' },
+    // Hostile mobs
+    { name: 'HostileMob', mcId: null, abstract: true, parent: 'Mob' },
+    { name: 'Zombie', mcId: 'minecraft:zombie', abstract: false, parent: 'HostileMob' },
+    { name: 'Skeleton', mcId: 'minecraft:skeleton', abstract: false, parent: 'HostileMob' },
+    { name: 'Creeper', mcId: 'minecraft:creeper', abstract: false, parent: 'HostileMob' },
+    { name: 'Spider', mcId: 'minecraft:spider', abstract: false, parent: 'HostileMob' },
+    { name: 'Enderman', mcId: 'minecraft:enderman', abstract: false, parent: 'HostileMob' },
+    { name: 'Blaze', mcId: 'minecraft:blaze', abstract: false, parent: 'HostileMob' },
+    { name: 'Witch', mcId: 'minecraft:witch', abstract: false, parent: 'HostileMob' },
+    { name: 'Slime', mcId: 'minecraft:slime', abstract: false, parent: 'HostileMob' },
+    { name: 'ZombieVillager', mcId: 'minecraft:zombie_villager', abstract: false, parent: 'HostileMob' },
+    { name: 'Husk', mcId: 'minecraft:husk', abstract: false, parent: 'HostileMob' },
+    { name: 'Drowned', mcId: 'minecraft:drowned', abstract: false, parent: 'HostileMob' },
+    { name: 'Stray', mcId: 'minecraft:stray', abstract: false, parent: 'HostileMob' },
+    { name: 'WitherSkeleton', mcId: 'minecraft:wither_skeleton', abstract: false, parent: 'HostileMob' },
+    { name: 'CaveSpider', mcId: 'minecraft:cave_spider', abstract: false, parent: 'HostileMob' },
+    // Passive mobs
+    { name: 'PassiveMob', mcId: null, abstract: true, parent: 'Mob' },
+    { name: 'Pig', mcId: 'minecraft:pig', abstract: false, parent: 'PassiveMob' },
+    { name: 'Cow', mcId: 'minecraft:cow', abstract: false, parent: 'PassiveMob' },
+    { name: 'Sheep', mcId: 'minecraft:sheep', abstract: false, parent: 'PassiveMob' },
+    { name: 'Chicken', mcId: 'minecraft:chicken', abstract: false, parent: 'PassiveMob' },
+    { name: 'Villager', mcId: 'minecraft:villager', abstract: false, parent: 'PassiveMob' },
+    { name: 'WanderingTrader', mcId: 'minecraft:wandering_trader', abstract: false, parent: 'PassiveMob' },
+];
+/** Map from lowercase name → EntityTypeNode */
+exports.ENTITY_TYPE_MAP = new Map(exports.ENTITY_TYPES.map(t => [t.name.toLowerCase(), t]));
+/** Map from mcId (without namespace) → EntityTypeNode */
+exports.ENTITY_TYPE_BY_MCID = new Map(exports.ENTITY_TYPES
+    .filter(t => t.mcId !== null)
+    .map(t => [t.mcId.replace('minecraft:', ''), t]));
+/** Check if typeA is a subtype of typeB (recursive ancestry) */
+function isSubtype(typeA, typeB) {
+    if (typeA === typeB)
+        return true;
+    const node = exports.ENTITY_TYPE_MAP.get(typeA.toLowerCase());
+    if (!node || !node.parent)
+        return false;
+    return isSubtype(node.parent, typeB);
+}
+/** True if one type is a subtype of the other (in either direction) */
+function areCompatibleTypes(outerType, innerType) {
+    return isSubtype(outerType, innerType) || isSubtype(innerType, outerType);
+}
+/** Get all non-abstract leaf types under a given node */
+function getConcreteSubtypes(typeName) {
+    const results = [];
+    for (const node of exports.ENTITY_TYPES) {
+        if (!node.abstract && isSubtype(node.name, typeName)) {
+            results.push(node);
+        }
+    }
+    return results;
+}
+/** Parse "type=zombie" from a selector string, return the entity type name or null */
+function getSelectorEntityType(selector) {
+    const match = selector.match(/type=(?:minecraft:)?([a-z_]+)/);
+    if (!match)
+        return null;
+    const mcId = match[1];
+    const node = exports.ENTITY_TYPE_BY_MCID.get(mcId);
+    return node ? node.name : null;
+}
+/** Determine the base entity type from a selector kind:
+ *  @a/@p/@r → "Player", @e → "Entity" or from type filter, @s → null */
+function getBaseSelectorType(selector) {
+    const trimmed = selector.trim();
+    // Check for type filter first (works for any selector)
+    const typeFromFilter = getSelectorEntityType(trimmed);
+    if (trimmed.startsWith('@a') || trimmed.startsWith('@p') || trimmed.startsWith('@r')) {
+        return typeFromFilter ?? 'Player';
+    }
+    if (trimmed.startsWith('@e')) {
+        return typeFromFilter ?? 'Entity';
+    }
+    // @s — context-dependent, we don't know unless there's a type filter
+    if (trimmed.startsWith('@s')) {
+        return typeFromFilter ?? null;
+    }
+    return null;
+}
+//# sourceMappingURL=entity-hierarchy.js.map

package/editors/vscode/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "redscript-vscode",
-  "version": "1.2.34",
+  "version": "1.2.42",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "redscript-vscode",
-      "version": "1.2.34",
+      "version": "1.2.42",
       "license": "MIT",
       "dependencies": {
         "redscript": "file:../../",
@@ -24,7 +24,7 @@
     },
     "../..": {
       "name": "redscript-mc",
-      "version": "2.4.0",
+      "version": "2.4.1",
       "license": "MIT",
       "dependencies": {
         "vscode-languageserver": "^9.0.1",

package/editors/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "redscript-vscode",
   "displayName": "RedScript for Minecraft",
   "description": "Syntax highlighting, error diagnostics, and language support for RedScript — a compiler targeting Minecraft Java Edition",
-  "version": "1.2.34",
+  "version": "1.2.42",
   "publisher": "bkmashiro",
   "icon": "icon.png",
   "license": "MIT",

package/examples/math-demo.mcrs

@@ -0,0 +1,127 @@
+// math-demo.mcrs — Showcase of RedScript stdlib: math, easing, noise, physics
+//
+// Run:
+//   redscript compile examples/math-demo.mcrs --namespace mathdemo -o <datapack>
+//   In game: /function mathdemo:start
+
+import "../src/stdlib/math.mcrs"
+import "../src/stdlib/easing.mcrs"
+import "../src/stdlib/noise.mcrs"
+import "../src/stdlib/physics.mcrs"
+import "../src/stdlib/vec.mcrs"
+
+// ─── Load ──────────────────────────────────────────────────────────────────────
+
+@load fn __load() {
+    scoreboard_add("mathdemo");
+}
+
+// ─── Math functions demo ───────────────────────────────────────────────────────
+
+@keep fn demo_math() {
+    // Fixed-point math (×10000 scale)
+    let x: int = 20000;  // 2.0
+
+    let l: int = ln(x);       // ln(2.0) ≈ 6931
+    let s: int = sqrt_fx(x);  // √2.0 ≈ 14142
+    let e: int = exp_fx(x);   // e^2.0 ≈ 73891
+
+    say(f"§e-- Math Demo --");
+    say(f"ln(2.0)    = {l}  [expect 6931]");
+    say(f"sqrt(2.0)  = {s}  [expect 14142]");
+    say(f"exp(2.0)   = {e}  [expect 73891]");
+
+    let c: int = combinations(10, 3);  // C(10,3) = 120
+    let f: int = factorial(6);         // 6! = 720
+    say(f"C(10,3) = {c}  [expect 120]");
+    say(f"6!      = {f}  [expect 720]");
+}
+
+// ─── Easing demo ──────────────────────────────────────────────────────────────
+
+@keep fn demo_easing() {
+    say(f"§e-- Easing Demo (t=5000 = midpoint) --");
+    let t: int = 5000;  // t = 0.5 (midpoint of animation)
+
+    let lin:    int = ease_linear(t);
+    let quad:   int = ease_in_quad(t);
+    let cubic:  int = ease_out_cubic(t);
+    let bounce: int = ease_out_bounce(t);
+    let back:   int = ease_out_back(t);
+
+    say(f"linear:      {lin}   [expect 5000]");
+    say(f"in_quad:     {quad}  [expect 2500]");
+    say(f"out_cubic:   {cubic} [expect 8750]");
+    say(f"out_bounce:  {bounce}");
+    say(f"out_back:    {back}");
+}
+
+// ─── Noise demo ───────────────────────────────────────────────────────────────
+
+@keep fn demo_noise() {
+    say(f"§e-- Noise Demo --");
+
+    // 1D value noise at a few positions
+    let n0: int = value_noise_1d(0);
+    let n1: int = value_noise_1d(25000);   // x = 2.5
+    let n2: int = value_noise_1d(50000);   // x = 5.0
+
+    say(f"noise1d(0.0) = {n0}");
+    say(f"noise1d(2.5) = {n1}");
+    say(f"noise1d(5.0) = {n2}");
+
+    // FBM terrain height
+    let h1: int = terrain_height(0, 0, 64, 20);
+    let h2: int = terrain_height(10, 5, 64, 20);
+    say(f"terrain(0,0)  = {h1} blocks  [base 64, amp 20]");
+    say(f"terrain(10,5) = {h2} blocks");
+}
+
+// ─── Physics demo ─────────────────────────────────────────────────────────────
+
+@keep fn demo_physics() {
+    say(f"§e-- Physics Demo --");
+
+    // Projectile: launched up with v0y = 200 (2.0 blocks/tick)
+    let v0y: int = 200;
+    let t_land: int = projectile_land_t(v0y);
+    let max_h: int = projectile_max_height(v0y);
+
+    say(f"Arrow launch: v0y={v0y} (2.0 bl/tick)");
+    say(f"  Land time: {t_land} ticks  [expect 50 ticks = 2.5 sec]");
+    say(f"  Max height: {max_h} units = {max_h / 100} blocks");
+
+    // Simulate first 5 ticks
+    say(f"  Y position (×100):");
+    let y: int = 0;
+    let t: int = 0;
+    while (t < 5) {
+        y = projectile_y(0, v0y, t);
+        say(f"    t={t}: y={y}");
+        t = t + 1;
+    }
+
+    // Spring: mass at 0, target at 10000, k=3000, damping=9500
+    say(f"Spring simulation (k=0.3, damp=0.95):");
+    let pos: int = 0;
+    let vel: int = 0;
+    let target: int = 10000;
+    let step: int = 0;
+    while (step < 5) {
+        vel = spring_update_v(vel, pos, target, 3000, 9500);
+        pos = update_pos(pos, vel);
+        say(f"    step={step}: pos={pos} vel={vel}");
+        step = step + 1;
+    }
+}
+
+// ─── Start (runs all demos) ────────────────────────────────────────────────────
+
+@keep fn start() {
+    say(f"§6=== RedScript stdlib Math Demo ===");
+    demo_math();
+    demo_easing();
+    demo_noise();
+    demo_physics();
+    say(f"§6=== Done ===");
+}

package/examples/showcase.mcrs

@@ -195,69 +195,47 @@ fn _tick_math() {
 // ── Phase 2: BigInt ───────────────────────────────────────────────────────
 
 fn _dump_bigint_phase() {
-    _section("BigInt — 32-Digit Arbitrary Precision");
-
-    say("§eFibonacci sequence (BigInt, base-10000 limbs):");
-
-    // Small Fibonacci — fits in single limb
-    let i: int = 0;
-    while (i <= 20) {
-        bigint_fib(i);
-        let v: int = bigint_get_a(0);
-        say(f"  F({i}) = {v}");
-        i = i + 5;
-    }
-
-    // F(50) = 12,586,269,025 (3 limbs)
-    bigint_fib(50);
-    let f50_2: int = bigint_get_a(2);
-    let f50_1: int = bigint_get_a(1);
-    let f50_0: int = bigint_get_a(0);
-    say(f"  F(50) = {f50_2}_{f50_1}_{f50_0}  [= 12,586,269,025]");
-
-    // F(100) = 354,224,848,179,261,915,075 (6 limbs)
-    bigint_fib(100);
-    let f100_5: int = bigint_get_a(5);
-    let f100_4: int = bigint_get_a(4);
-    let f100_3: int = bigint_get_a(3);
-    let f100_2: int = bigint_get_a(2);
-    let f100_1: int = bigint_get_a(1);
-    let f100_0: int = bigint_get_a(0);
-    say(f"  F(100)= {f100_5}_{f100_4}_{f100_3}_{f100_2}_{f100_1}_{f100_0}");
-    say(f"  [= 354,224,848,179,261,915,075]");
-
-    // BigInt multiplication: 999999999 × 999999999
-    say("§eBigInt Multiply:");
-    bigint_init();
-    bigint_from_int_a(999999999);
-    bigint_from_int_b(999999999);
-    bigint_mul();
-    let m2: int = bigint_get_c(2);
-    let m1: int = bigint_get_c(1);
-    let m0: int = bigint_get_c(0);
-    say(f"  999999999² = {m2}_{m1}_{m0}");
-    say(f"  [= 999999998_000000001]");
-
-    // BigInt subtract
-    say("§eBigInt Subtract:");
-    bigint_init();
-    bigint_from_int_a(1000000000);
-    bigint_from_int_b(1);
-    bigint_sub();
-    let s0: int = bigint_get_c(0);
-    let s1: int = bigint_get_c(1);
-    say(f"  1,000,000,000 - 1 = {s1}_{s0}  [= 999999999]");
+    _section("BigInt — Arbitrary Precision (base-10000 arrays)");
+
+    say("§eBigInt add: [9999,9999] + [0,1] = [1,0,0]");
+    // 9999_9999 + 1 = 1_0000_0000 (overflow into next chunk)
+    let a: int[] = [9999, 9999];
+    let b: int[] = [0, 1];
+    let r: int[] = [0, 0];
+    let carry: int = bigint_add(a, b, r, 2);
+    say(f"  carry={carry} result=[{r[0]},{r[1]}]  [expect carry=1 result=[0,0]]");
+
+    say("§eBigInt sub: [1,0] - [0,1] = [0,9999]");
+    // 1_0000 - 1 = 9999
+    let c: int[] = [1, 0];
+    let d: int[] = [0, 1];
+    let s: int[] = [0, 0];
+    bigint_sub(c, d, s, 2);
+    say(f"  result=[{s[0]},{s[1]}]  [expect [0,9999]]");
+
+    say("§eBigInt mul_small: [1,2345] × 3");
+    // 1_2345 × 3 = 3_7035
+    let e: int[] = [1, 2345];
+    let f: int[] = [0, 0];
+    bigint_mul_small(e, 3, f, 2);
+    say(f"  result=[{f[0]},{f[1]}]  [expect [3,7035]]");
+
+    say("§eBigInt cmp: [1,0] > [0,9999]");
+    let g: int[] = [1, 0];
+    let h: int[] = [0, 9999];
+    let cmp_result: int = bigint_cmp(g, h, 2);
+    say(f"  cmp={cmp_result}  [expect 1 (greater)]");
 }
 
 fn _tick_bigint_live() {
-    // Show incremental Fibonacci on actionbar
-    if (state.tick % 10 == 0) {
-        let n: int = (state.tick / 10) % 30;
-        bigint_fib(n);
-        let v0: int = bigint_get_a(0);
-        let v1: int = bigint_get_a(1);
+    // Show counter with bigint add on actionbar
+    if (state.tick % 20 == 0) {
+        let counter: int[] = [0, state.tick / 20];
+        let one: int[] = [0, 1];
+        let r: int[] = [0, 0];
+        let carry: int = bigint_add(counter, one, r, 2);
         foreach (p in @a[limit=1]) {
-            actionbar(p, f"§dF({n}) limb[1]={v1} limb[0]={v0}");
+            actionbar(p, f"§dBigInt tick: [{r[0]},{r[1]}] carry={carry}");
         }
     }
 }
@@ -436,56 +414,33 @@ fn dump_advanced() {
 // ── BigInt step-by-step debug ─────────────────────────────────────────────
 // /function showcase:debug_bigint
 fn debug_bigint() {
-    say("§e=== BigInt Debug ===");
-
-    // Step 0: check scoreboard objective 'rs' exists (set by __load)
-    // If this reads 0, __load hasn't run — do /reload first!
-    scoreboard_set("__dbgcheck", #rs, 9999);
-    let rs_check: int = scoreboard_get("__dbgcheck", #rs);
-    say(f"§7[0] rs-objective check={rs_check}  (expect 9999; if 0 → run /reload first!)");
-
-    // Step 1: init
-    bigint_init();
-    say("§7[1] bigint_init() done");
-
-    // Step 2: from_int_a (STATIC index writes, no macro)
-    bigint_from_int_a(12345);
-    // 2a: static read (data get storage rs:bigint a[0] — NO macro)
-    let direct0: int = storage_get_int("rs:bigint", "a", 0);
-    let direct1: int = storage_get_int("rs:bigint", "a", 1);
-    say(f"§7[2a] static-read a[0]={direct0}  a[1]={direct1}  (expect 2345,1)");
-    // 2b: macro read (bigint_get_a uses macro sub-function)
-    let a0: int = bigint_get_a(0);
-    let a1: int = bigint_get_a(1);
-    say(f"§7[2b] macro-read  a[0]={a0}  a[1]={a1}  (expect 2345,1)");
-
-    // Step 3: fib(1) = 1  (no carry, simplest case)
-    bigint_fib(1);
-    let f1: int = bigint_get_a(0);
-    say(f"§7[3] fib(1) → get_a(0)={f1}  (expect 1)");
-
-    // Step 4: fib(5) = 5
-    bigint_fib(5);
-    let f5: int = bigint_get_a(0);
-    say(f"§7[4] fib(5) → get_a(0)={f5}  (expect 5)");
-
-    // Step 5: fib(10) = 55
-    bigint_fib(10);
-    let f10: int = bigint_get_a(0);
-    say(f"§7[5] fib(10) → get_a(0)={f10}  (expect 55)");
-
-    // Step 6: fib(20) = 6765
-    bigint_fib(20);
-    let f20: int = bigint_get_a(0);
-    say(f"§7[6] fib(20) → get_a(0)={f20}  (expect 6765)");
-
-    // Step 7: manual add — bigint_add() writes via __ssi macro
-    bigint_init();
-    bigint_from_int_a(1);
-    bigint_from_int_b(1);
-    bigint_add();
-    let c0: int = bigint_get_c(0);
-    say(f"§7[7] 1+1=? get_c(0)={c0}  (expect 2)");
+    say("§e=== BigInt Debug (v2.4+ array-by-ref API) ===");
+
+    // Test 1: add with carry
+    let a: int[] = [9999, 9999];
+    let b: int[] = [0, 1];
+    let r: int[] = [0, 0];
+    let carry: int = bigint_add(a, b, r, 2);
+    say(f"§7[1] 9999_9999 + 1: carry={carry} r=[{r[0]},{r[1]}]  (expect carry=1 r=[0,0])");
+
+    // Test 2: subtract
+    let c: int[] = [1, 0];
+    let d: int[] = [0, 1];
+    let s: int[] = [0, 0];
+    bigint_sub(c, d, s, 2);
+    say(f"§7[2] 1_0000 - 1: s=[{s[0]},{s[1]}]  (expect [0,9999])");
+
+    // Test 3: mul_small
+    let e: int[] = [1, 2345];
+    let f: int[] = [0, 0];
+    bigint_mul_small(e, 3, f, 2);
+    say(f"§7[3] 1_2345 × 3: f=[{f[0]},{f[1]}]  (expect [3,7035])");
+
+    // Test 4: compare
+    let g: int[] = [1, 0];
+    let h: int[] = [0, 9999];
+    let cmp: int = bigint_cmp(g, h, 2);
+    say(f"§7[4] [1,0] vs [0,9999]: cmp={cmp}  (expect 1 = greater)");
 
     say("§a=== Done ===");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redscript-mc",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "A high-level programming language that compiles to Minecraft datapacks",
   "main": "dist/src/index.js",
   "bin": {

package/src/__tests__/array-param.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Tests for array reference parameter passing.
+ *
+ * When a function takes an `int[]` parameter and is called with an array
+ * variable, the compiler monomorphizes the callee per-call-site so that
+ * array index reads/writes inside the callee refer to the caller's actual
+ * NBT storage path.
+ */
+
+import { compile } from '../emit/compile'
+
+function getFile(files: { path: string; content: string }[], pathSubstr: string): string | undefined {
+  return files.find(f => f.path.includes(pathSubstr))?.content
+}
+
+function getFunctionBody(files: { path: string; content: string }[], fnName: string): string {
+  const content = getFile(files, `${fnName}.mcfunction`)
+  if (!content) {
+    const paths = files.map(f => f.path).join('\n')
+    throw new Error(`Function '${fnName}' not found in output. Files:\n${paths}`)
+  }
+  return content
+}
+
+describe('Array reference parameter passing', () => {
+  const src = `
+    fn swap_elems(arr: int[], i: int, j: int) {
+        let tmp: int = arr[i];
+        arr[i] = arr[j];
+        arr[j] = tmp;
+    }
+    @keep fn test() {
+        let nums: int[] = [30, 10, 20];
+        swap_elems(nums, 0, 1);
+        scoreboard_set("#out", "test", nums[0]);
+    }
+  `
+
+  let files: { path: string; content: string }[]
+  beforeAll(() => {
+    const result = compile(src, { namespace: 'test' })
+    files = result.files
+  })
+
+  test('compiles without error', () => {
+    expect(files.length).toBeGreaterThan(0)
+  })
+
+  test('a specialized swap function is generated for nums', () => {
+    const specialized = files.filter(f => f.path.includes('swap_elems__arr_'))
+    expect(specialized.length).toBeGreaterThan(0)
+  })
+
+  test('specialized swap function contains "with storage" for dynamic index access', () => {
+    const specialized = files.filter(f => f.path.includes('swap_elems__arr_'))
+    expect(specialized.length).toBeGreaterThan(0)
+    const allContent = specialized.map(f => f.content).join('\n')
+    expect(allContent).toContain('with storage')
+  })
+
+  test('specialized swap function references the correct array path (nums)', () => {
+    const specialized = files.filter(f => f.path.includes('swap_elems__arr_'))
+    const allContent = specialized.map(f => f.content).join('\n')
+    expect(allContent).toContain('nums')
+  })
+
+  test('test function calls the specialized swap variant', () => {
+    const testBody = getFunctionBody(files, 'test')
+    expect(testBody).toContain('swap_elems__arr_')
+  })
+
+  test('original unspecialized swap is not called from test', () => {
+    const testBody = getFunctionBody(files, 'test')
+    // Should not call plain 'swap_elems' (only the specialized variant)
+    expect(testBody).not.toMatch(/function test:swap_elems\b(?!__arr_)/)
+  })
+})

package/src/__tests__/e2e/for-in-array.test.ts

@@ -0,0 +1,62 @@
+/**
+ * E2E tests for the `for (let v in arr, len)` syntax sugar.
+ */
+
+import { compile } from '../../emit/compile'
+
+function getFiles(files: { path: string; content: string }[]): string {
+  return files.map(f => f.content).join('\n')
+}
+
+describe('e2e: for-in-array syntax sugar', () => {
+  test('for in array basic compiles without error', () => {
+    const src = `
+      @keep fn test() {
+        let nums: int[] = [10, 20, 30];
+        let len: int = 3;
+        for (let v in nums, len) {
+          scoreboard_add("#sum", "test", v);
+        }
+      }
+    `
+    expect(() => compile(src, { namespace: 'test' })).not.toThrow()
+  })
+
+  test('for in array generates dynamic index access (with storage)', () => {
+    const src = `
+      @keep fn test() {
+        let nums: int[] = [10, 20, 30];
+        let len: int = 3;
+        for (let v in nums, len) {
+          scoreboard_add("#sum", "test", v);
+        }
+      }
+    `
+    const result = compile(src, { namespace: 'test' })
+    const allContent = getFiles(result.files)
+    expect(allContent).toContain('with storage')
+  })
+
+  test('for in array with len variable compiles', () => {
+    const src = `
+      @keep fn loop_sum(arr: int[], n: int): void {
+        for (let item in arr, n) {
+          scoreboard_add("#total", "obj", item);
+        }
+      }
+    `
+    expect(() => compile(src, { namespace: 'test' })).not.toThrow()
+  })
+
+  test('for in array with literal len compiles', () => {
+    const src = `
+      @keep fn test() {
+        let data: int[] = [1, 2, 3, 4, 5];
+        for (let x in data, 5) {
+          scoreboard_add("#res", "test", x);
+        }
+      }
+    `
+    expect(() => compile(src, { namespace: 'test' })).not.toThrow()
+  })
+})