ranger-compiler 3.5.0 → 3.5.2

package/LICENSE

@@ -2,7 +2,9 @@ Ranger uses multiple licenses.
 
 Ranger-authored source code outside the gallery/ directory is licensed
 under the MIT License, unless a file or subdirectory explicitly states
-otherwise. See LICENSE-MIT.
+otherwise. See LICENSE-MIT. This includes the compiler, the runtime,
+lib/ — and with it the EVG layout engine (lib/evg) and the image codecs
+(lib/image), which moved out of gallery/ and to MIT in September 2026.
 
 Ranger-authored source code under gallery/ is licensed under the GNU
 Affero General Public License version 3 or later (AGPL-3.0-or-later),

package/README.md

@@ -1,6 +1,6 @@
 # Ranger cross language compiler
 
-**Version 3.3.0** | Status: `experimental`
+**Version 3.5.1** | Status: `experimental`
 
 **Licensing:** Ranger-authored compiler and language sources are MIT licensed,
 unless a file says otherwise. Ranger-authored applications and technology
@@ -73,19 +73,56 @@ const host = ProcessUiHost.__singleton();
 host.notifyPath = (path) => { /* sync view model + re-render */ };
 ```
 
-**Docs:** [PROCESS_MVP.md](PROCESS_MVP.md) (scope), [PROCESS_STATUS.md](PROCESS_STATUS.md) (compiler checklist), [PROCESS_RUNTIME_INVARIANTS.md](PROCESS_RUNTIME_INVARIANTS.md) (dispatch turn / one notify), [PROCESS_UI_NOTIFY.md](PROCESS_UI_NOTIFY.md) (notify batching), [PROCESS_UI_VIEW_MODELS.md](PROCESS_UI_VIEW_MODELS.md) (view DTO assignment). **Gallery:** [process_counter_board](gallery/process_counter_board/README.md) (Vite + React host for `@process`).
+**Docs:** [PROCESS_MVP.md](docs/plans/process/PROCESS_MVP.md) (scope), [PROCESS_STATUS.md](docs/plans/process/PROCESS_STATUS.md) (compiler checklist), [PROCESS_RUNTIME_INVARIANTS.md](docs/plans/process/PROCESS_RUNTIME_INVARIANTS.md) (dispatch turn / one notify), [PROCESS_UI_NOTIFY.md](docs/plans/process/PROCESS_UI_NOTIFY.md) (notify batching), [PROCESS_UI_VIEW_MODELS.md](legacy/docs/PROCESS_UI_VIEW_MODELS.md) (view DTO assignment). **Gallery:** [process_counter_board](gallery/process_counter_board/README.md) (Vite + React host for `@process`).
+
+## Getting started with Claude Code
+
+Two commands give a Claude Code session everything it needs to write Ranger —
+in any directory, including an empty one:
+
+```
+/plugin marketplace add terotests/Ranger
+/plugin install ranger@ranger
+```
+
+Then, in a folder with nothing in it:
+
+```bash
+npm init -y && npm i -D ranger-compiler
+```
+
+…and ask for a program. The plugin carries the language's traps, a build
+command that **fails when the compile fails** (compilers through 3.5.1 printed
+`[FAIL]` and exited 0, which made `&&` run the previous build), the EVG and
+Rave skills, and
+`/ranger:example` — worked examples indexed by what they do, with the command
+for each.
+
+```bash
+cp "$CLAUDE_PLUGIN_ROOT/examples/calc/Calc.rgr" .
+rgr run Calc.rgr              # a parser and evaluator
+rgr run Calc.rgr -l=python    # …the same source, through Python
+rgr run Calc.rgr -l=go        # …and Go
+```
+
+[`plugins/ranger/README.md`](plugins/ranger/README.md) lists what is in it, and
+[RangerStarter](https://github.com/terotests/RangerStarter) is the same thing as
+a project you clone: the skills are already in `.claude/skills/`, and `npm start`
+prints on a cold checkout.
 
 ## Where To Start
 
 - [Documentation site](https://terotests.github.io/Ranger/docs/) — install, first program, types, optionals, and the **generated operator reference** (838 operators, compiled from the sources of the commit that publishes the site, so it cannot drift)
 - [The front page](https://terotests.github.io/Ranger/) — what Ranger is, the targets, the platforms and the gallery (`landing/`)
 - [Online playground](https://terotests.github.io/Ranger/playground/) — try Ranger in the browser (`playground/`, Vite + current compiler)
+- [UI gallery](https://terotests.github.io/EVGUI/) — EVG controllers measured against Radix (controllers in `gallery/ui/`; the demos live in [terotests/EVGUI](https://github.com/terotests/EVGUI))
 - `README.md` - language overview, installation, and syntax notes
 - [`gallery/README.md`](gallery/README.md) - index of the application stack (AGPL): EVG, Office, DataGrid, parsers, games, and `@process` host apps
 - [`LICENSING.md`](LICENSING.md) - MIT compiler vs AGPL gallery
 - [`TARGET_NOTES.md`](TARGET_NOTES.md) - what each target language supports and where it falls short
-- [`PLAN_FORMATS.md`](PLAN_FORMATS.md) — the architecture for reading more than three file formats: the layer stack, the internal models, and the phased roadmap after DOCX/XLSX/PPTX. Phase 1 is `.odp` beside `.pptx`, run as the experiment that proves or disproves the shared scene
-- [`PLAN_API_DOCS.md`](PLAN_API_DOCS.md) — the design for `doc { … }` declarations: API metadata attached to a Ranger declaration that never restates what the compiler already knows, the `no doc` / `doc` / `doc public` visibility rule, a canonical **ApiIR** that names a logical module and no namespace, and the outputs built from it — native doc comments and annotations per target (XML doc, TSDoc, DocC, KDoc, rustdoc, Javadoc, dartdoc, Doxygen, docstrings), and the language × platform split that separates C# from Unity and Dart from Flutter
+- [`PLAN_FORMATS.md`](docs/plans/PLAN_FORMATS.md) — the architecture for reading more than three file formats: the layer stack, the internal models, and the phased roadmap after DOCX/XLSX/PPTX. Phase 1 is `.odp` beside `.pptx`, run as the experiment that proves or disproves the shared scene
+- [`PLAN_API_DOCS.md`](docs/plans/PLAN_API_DOCS.md) — the design for `doc { … }` declarations: API metadata attached to a Ranger declaration that never restates what the compiler already knows, the `no doc` / `doc` / `doc public` visibility rule, a canonical **ApiIR** that names a logical module and no namespace, and the outputs built from it — native doc comments and annotations per target (XML doc, TSDoc, DocC, KDoc, rustdoc, Javadoc, dartdoc, Doxygen, docstrings), and the language × platform split that separates C# from Unity and Dart from Flutter
+- [`docs/plans/`](docs/plans/README.md) — the plans that are still open: language, shapes, ownership, LLVM/WASM, the portable JS stdlib, formats and tooling. Finished ones move to [`legacy/docs/`](legacy/docs/README.md)
 - [`CHANGELOG.md`](CHANGELOG.md) - version history
 - [`AGENTS.md`](AGENTS.md) — git/PR rules and Ranger gotchas for AI agents; links the [FAQ](https://terotests.github.io/Ranger/docs/faq/)
 - `ai/` — short offline notes for assistants (`README.md`, `QUICKREF.md`, `GRAMMAR.md`, `INTROSPECTION.md`); prefer the docs site when online
@@ -106,7 +143,7 @@ cross-target gate: Go, Kotlin, Python, C#, Dart and Swift 6 each compile, and
 where the toolchain is on `PATH` they build and answer the Node benchmark cases
 (`npm run test:tsengine`). Dart also keeps the `gallery/ts_parser` golden
 (AST identical to the JS `-d` demo). Details:
-[`TS_ENGINE_PERF.md`](TS_ENGINE_PERF.md), [`TARGET_NOTES.md`](TARGET_NOTES.md).
+[`TS_ENGINE_PERF.md`](gallery/ranger_engine/TS_ENGINE_PERF.md), [`TARGET_NOTES.md`](TARGET_NOTES.md).
 
 **Thinner CI** — `PHP`, `Java 7` and `Scala` still have operator templates and
 appear in the syntax-app matrix, but they are not on the large-engine golden
@@ -158,6 +195,20 @@ Regenerate the fixture list with `node scripts/generate-conformance-table.mjs`.
 
 ## Quick start
 
+You do not need this repository to write a program in Ranger. This is the
+compiler, the gallery and their own test corpus — what you clone to work *on*
+Ranger. To start a program *in* it,
+[RangerStarter](https://github.com/terotests/RangerStarter) is a project already
+built around the npm compiler: two source files, a test, a build loop that fails
+when the compile fails, all fourteen targets, and the agent skills. MIT.
+
+```bash
+git clone https://github.com/terotests/RangerStarter my-app
+cd my-app && npm install
+npm start          # hei maailma
+npm run targets    # the same source as Swift, Kotlin, Rust, Go, C++, …
+```
+
 Source files use the `.rgr` extension (`.clj` is the legacy extension and still
 works) and the CLI is `rgrc`:
 
@@ -214,12 +265,14 @@ def c (Config.__singleton())
 **Optionals have to be wrapped and unwrapped.** Any variable declared without a
 value is optional, and several operators — `get` on a hash above all — always
 return one. Reading the value takes `unwrap` / `!!`, or `??` for a default;
-`wrap` makes an optional out of a plain value. Forgetting this shows up as a
+`wrap` makes an optional out of a plain value. Inside `if (!null? x) { … }`
+an optional object is narrowed: `x.field` and `x.method()` need no `unwrap`
+there. Forgetting this shows up as a
 type error between `T` and `<optional>T`. See
 [Optional variables](#optional-variables).
 
 **Extending the language does not mean recompiling the compiler.**
-`compiler/Lang.rgr` is read at compile time, not baked into `bin/output.js`.
+`compiler/Lang.rgr` is read at compile time, not baked into `dist/rgrc.js`.
 Add or change an operator template there, and the very next compile uses it —
 no `npm run compile` in between. The compiler looks for `Lang.rgr` in the
 working directory first, so a copy beside your sources overrides the installed
@@ -384,7 +437,7 @@ Two things about that table are worth knowing before quoting it. **Every row is
 checked against Node's answer** and the command exits non-zero if any engine
 disagrees — a fast wrong answer is not a result. And **the strcat row flatters
 us**: QuickJS 2021-03-27 has no string ropes, so its `s += "ab"` is quadratic.
-Quote the excluding-strcat number. [`QUICKJS_COMPARISON.md`](QUICKJS_COMPARISON.md)
+Quote the excluding-strcat number. [`QUICKJS_COMPARISON.md`](gallery/ranger_engine/QUICKJS_COMPARISON.md)
 has the measurement methodology and a source-level comparison of what the two
 engines do differently.
 
@@ -491,13 +544,13 @@ The compiler supports three JavaScript module output formats:
 
 ```bash
 # Standalone JavaScript (runs main function)
