redscript-mc 2.6.0 → 3.0.0

package/.github/workflows/ci.yml

@@ -10,6 +10,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Checkout redscript-docs
+        uses: actions/checkout@v4
+        with:
+          repository: bkmashiro/redscript-docs
+          path: redscript-docs
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -17,6 +22,12 @@ jobs:
       - run: npm install
       - run: npm run build
       - run: npm test
+      - name: Run MC integration tests (offline - graceful skip)
+        run: npx jest --testPathPattern="mc-integration" --forceExit
+        env:
+          MC_OFFLINE: "true"
+      - name: Check stdlib docs are up to date
+        run: npx ts-node scripts/gen-docs.ts --check --docs-dir redscript-docs
 
   build:
     runs-on: ubuntu-latest

package/CHANGELOG.md

@@ -2,6 +2,95 @@
 
 All notable changes to RedScript will be documented in this file.
 
+## [Unreleased]
+
+## [3.0.0] - 2026-03-21
+
+### Added
+
+#### Language / Compiler
+- **`match` expression** — pattern-match on int / enum values; compiles to `execute if score` chains with exhaustiveness checking
+- **`break` / `continue` statements** — structured loop control now lowers cleanly through HIR/MIR/LIR and is covered by unit, e2e, and MC integration tests
+- **`do { ... } while (...)` and `repeat N { ... }` loops** — post-test and fixed-count loop forms added to the parser, lowering pipeline, and compiler tests
+- **`const` declarations** — compile-time constants inline at use sites for simpler generated datapacks and cleaner constant propagation
+- **`@deprecated("message")` decorator** — compile-time warnings for deprecated APIs and migration guidance at call sites
+- **`for item in array` iteration** — `for x in arr { … }` syntax sugar; desugars to `while idx < arr.len() { let x = arr[idx]; idx++ }` in HIR; generates loop-header / loop-body / loop-exit mcfunction splits
+- **`arr.len()` — literal constant + dynamic runtime** — literal arrays (`[1,2,3].len()`) fold to a compile-time constant (`scoreboard players set`); function-parameter and heap arrays use the new `nbt_list_len` MIR instruction which lowers to `execute store result score … run data get storage`
+- **`@on(EventType)` full compiler implementation** — compiler generates Minecraft function-tag JSON and wires an `events.mcrs` dispatcher automatically; supported events: `PlayerJoin`, `PlayerDeath`, `EntityKill`, `ItemUse` (each with correctly typed parameters)
+
+#### Standard Library
+- **`Result<T>`** — new stdlib result type with `Ok` / `Err` variants and helper functions for explicit error handling
+- **`state.mcrs`** — persistent entity/global state management stdlib module
+- **`dialog.mcrs`** — NPC dialog trees with choice branching and callback support
+- **`scheduler.mcrs`** — tick-budget-aware task scheduler (coroutine-compatible)
+- **`linalg.mcrs`** — double-precision linear algebra: `vec2_add/sub/scale/dot/length/normalize`, `vec3_cross`, `mat2x2 / mat3x3 / mat4x4` multiply, Cramer's rule solver for 2×2 and 3×3 systems
+- **`fft.mcrs`** — Discrete Fourier Transform with a `@coroutine` variant for in-game use; supports transforms up to n=64; quarter-wave symmetry test now enabled after related compiler fix
+- **`ecs.mcrs`** — Entity Component System: `register_component`, `get_component`, `has_component`; built-in Health and Velocity components; `@tick` system iteration via `foreach(entity[tag=has_<component>])`; fills the gap that Java datapacks have vs Bedrock's native component model
+- **`sort.mcrs` v2** — coroutine-based bottom-up merge sort for large arrays (n > 64); yields every 20 comparisons to stay within the 20 ms tick budget
+
+#### Examples
+- **7 new example programs** — `rpg/health_system`, `rpg/boss_fight`, `rpg/inventory`, `game/tower_defense`, `game/racing`, `math/physics_sim`, and `util/debug_hud`
+
+#### Documentation
+- **Language reference expansion** — `docs/LANGUAGE_REFERENCE.md` now documents the current type system plus expression, statement, decorator, execute-context, selector, coordinate, and builtin semantics in one place
+
+#### Tests
+- **Coverage increased further across compiler subsystems** — `src/typechecker/index.ts` branch coverage reached **88.33%**, `src/optimizer/**` line coverage reached **96.21%** (~97%), and `src/optimizer/coroutine.ts` function coverage reached **94.23%**
+- **MC integration tests** for `@on(PlayerJoin)` and `@on(PlayerDeath)` added to the test suite
+
+#### Runtime
+- **`MCRuntime`** `storage_get_int` / `storage_set_array` builtins — allows `sin` / `cos` (which rely on NBT storage) to execute correctly in unit test environment without a running Minecraft instance
+
+### Fixed
+
+#### Compiler
+- **Dynamic array indexing on function parameters** — `arr[i]` inside a callee now resolves to the correct per-call-site monomorphized NBT path; previously the binding was shadowed and produced a wrong path
+- **`scoreboard_get` / `scoreboard_set` Player selector** — emits `@s` (not an empty string) when the Player argument resolves to the executing entity
+
+#### stdlib
+- **`linalg.mcrs`** — `double_sqrt` return-type cast corrected; prevents type mismatch in chained double-precision expressions
+
+#### Events
+- **`@on(BlockBreak)`** — constrained to `Player` parameter only; Minecraft does not expose block type at function-tag dispatch time and including it caused a compile error
+
+---
+
+## [2.6.1] - 2026-03-20
+
+### Fixed
+
+#### Compiler
+- **Dynamic array indexing on function parameters** — `arr[i]` in callee functions now correctly resolves the per-call-site monomorphized binding (regression introduced in v2.4.0 array-reference work)
+- **`scoreboard_get` / `scoreboard_set` Player param** — selector now correctly emits `@s` instead of an empty string when the Player argument is the executing entity
+
+#### stdlib
+- **`linalg.mcrs`** — `double_sqrt` return type cast fixed; avoids type error in chained double expressions
+
+#### Events
+- **`@on(BlockBreak)`** — removed block-type parameter; MC provides no runtime block type info at function-tag dispatch
+
+---
+
+## [2.6.0] - 2026-03-19
+
+### Compiler
+
+- **Parser** now emits `span.endLine` for function declarations — LSP clients receive accurate scope ranges for hovers and highlights
+- **String concatenation error:** `"string" + var` now raises a compile-time error with a hint to use f-string interpolation instead of silently producing broken output
+- **F-string MC text components:** f-string interpolation inside `tell`, `title`, `subtitle`, `actionbar`, and `announce` now emits proper Minecraft JSON text components (e.g. `["", {"score": …}, " text"]`) instead of raw concatenated strings
+- **LSP inlay hints:** the language server now shows inferred types next to unannotated `let` bindings inline in the editor
+
+### stdlib
+
+- **`mat3_mul` / `mat4_mul`** — 3×3 and 4×4 matrix multiply helpers (fixed-point ×10000 scale) in `stdlib/matrix.mcrs`
+- **`bigint_div`** — full arbitrary-precision long division returning both quotient and remainder in `stdlib/bigint.mcrs`
+- **`graph.mcrs`** — adjacency-list graph library: `graph_add_edge`, BFS, DFS, `has_path`, and `shortest_path` (Dijkstra's algorithm)
+- **`ode.mcrs`** — Runge-Kutta 4th-order ODE solver supporting exponential decay/growth and sine oscillator systems
+
+### VSCode Extension
+
+- **v1.3.17:** inlay hints for inferred `let` binding types; improved variable hover tooltips showing type and declaration site
+
 ## [2.5.0] - 2026-03-17
 
 ### Added

package/README-benchmarks.md

@@ -0,0 +1,48 @@
+# Benchmark Suite
+
+RedScript now ships two benchmark entrypoints under `benchmarks/`.
+
+## What They Measure
+
+`benchmarks/compiler-perf.ts`
+
+- Generates synthetic RedScript programs at roughly 10, 100, and 1000 lines.
+- Measures end-to-end compiler stage time for:
+  - `parse`: preprocess, lex, parse, import merge, typecheck
+  - `HIR`: AST to HIR lowering and monomorphization
+  - `MIR`: MIR lowering, optimization, coroutine transform, and LIR lowering/optimization
+  - `emit`: datapack file emission
+- Emits a JSON report to stdout.
+
+`benchmarks/stdlib-complexity.ts`
+
+- Compiles every file in `src/stdlib/`.
+- Reports emitted instruction count, file count, and artifact size.
+- Compares three optimization presets:
+  - `O0`: no MIR/LIR optimization passes
+  - `O1`: current default optimization pipeline
+  - `O2`: `O1` plus a second MIR/LIR optimization round after coroutine lowering
+
+## How To Run
+
+Run the default compiler benchmark:
+
+```bash
+npm run bench
+```
+
+Write the compiler benchmark report to a file:
+
+```bash
+npx ts-node benchmarks/compiler-perf.ts --iterations 5 --output benchmarks/compiler-perf.report.json
+```
+
+Run the stdlib complexity benchmark:
+
+```bash
+npx ts-node benchmarks/stdlib-complexity.ts --output benchmarks/stdlib-complexity.report.json
+```
+
+## Baseline
+
+`benchmarks/baseline.json` stores one recorded run of both benchmarks on the local machine. Treat it as a local baseline, not a cross-machine performance target.

package/README-vscode-test.md

@@ -0,0 +1,251 @@
+# VSCode Extension Manual Test Guide
+
+The RedScript VSCode extension (`editors/vscode/`) provides syntax highlighting,
+code completion, hover documentation, and error diagnostics for `.mcrs` files.
+Because the extension runs inside a VS Code host process, automated integration
+tests require the `@vscode/test-electron` or `@vscode/test-cli` harness and an
+Xvfb display server (or Electron headless mode).  The steps below describe how
+to run the manual test cases by hand, plus a scaffold for future automation.
+
+---
+
+## 1. Prerequisites
+
+```bash
+cd editors/vscode
+npm install
+npm run build   # produces out/ from src/
+```
+
+Install the extension from VSIX into VS Code:
+
+```bash
+code --install-extension redscript-vscode-*.vsix
+```
+
+Or open `editors/vscode/` in VS Code and press **F5** to launch an Extension
+Development Host.
+
+---
+
+## 2. Test Cases
+
+### 2.1 Syntax Highlighting – `.mcrs` file loaded
+
+**File to open:** any `.mcrs` file, e.g. `examples/hello.mcrs`.
+
+Expected token colourisation (use **Developer: Inspect Editor Tokens and Scopes**):
+
+| Token                  | Expected scope                              |
+|------------------------|---------------------------------------------|
+| `fn`                   | `keyword.declaration.redscript`             |
+| `let`                  | `keyword.declaration.redscript`             |
+| `if`, `while`, `return`| `keyword.control.redscript`                 |
+| `true`, `false`        | `constant.language.boolean.redscript`       |
+| `self`                 | `variable.language.self.redscript`          |
+| `int`, `bool`, `string`| `support.type.primitive.redscript`          |
+| `@keep`, `@load`       | `meta.decorator.redscript`                  |
+| `// comment`           | `comment.line.double-slash.redscript`       |
+| `"hello"`              | `string.quoted.double.redscript`            |
+| `42`, `3.14`           | `constant.numeric.redscript`                |
+| `@p`, `@a`, `@e`       | `entity.name.selector.redscript`            |
+
+**Pass criteria:** every token above shows the expected scope in the inspector.
+
+---
+
+### 2.2 Code Completion – keywords and builtins
+
+1. Create a new file `test.mcrs` with:
+   ```redscript
+   fn example() {
+       sc
+   ```
+2. Place the cursor after `sc` and press **Ctrl+Space**.
+
+**Expected:** `scoreboard_get`, `scoreboard_set`, `scoreboard_add` appear in the
+completion list with their signatures.
+
+3. Type `say(` and hover over it.
+
+**Expected:** completion or IntelliSense shows `say(msg: string)` signature.
+
+4. Type `fn ` at the top level.
+
+**Expected:** snippet for a function declaration is offered.
+
+---
+
+### 2.3 Error Diagnostics – red underline on syntax errors
+
+1. Open or create `test.mcrs` with an intentional error:
+   ```redscript
+   fn broken() {
+       let x: int = ;   // missing right-hand side
+   }
+   ```
+2. Wait ≤ 600 ms (the debounce interval).
+
+**Expected:** the `;` (or the assignment) is underlined in red; the Problems
+panel shows an error from the RedScript compiler.
+
+3. Fix the error (`let x: int = 42;`) and save.
+
+**Expected:** the red underline disappears within ~600 ms.
+
+---
+
+### 2.4 Hover Documentation
+
+1. Open any `.mcrs` file that uses a builtin, e.g.:
+   ```redscript
+   fn t() { scoreboard_set("@s", "score", 10); }
+   ```
+2. Hover over `scoreboard_set`.
+
+**Expected:** a Markdown hover card appears showing:
+- Signature: `scoreboard_set(target, objective, value)`
+- Description from the builtin docs table in `src/hover.ts`
+- Example usage (if present)
+
+3. Hover over a user-defined function in the same file.
+
+**Expected:** if the function has a `///` doc comment immediately above it,
+that comment text appears in the hover.
+
+---
+
+## 3. Automated Test Scaffold (future)
+
+The following test file can be placed at
+`editors/vscode/src/test/extension.test.ts` once `@vscode/test-electron` is
+added as a dev dependency and a Mocha runner is configured in `package.json`.
+
+```typescript
+// editors/vscode/src/test/extension.test.ts
+// Automated integration tests for the RedScript VSCode extension.
+// Run via: npx @vscode/test-electron --extensionDevelopmentPath=. --extensionTestsPath=./out/test
+//
+// Requires: @vscode/test-electron, mocha, @types/mocha
+
+import * as assert from 'assert'
+import * as path from 'path'
+import * as vscode from 'vscode'
+
+const FIXTURE = path.join(__dirname, '..', '..', 'fixtures', 'test.mcrs')
+
+suite('RedScript VSCode Extension', function () {
+  this.timeout(10_000)
+
+  let document: vscode.TextDocument
+
+  suiteSetup(async () => {
+    // Ensure the extension is activated before tests run.
+    await vscode.extensions.getExtension('redscript.redscript-vscode')?.activate()
+    document = await vscode.workspace.openTextDocument(FIXTURE)
+    await vscode.window.showTextDocument(document)
+    // Allow diagnostics to settle (debounce is 600 ms).
+    await new Promise(r => setTimeout(r, 800))
+  })
+
+  // ── 2.1 Syntax Highlighting ─────────────────────────────────────────────────
+  test('grammar is registered for .mcrs files', () => {
+    assert.strictEqual(document.languageId, 'redscript')
+  })
+
+  // ── 2.2 Completions ─────────────────────────────────────────────────────────
+  test('completion list includes scoreboard_set', async () => {
+    const pos = new vscode.Position(5, 10)  // after "sc" on line 5
+    const list = await vscode.commands.executeCommand<vscode.CompletionList>(
+      'vscode.executeCompletionItemProvider',
+      document.uri,
+      pos
+    )
+    const labels = (list?.items ?? []).map(i =>
+      typeof i.label === 'string' ? i.label : i.label.label
+    )
+    assert.ok(labels.some(l => l.includes('scoreboard_set')), `Expected scoreboard_set in: ${labels.join(', ')}`)
+  })
+
+  test('completion list includes keyword "fn"', async () => {
+    const pos = new vscode.Position(0, 0)
+    const list = await vscode.commands.executeCommand<vscode.CompletionList>(
+      'vscode.executeCompletionItemProvider',
+      document.uri,
+      pos
+    )
+    const labels = (list?.items ?? []).map(i =>
+      typeof i.label === 'string' ? i.label : i.label.label
+    )
+    assert.ok(labels.some(l => l === 'fn'), `Expected "fn" keyword in completions`)
+  })
+
+  // ── 2.3 Diagnostics ─────────────────────────────────────────────────────────
+  test('no diagnostics on valid file', async () => {
+    const diags = vscode.languages.getDiagnostics(document.uri)
+    assert.strictEqual(diags.length, 0, `Unexpected diagnostics: ${diags.map(d => d.message).join('; ')}`)
+  })
+
+  test('syntax error produces a diagnostic', async () => {
+    const edit = new vscode.WorkspaceEdit()
+    const errorLine = 'fn broken() { let x: int = ; }\n'
+    edit.insert(document.uri, new vscode.Position(document.lineCount, 0), errorLine)
+    await vscode.workspace.applyEdit(edit)
+    await new Promise(r => setTimeout(r, 800))
+
+    const diags = vscode.languages.getDiagnostics(document.uri)
+    assert.ok(diags.length > 0, 'Expected at least one error diagnostic for broken syntax')
+  })
+
+  // ── 2.4 Hover ───────────────────────────────────────────────────────────────
+  test('hover on scoreboard_set returns documentation', async () => {
+    // Position on "scoreboard_set" in the fixture file (line 2, col 4)
+    const pos = new vscode.Position(2, 6)
+    const hovers = await vscode.commands.executeCommand<vscode.Hover[]>(
+      'vscode.executeHoverProvider',
+      document.uri,
+      pos
+    )
+    const text = (hovers ?? [])
+      .flatMap(h => h.contents)
+      .map(c => (typeof c === 'string' ? c : c.value))
+      .join('\n')
+    assert.ok(text.includes('scoreboard'), `Expected hover docs to mention 'scoreboard', got: ${text}`)
+  })
+})
+```
+
+A matching fixture file (`editors/vscode/fixtures/test.mcrs`):
+
+```redscript
+// Fixture for VSCode extension integration tests
+fn example() {
+    scoreboard_set("@s", "score", 10);
+    say("hello");
+}
+
+// sc   ← cursor here for completion test (line 5, col 10)
+```
+
+---
+
+## 4. Build & Run (CI)
+
+Add to `editors/vscode/package.json` scripts when the automated scaffold is ready:
+
+```json
+"test": "node ./out/test/runTests.js"
+```
+
+And install:
+
+```bash
+npm install --save-dev @vscode/test-electron mocha @types/mocha
+```
+
+For headless CI:
+
+```bash
+Xvfb :99 -screen 0 1024x768x24 &
+DISPLAY=:99 npm test
+```

package/README.md

@@ -2,14 +2,14 @@
 
 <img src="./logo.png" alt="RedScript Logo" width="64" />
 
-<img src="https://img.shields.io/badge/RedScript-2.1.1-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
+<img src="https://img.shields.io/badge/RedScript-2.6.2-red?style=for-the-badge&logo=minecraft&logoColor=white" alt="RedScript" />
 
 **A typed scripting language that compiles to Minecraft datapacks.**
 
 Write clean game logic. RedScript handles the scoreboard spaghetti.
 
 [![CI](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bkmashiro/redscript/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-1123%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
+[![Tests](https://img.shields.io/badge/tests-1901%20passing-brightgreen)](https://github.com/bkmashiro/redscript)
 [![npm](https://img.shields.io/npm/v/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
 [![npm downloads](https://img.shields.io/npm/dm/redscript-mc?color=cb3837)](https://www.npmjs.com/package/redscript-mc)
 [![VSCode](https://img.shields.io/badge/VSCode-Extension-007ACC?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=bkmashiro.redscript-vscode)
@@ -87,21 +87,6 @@ let frame: int = 0;
 
 ---
 
-### What's New in v2.1.x
-
-- **`enum` + `match` dispatch** — zero-runtime-overhead state machines; the compiler folds enum variants to integer constants and uses `execute if score` dispatch with no heap allocation
-- **Multi-return values** — `fn divmod(a: int, b: int): (int, int)` unpacks to separate scoreboard slots; no struct wrapper needed
-- **Generics** — `fn max<T>(a: T, b: T): T` is fully monomorphized at compile time; no boxing, no indirection
-- **`Option<T>` null safety** — `Some(x)` / `None` with `if let Some(x) = opt` pattern binding; safe access to optional values without sentinel integers
-- **`@coroutine(batch=N)`** — spreads a heavy loop across multiple ticks (`batch=50` means 50 iterations/tick), avoiding `maxCommandChainLength` hits on large workloads
-- **`@schedule(ticks=N)`** — delays a function call by N game ticks; compiles to `schedule function` with automatic namespace scoping
-- **Module system** — `module math;` declares a named module; consumers `import math::sin` to tree-shake individual symbols
-- **Multi-version targets** — `--mc-version 1.20.2` switches emit strategy (macro sub-functions vs. legacy scoreboards) for the target server version
-- **Source maps** — `--source-map` emits a `.mcrs.map` sidecar that maps each `.mcfunction` line back to the original source; enables in-editor debugging
-- **LSP: hover + completion for builtins & decorators** — 50+ builtin functions and all decorators (`@tick`/`@load`/`@coroutine`/`@schedule`/`@on_trigger`) now show inline docs on hover
-
----
-
 ### Quick Start
 
 #### Option 1: Online IDE (No Install)
@@ -325,38 +310,11 @@ import "stdlib/player"    // health, alive check, range
 import "stdlib/cooldown"  // per-player cooldown tracking
 ```
 
-Custom library paths can be added with `--include <dir>` so your own modules work the same way.
-
-### Standard Library
-
 All stdlib files use `module library;` — only the functions you actually call are compiled in.
 
 > Parts of the standard library are inspired by [kaer-3058/large_number](https://github.com/kaer-3058/large_number), a comprehensive math library for Minecraft datapacks.
 
-```rs
-import "stdlib/math"            // abs, sign, min, max, clamp, lerp, isqrt, sqrt_fixed,
-                                // pow_int, gcd, lcm, sin_fixed, cos_fixed, map, ceil_div,
-                                // log2_int, mulfix, divfix, smoothstep, smootherstep
-
-import "stdlib/vec"             // dot2d, cross2d, length2d_fixed, distance2d_fixed,
-                                // manhattan, chebyshev, atan2_fixed, normalize2d_x/y,
-                                // rotate2d_x/y, lerp2d_x/y, dot3d, cross3d_x/y/z,
-                                // length3d_fixed
-
-import "stdlib/advanced"        // fib, is_prime, collatz_steps, digit_sum, reverse_int,
-                                // mod_pow, hash_int, noise1d, bezier_quad,
-                                // mandelbrot_iter, julia_iter, angle_between,
-                                // clamp_circle_x/y, newton_sqrt, digital_root
-
-import "stdlib/bigint"          // bigint_init, bigint_from_int_a/b, bigint_add/sub/mul,
-                                // bigint_compare, bigint_mul_small, bigint_fib
-                                // — up to 32 decimal digits, runs on MC scoreboard
-
-import "stdlib/player"          // is_alive, in_range, get_health
-import "stdlib/timer"           // start_timer, tick_timer, has_elapsed
-import "stdlib/cooldown"        // set_cooldown, check_cooldown
-import "stdlib/mobs"            // ZOMBIE, SKELETON, CREEPER, ... (60+ constants)
-```
+Custom library paths can be added with `--include <dir>` so your own modules work the same way.
 
 **Example — computing Fibonacci(50) in-game:**
 
@@ -395,36 +353,6 @@ node dist/cli.js compile examples/coroutine-demo.mcrs -o ~/mc-server/datapacks/d
 
 ---
 
-### Further Reading
-
-| | |
-|---|---|
-| 📖 [Language Reference](docs/LANGUAGE_REFERENCE.md) | Full syntax & type system |
-| 🔧 [Builtins](https://redscript-docs.pages.dev/Builtins) | All 34+ MC builtin functions |
-| ⚡ [Optimizer](https://redscript-docs.pages.dev/Optimizer) | How the optimizer works |
-| 🧱 [Structure Target](docs/STRUCTURE_TARGET.md) | Compile to NBT command block structures |
-| 🧪 [Integration Testing](https://redscript-docs.pages.dev/Integration-Testing) | Test against a real Paper server |
-| 🏗 [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md) | Compiler internals |
-
----
-
-### What's New in v1.2.27
-
-- **BigInt confirmed working in real Minecraft** (`bigint.mcrs`): arbitrary precision integers on MC scoreboard + NBT — base 10,000 × 8 limbs = up to 32 decimal digits; `bigint_add`, `bigint_sub`, `bigint_compare`, `bigint_mul`, `bigint_fib(50)` = 12,586,269,025 all verified on Paper 1.21.4
-- **`storage_set_int` macro fix**: dynamic NBT array writes now use `execute store result storage` instead of `data modify set value $(n)` — avoids a silent Minecraft macro substitution bug with integer values
-- **Full stdlib** (`math.mcrs`, `vec.mcrs`, `advanced.mcrs`, `bigint.mcrs`, `showcase.mcrs`): 18 math functions, 14 vector geometry functions, 20+ advanced number-theory and fractal functions
-- **`module library;` pragma**: tree-shaking for library files — stdlib never bloats your pack
-- **`storage_get_int` / `storage_set_int` builtins**: dynamic NBT int array read/write with runtime indices via MC 1.20.2+ macro sub-functions
-- **`@require_on_load(fn)` decorator**: declarative load-time dependency tracking for sin/cos/atan table initializers
-
-### What's New in v1.2.26
-
-- **Math stdlib** (`math.mcrs`): 18 fixed-point functions — `abs`, `sign`, `min`, `max`, `clamp`, `lerp`, `isqrt`, `sqrt_fixed`, `pow_int`, `gcd`, `lcm`, `sin_fixed`, `cos_fixed`, `map`, `ceil_div`, `log2_int`, `mulfix`, `divfix`, `smoothstep`, `smootherstep`
-- **Vector stdlib** (`vec.mcrs`): 2D and 3D geometry — dot/cross products, `length2d_fixed`, `atan2_fixed` (binary search, O(log 46)), `normalize2d`, `rotate2d`, `lerp2d`, full 3D cross product
-- **Advanced stdlib** (`advanced.mcrs`): number theory (`fib`, `is_prime`, `collatz_steps`, `gcd`, `mod_pow`), hash/noise (`hash_int` splitmix32, `noise1d`), curves (`bezier_quad`), fractals (`mandelbrot_iter`, `julia_iter`), geometry experiments
-- **BigInt** (`bigint.mcrs`): arbitrary precision integers — base 10,000 × 8 limbs = up to 32 decimal digits; `bigint_add/sub/compare/mul/fib` running on MC scoreboard + NBT storage
-- **Compiler fixes**: `isqrt` large-number convergence, optimizer copy propagation alias invalidation, cross-function variable collision, MCRuntime array-index regex
-
 ### Changelog Highlights
 
 #### v1.2.27 (2026-03-14)