-node bin/output.js -es6 myfile.rgr -o=myfile.js
+node dist/rgrc.js -es6 myfile.rgr -o=myfile.js
 
 # CommonJS module (.cjs)
-node bin/output.js -es6 -nodemodule myfile.rgr -o=myfile.cjs
+node dist/rgrc.js -es6 -nodemodule myfile.rgr -o=myfile.cjs
 
 # ES6/ESM module (.mjs)
-node bin/output.js -es6 -esm myfile.rgr -o=myfile.mjs
+node dist/rgrc.js -es6 -esm myfile.rgr -o=myfile.mjs
 ```
 
 **File Extensions:**
@@ -519,7 +572,7 @@ Use `-sourcemap` with `-es6` or `-typescript` to emit a sibling `.js.map` / `.ts
 
 ```bash
 # Standalone ES module + map
-node bin/output.js -es6 -esm -nodemodule -sourcemap ./myapp/App.rgr -o=app.js
+node dist/rgrc.js -es6 -esm -nodemodule -sourcemap ./myapp/App.rgr -o=app.js
 
 # Result: bin/app.js and bin/app.js.map
 ```
@@ -540,9 +593,9 @@ npx vitest run tests/compiler-sourcemap.test.ts
 
 **Implementation notes** (for compiler hackers)
 
-- `compiler/ng_SourceMap.rgr` — `SourceMapBuilder`, VLQ encoder, `addMappingFromNode()` uses `node.getLine()` + `node.code.getColumn(sp)` (not stale `node.row`).
-- `compiler/ng_writer.rgr` — `lineNumber` / `columnNumber` on emit, `walkNodeStack`, `outMapped()`, `.map` write in `CodeFileSystem.saveTo`.
-- Flag: `compiler/ng_Compiler.rgr` → `flag sourcemap`; enabled in `VirtualCompiler.rgr` via `fileSystem.enableSourceMaps()`.
+- `compiler/SourceMap.rgr` — `SourceMapBuilder`, VLQ encoder, `addMappingFromNode()` uses `node.getLine()` + `node.code.getColumn(sp)` (not stale `node.row`).
+- `compiler/CodeWriter.rgr` — `lineNumber` / `columnNumber` on emit, `walkNodeStack`, `outMapped()`, `.map` write in `CodeFileSystem.saveTo`.
+- Flag: `compiler/Compiler.rgr` → `flag sourcemap`; enabled in `VirtualCompiler.rgr` via `fileSystem.enableSourceMaps()`.
 
 ## Getting started with Hello World
 
@@ -550,14 +603,14 @@ Create file `hello.rgr`
 
 ```
 class Hello {
-    sfn m@(main):void () {
+    sfn main () {
         print "Hello World"
     }
 }
 ```
 
 ```
-ranger-compiler hello.rgr            ; writes bin/output.js
+ranger-compiler hello.rgr            ; writes bin/hello.js
 ranger-compiler hello.rgr -o=hello.js
 ```
 
@@ -786,7 +839,7 @@ comment starts with `;`.
 ```
 ; here is a comment
 class Hello {
-    sfn main@(main):void () {
+    sfn main () {
         def o (new Hello)
         o.SomeNonStaticFn()
     }
@@ -921,7 +974,7 @@ Dart and Python `public` writes the export list itself — a barrel file and
 `__all__` are exactly the kind of list that rots when a person maintains it. A
 class with no doc block is not opted into the API model and compiles exactly as
 it did before. Design and the remaining targets:
-[`PLAN_API_DOCS.md`](PLAN_API_DOCS.md).
+[`PLAN_API_DOCS.md`](docs/plans/PLAN_API_DOCS.md).
 
 ## Types
 
@@ -1147,7 +1200,7 @@ class childClass {
     Extends( fatherClass )
 }
 class mainProgram {
-    sfn m@(main) {
+    sfn main () {
         ; invoke the class
         def cc (new childClass)
         cc.foo("World!")
@@ -1221,6 +1274,45 @@ return one.
     }
 ```
 
+Inside the then block of `if (!null? x)` an optional **object** is narrowed:
+fields and methods are read through it without `unwrap`, also under `-strict`.
+A condition narrows only when it must be true for the block to run — a single
+`!null?` or an `&&` of them, on a name or a path such as `a.friend`:
+
+```
+    fn describe:string (p@(optional):Person) {
+        if (!null? p) {
+            return (p.greet() + " " + p.name)
+        }
+        return "nobody"
+    }
+```
+
+`if p { … }` is the same test. Inside the block `def q:Person p` takes the
+value: the compiler writes one unwrap for it, the same code as
+`def q:Person (unwrap p)`.
+
+The flow narrows as well: the else branch of `if (null? p)`, the code after
+`if (null? p) { return … }` (also `throw`, `break` and `continue`), and the
+code after `p = <a value>`:
+
+```
+    fn describe:string (p@(optional):Person) {
+        if (null? p) {
+            return "nobody"
+        }
+        return p.name
+    }
+```
+
+Not narrowed: an `||` of `!null?` tests, and optional scalars — `(n + 1)` on
+an optional int still needs `(unwrap n)`.
+
+A field declared without a value is optional too. Under `-strict` it counts
+as present when the constructor assigns it at its top level, and a field that
+an attach or init method sets before use is declared `@(late)`
+(`def model@(late):SheetModel`), like Kotlin's `lateinit`.
+
 [Optional values](https://terotests.github.io/Ranger/docs/language/optionals/)
 lists the operators (`??`, `!!`, `unwrap`, `null?`, `!null?`, `wrap`,
 `nullify`), what each target uses for an empty value, and the `-strict` flag.
@@ -1448,7 +1540,7 @@ class Main {
         }))
         print (join n.items " ")
     }
-    sfn hello@(main):void () {
+    sfn main () {
         def hello (new Main ())
         hello.testCollection()
     }
@@ -1574,7 +1666,7 @@ the reserved words and the compilation rules live in `compiler/Lang.rgr`, which
 the compiler reads at compile time. Adding a target to an existing operator, or
 adding a whole operator, takes effect on the next compile with no rebuild step.
 The compiler looks for `Lang.rgr` in the working directory first and falls back
-to the copy beside `bin/output.js`, so a modified copy next to your sources
+to the copy beside `dist/rgrc.js`, so a modified copy next to your sources
 overrides the installed one — which makes an experiment cheap to try and cheap
 to revert. `lib/stdops.rgr` (macros, the `ret` operator) works the same way.
 
@@ -1583,16 +1675,16 @@ are Ranger source under `compiler/`. Changing them means compiling the compiler
 with itself:
 
 ```bash
-npm run compile      # compiler/ng_Compiler.rgr -> bin/output.js, and copies Lang.rgr to bin/
+npm run compile      # compiler/Compiler.rgr -> dist/rgrc.js, and copies Lang.rgr to dist/
 npm test             # the suite runs against the compiler you just built
 ```
 
-`npm run compile` is the self-hosting step: the current `bin/output.js` compiles
-the new sources into the next `bin/output.js`. A change that breaks codegen can
+`npm run compile` is the self-hosting step: the current `dist/rgrc.js` compiles
+the new sources into the next `dist/rgrc.js`. A change that breaks codegen can
 therefore break the compiler that builds the next one, so keep the previous
-`bin/output.js` until the tests pass; `versions/<target>/compiler.js` holds
-earlier builds. The standalone form is `ranger-compiler -compiler -copysrc`,
-which writes `bin/ng_Compiler.js`.
+`dist/rgrc.js` until the tests pass -- `git checkout dist/rgrc.js` restores
+the last committed build, and the git history of that one file is the rollback.
+The published CLI is `dist/rgrc.js`, built by `npm run build:dist`.
 
 # Annotations
 
@@ -1600,7 +1692,10 @@ Compiler is using annotation syntax for specifying some parameters for class, tr
 
 ## sfn someFn@(main)
 
-Static functions can be annotated to be the start point of compiled application using `@(main)` annotation.
+A static function named `main` is the start point of the compiled application:
+`sfn main () { … }`. A static function with another name can be made the start
+point with the `@(main)` annotation, `sfn start@(main):void ()`, which is what
+older code does.
 
 ## trait myTrait @params(...)