ranger-compiler 3.5.1 → 3.5.2

package/CHANGELOG.md

@@ -7,6 +7,1050 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- **Erazer moved to its own repository,
+  [terotests/Erazer](https://github.com/terotests/Erazer).** `gallery/erazer`,
+  its `erazer*` npm scripts, the CI layout-lab step, and the `/evg/erazer/`
+  page and its checks in the Pages deploy are gone from this repository.
+  The compiled `gallery/erazer/bin/*.js` that the removal left tracked are
+  deleted too.
+- **The EVG live-build harness moved to its own repository,
+  [terotests/EvgHarness](https://github.com/terotests/EvgHarness).**
+  `gallery/evg/livebuild` and its `livebuild*` npm scripts are gone. The
+  harness clones Ranger and Erazer (or uses `RANGER_DIR` / `ERAZER_DIR`) and
+  links itself back in at `gallery/evg/livebuild`; both link paths are
+  ignored here.
+
+### Fixed
+
+- **`npm run test:publish` depended on the machine it ran on.** The
+  interpreter's local time is UTC, and `runtime-conformance` compared it with
+  Node formatting in the host's zone, so the `Intl` date probes failed
+  anywhere but UTC. `tests/vitest.config.ts` sets `TZ=UTC` for every fork.
+  `docs-usage` counted every `.rgr` file on disk, so test output, self-host
+  copies of `lib/` and files a moved-out project left behind could mark a
+  legacy library as used; it now reads `git ls-files`.
+- **`npm run build:dist:module` failed with 140 TypeScript errors.** The
+  TypeScript writer typed `buffer` as `Uint8Array`, but the es6 buffer
+  templates make an `ArrayBuffer` with a `DataView` in `_view`. `buffer` is
+  now `(ArrayBuffer & { _view: DataView })` on TypeScript, and the
+  templates attach `_view` with `Object.assign`, which gives that type.
+  The generated JavaScript behaves as before.
+- **`npm run test:publish` passes again.** `tests/http-server.test.ts` and
+  its fixture are removed: they ran the es6 HTTP server that the plugin
+  removal took out (`start` / `stop` and `RangerJavaScriptHttpServerWriter`).
+  The C++ ownership test accepts `h->item.value()` for an optional field,
+  and the Dart self-host test checks for `List<dynamic>` in place of
+  `jsonEncode`, which the compiler no longer calls.
+- **A document's `theme` now turns on its `.theme-<name> .class` rules.**
+  `EVGLayout` applied a document's stylesheet with an empty theme, so every
+  theme-scoped rule was dead in the live page, `measure` and every other
+  layout path: `{"theme":"dark"}` on the root parsed, round-tripped, and
+  styled nothing. The UI kit's `.theme-dark` rules for every piece now
+  apply. `evg:json:test` covers it.
+- **UI kit `bars`: the bars sit in their row.** `.ui-bar-col` had
+  `justify-content: flex-end`, and a content-sized column with that laid its
+  bar and label out one column-height above itself, over the card's title.
+  `measure` did not report it, because nothing clips there.
+
+### Added
+
+- **Dashboard pieces in the UI kit.** `ui_kit.mjs add` builds `tabbar`,
+  `pills`, `tiles`, `bars` and `banner` as whole pieces with their rules in
+  `gallery/ui/theme/base.css`, beside `row`, `card`, `appbar`, `chips` and
+  `field`.
+
+- **Native generic classes on Rust.** A generic class whose body only stores,
+  moves and returns its parameter values is written as `struct History<Op>`
+  with `impl<Op: Clone> History<Op>`, and used as `History<i64>` /
+  `History::<i64>::new()`. A parameter typed by the type parameter is taken by
+  value (`op: Op`) and the call sites pass owned values. A class that extends,
+  is extended or `does` a trait, a method that needs its own handle, and a
+  template named like a Rust prelude type (`Box`, `Vec`, …) keep the copies.
+
+- **Native generic classes.** A `class History @params(Op)` whose body only
+  stores, moves and returns its parameter values is written once, as a
+  generic class of the target: `template <class Op> class History` on C++,
+  `class History<Op>` on Java, C#, Kotlin, Dart and TypeScript,
+  `class History[Op]` on Scala, `type History[Op any] struct` on Go,
+  `class History(Generic[Op])` on Python, and one `History` class on
+  JavaScript and PHP. Uses are spelled `History<int>`, `*History[int64]` and
+  so on. The type checker still checks one class per argument list. A body
+  that needs to know its parameter, and every generic class on Rust, Swift
+  and LLVM, keeps the copies (`History_int`). `-generics-report` prints the
+  choice, `-no-native-generics` turns it off.
+
+- **`char_length`: how many characters, on all fourteen targets.** `strlen`
+  counts the target's own unit — UTF-16 code units on JavaScript, Java,
+  Kotlin, C#, Scala and Swift, UTF-8 bytes on Rust, Go, C++ and PHP, code
+  points on Python. That is the right number for a scan and the wrong one for
+  anything a person sees: a column, a width, a padding count. `char_length`
+  is the count that does not move: `len(s)` on Python, `chars().count()` on
+  Rust, `utf8.RuneCountInString` on Go, `codePointCount` on the JVM,
+  `runes.length` on Dart, `mb_strlen` on PHP, `unicodeScalars.count` on
+  Swift, and a non-continuation-byte or non-low-surrogate count where the
+  standard library has nothing. It is the length of `(to_chars s)` without
+  building the array, and for ASCII it is `strlen`.
+
+- **EVG live build exports one Ranger UI JSON document.** Save keeps a
+  design on this machine. **Export** copies a single `.ranger.json`
+  (`format: ranger-ui`, version 2): a semantic `ui` tree, a CSS string,
+  the machine, and a `components` manifest. Known controls collapse to
+  `rave.Switch` / `SettingsRow` rather than a track and a thumb.
+  Compact is the clipboard; Full adds `compiled.evg` and layout debug.
+  `npm run livebuild:export`.
+
+### Changed
+
+- **The Rust header is built from what the file contains.** Every output used
+  to open with the same block — `#![allow(unused_parens)]`,
+  `unused_mut`, `unused_variables`, `unused_assignments`, `dead_code` and
+  three clippy lines — whether or not the file held the shape. An allow
+  nobody needs hides the backend's own regressions: a stray `mut` or a
+  redundant paren the generator starts emitting is swallowed by the pragma
+  instead of being reported. Each line is asked for now: `unused_mut` by the
+  one `let mut` the writer could not prove, the rest by predicates over the
+  program (a parameter the body never reads, a dead store, a name whose
+  snake_case spelling is already another name here, an `if` inside an `if`,
+  seven parameters, a borrowed `Vec`). Across the twelve `friendly` studies
+  the header matches what each file needs exactly, and no study asks for a
+  line it does not need. Only `dead_code` is unconditional — a
+  program's public surface is dead code in a single-file rendering of it,
+  which says nothing about the generator. The predicates skip what the
+  class-writing loop skips: `Vector.set` has an unused parameter and is never
+  emitted, and it alone was asking every file for `unused_variables`.
+
+- **`unused_parens` is not asked for either, because the parentheses are
+  gone.** A `let` value, an assignment's right side and a template's argument
+  slot all delimit the expression, so the pair an operator template puts
+  around its whole result comes off there: `let n: i64 = (xs.len() as i64);`
+  and `rg_substring(&s, i, (i + 1))` were the two shapes, 996 rustc warnings
+  between them. An operand with an operator on either side keeps its pair —
+  that is what makes the precedence right. The template-slot rule is
+  target-neutral, so `g.check(0 - 1)` is what every target emits now.
+
+- **`mut` is asked of the body rather than of the type.** An object local
+  used to be `mut` whatever was done with it, and so did a collection, a
+  buffer and every parameter binding. An object local now takes `mut` only
+  when the body assigns it, writes through it, calls a method emitted
+  `&mut self` on it, or hands it where the callee takes `&mut`; a parameter
+  takes it only when the body reassigns the parameter itself. Collections and
+  `&mut` parameters keep the blanket `mut` and ask for the allow — dropping
+  it on those was measured at 43 and 11 rustc errors, every one an E0596
+  where a call site writes `&mut name` and the callee is invisible from
+  there.
+
+- **Three Rust shapes from the same reading.** A folded object literal binds
+  `let line: CartLine = …` rather than `let mut`, unless the body writes
+  through the name after the fold — and the local is renamed where it
+  collided (`g` → `g_1`), so the scan matches the source name and the
+  compiled one. A `for` body that only calls `&self` methods on the element
+  binds `&T`: `for line in &self.lines`, not `.iter().cloned()`; the answer
+  is `rust_mut_self`, which is settled for every class before the first line
+  is written. And a constructor names `Self { … }` and gives an empty owned
+  String `String::new()`.
+
+  Measured on the Rust rendering of this compiler: **2 148 warnings → 321**,
+  with 0 rustc errors, and the rendering still compiles the compiler to
+  output byte-identical to `dist/rgrc.js`. What is left was never covered by
+  any of these allows. A shopping-cart program of the kind the playground
+  compiles now carries `#![allow(dead_code)]` alone and draws no rustc
+  warning at all; `tests/codegen-rust.test.ts` keeps it that way.
+
+- **The front-page hero copy is the shorter two columns.** Silver Bullet:
+  Ranger is a little heavier to get started with, and a golden test when
+  you have more than one language to target. Stay DRY: AI makes generating
+  code easier; consistent validation across platforms is the remaining
+  problem.
+
+- **Front-page bench re-run: Go is 236 ms, third after C++ and Rust.**
+  Re-running after the string-index fix (C++ 136, Rust 170, Go 236, Java
+  351, JavaScript 508, Python 971). PHP, C# and Kotlin were not on this
+  machine this run. The Platforms and Gallery sections come off the front
+  page: they are AGPL gallery work, and the Platforms copy was too specific
+  for the language page.
+
+- **`-strict-strings` asks whether the unit is observable, and the compiler
+  now reports zero.** The first version listed every index whose subject was
+  not an ASCII literal — 322 sites, which named the language rather than the
+  defect. A scan is not a defect: `while (i < (strlen s)) { charAt s i }`
+  reads the same characters on a byte target and a UTF-16 one; only the
+  numbers differ, and the program never sees them.
+
+  The flag now reports the three ways a number escapes — a `strlen` that
+  indexes nothing, a `to_chars` offset handed to `charAt`, a `charcode` on
+  something that is not an ASCII literal — and proves the rest quiet: an
+  emptiness test, a length that indexes some string, a length that bounds an
+  index, two counts of the same string compared with each other. A length
+  against a constant or against another string's length is a **note**, not a
+  finding. `strlen` is covered, which it was not before, and that is where
+  the real defects were.
+
+  Four of them, all a count of characters someone sees: the CLI progress bar
+  padded to a different column depending on which build of the compiler wrote
+  it; `formatSource` wrapped the same file in different places, because a
+  comment holding an em dash was one column wide under Node and three in the
+  Rust and Go self-hosts; `columnNumber`, which goes into errors and into the
+  source map; and `(cc N)`, which burns a character code into generated
+  source and so must not depend on its host. Three escapers now `switch` on
+  the one-character slice instead of on `charcode` of it.
+
+  Where provenance crosses a function boundary — a scan position kept in a
+  field, a length arriving as a parameter — the source says so with
+  `@(units)` on the `def` or on the function, so the claim is visible where
+  it is made. `tests/strict-strings.test.ts` keeps the count at zero.
+
+### Fixed
+
+- **A string literal holding BOTH an escape and a non-ASCII character came
+  out broken.** `"merkintä... esim. \"treeni\""` compiled to
+  `merkint\uFFFD\uFFFD...`: two replacement characters where the `ä` was.
+  The parser's escape-decoding path converted the literal to a `charbuffer`
+  and copied it back one unit at a time, and since a `charbuffer` is UTF-8
+  bytes on every target now, each byte of a multi-byte character was decoded
+  by itself. It reads the string directly — `strlen`, `charAt` and
+  `substring` index the same unit as each other on any one target, and every
+  character the loop looks at (`\`, `"`, `n`, …) is ASCII. The same shape as
+  the `EncodeString` fix in the six writers, in the one place that was
+  missed; the checked-in `dist/rgrc.js` carried the damage in one of its own
+  messages and needed two bootstrap passes to converge.
+
+- **A Rust `switch` over strings broke on a quote, a backslash or a
+  newline.** A `match` arm is a pattern, so the Rust writer wrote the case
+  literal with `(str N)` — the text and nothing else, because the
+  `.to_string()` a literal gets in expression position is not something a
+  pattern takes. Unescaped, `case "\""` came out as `"""` and rustc read
+  three tokens where one was meant; `case "\n"` put a real newline inside
+  the pattern. `(estr N)` is the same accessor with the target's own string
+  escaping applied and still no quotes of its own, and the Rust `case`
+  template uses it. Found by moving three escapers onto a string `switch`.
+
+- **The Rust rendering of the compiler compiles the compiler.** It had type-
+  checked with zero rustc errors for years and aborted on the first file it
+  was ever given, because `RefCell` checks at run time and the self-host gate
+  only type-checked. Two causes, both the same shape — a borrow that outlives
+  the statement that took it:
+
+  A `for` head is the one place Rust keeps a temporary alive across a block,
+  so a collection reached through a field kept that object borrowed while the
+  body ran and the first `borrow_mut` panicked. And a trait method with a
+  `&mut self` receiver means the call site holds a `RefMut` for the whole
+  call — while the compiler and its writers are mutually recursive by design.
+
+  A trait family that can be re-entered through its own handle is now
+  implemented for `Rc<RefCell<C>>` rather than for `C`, so `&self` IS the
+  handle and dispatching borrows nothing. Which families those are is
+  answered from the field graph rather than declared: the trait root holds a
+  field of some class X, X holds a field of the family's type, and both call
+  through it.
+
+  `npm run selfhost:run:rust` is the new gate and holds Rust to what C++ and
+  Go already meet: build it, make it compile `compiler/Compiler.rgr`, and
+  diff the result against `dist/rgrc.js`. It is identical, all 5 596 785
+  bytes, in 7.3 s against the node host's 7.8 s.
+  `docs/plans/PLAN_RUST_REENTRANCY.md` is the write-up.
+
+- **Rust and Go index the byte their string is made of.** `strlen`, `charAt`
+  and `substring` on both counted characters, which cost them the quadratic
+  scan — `charAt` walked from the start on every read, and on Go `[]rune(s)`
+  copied the whole string each time. `gallery/friendly/bench/strscan.rgr` at
+  120 000 characters: Rust 8 830 ms → 11 ms, which is C++ to the millisecond;
+  Go did not finish inside two minutes → 19 ms.
+
+  It was also a correctness fix. `indexOf` is `strings.Index` on Go and
+  answers a BYTE offset, so a scanner that found a delimiter and sliced at it
+  sliced in the wrong place as soon as anything non-ASCII stood before it:
+  for `"ä,b"` the head came back as `"ä,"` and the tail as `""` — the rest of
+  the text, dropped without a word. Rust had the same bug and paid an O(n)
+  `chars().count()` on every `indexOf` to hide it; that conversion is gone.
+  Rust's `charcode` read `as_bytes()[0]` all along and so disagreed with its
+  own `charAt`; Java's read `getBytes()[0]` and answered −61 where `charAt`
+  said 228. All nine runnable targets are now internally consistent.
+
+- **A byte-hosted compiler wrote every non-ASCII literal twice encoded.**
+  The C++ self-host emitted `"a—b"` into its JavaScript output as
+  `C3 A2 C2 80 C2 94` instead of `E2 80 94`: `EncodeString` rebuilt each
+  character with `strfromcode`, which writes a code point, from what `charAt`
+  gave it, which on a byte host is a byte. True of C++ and PHP all along and
+  never noticed. A one-unit `substring` copies the unit across instead, and
+  the C++ and Go self-hosts now produce output byte-identical to the
+  node-hosted compiler's.
+
+- **`to_chars` is the portable indexable view of text.** `def cs:[int]
+  (to_chars s)` gives Unicode code points, the same sequence on every target,
+  built once in O(n) and read in O(1). `charAt` on a `string` stays the
+  target's own unit — that is what makes it O(1) there — and is right for a
+  scanner over ASCII structure; `to_chars` is for text a human wrote, where
+  `"a😀b"` has to be three characters and not two UTF-16 units plus two.
+  Because the program names the conversion, the allocation is asked for
+  rather than hidden behind an index.
+
+- **A `charbuffer` is a buffer of bytes, and `to_charbuffer` is a string's
+  UTF-8.** One element is one octet, 0..255, not a character; UTF-8 belongs
+  to `to_charbuffer` and `to_string`, the two operators that cross between
+  text and bytes, because a conversion cannot be made without naming an
+  encoding. The buffer itself is just bytes — one holding a JPEG is not
+  "UTF-8 bytes".
+
+  It used to be whatever the host's string happened to be made of: UTF-16
+  units on JavaScript, Kotlin and Dart, code points on Python, bytes on the
+  other eight, and on Scala a `toByte` cast that truncated anything above
+  U+00FF. `to_charbuffer` is the explicit conversion — the program asks for
+  the byte view by name — so it is the one place a single portable unit can
+  be promised, and now it is: `"a—b"` is five bytes on all of them.
+
+  Measuring it with `tests/fixtures/charbuffer_units.rgr` turned up three
+  holes as well: `to_string` on a charbuffer did not compile on Rust, Java or
+  Kotlin, `charAt` on one returned a *signed* byte on the JVM targets, and
+  Swift 6 had no `to_charbuffer` template at all. Java's conversion used the
+  platform default charset rather than UTF-8.
+
+  A `charbuffer` is `Uint8Array` on JavaScript and TypeScript, `bytes` on
+  Python and `ByteArray` on Kotlin. `RangerLispParser` holds its source in
+  one, so the JavaScript self-host now scans the same bytes the C++ one does,
+  at the same speed. `tests/charbuffer-units.test.ts` asserts the agreement;
+  `docs/plans/PLAN_STRING_INDEXING.md` is the plan this is stage 1 of.
+
+- **What a `string` index means is now measured and written down.**
+  `strlen`, `charAt` and `substring` mean a UTF-16 code unit on six targets, a
+  Unicode code point on three and a UTF-8 byte on two, and nothing said so.
+  `tests/fixtures/string_units.rgr` and `tests/string-units.test.ts` pin each
+  target's answer, `gallery/friendly/bench/strscan.rgr` measures the other
+  half — the ordinary index scan is O(n²) on Rust and Go — and `ai/QUICKREF.md`
+  says both where `string` is documented. No behaviour changed; the defect is
+  visible now.
+
+- **Generated-code quality is three questions now, not one ranking.** The
+  single ordering read as a verdict, and it was one reading of the generated
+  files. It is split into correctness, speed and idiom, because a target can
+  do well on one and badly on another.
+
+  *Correctness* is what `gallery/friendly/compile.sh` already measured: eight
+  targets agree on all twelve studies. The one place they do not is integer
+  width — `100000 * 100000` answers `10000000000` on JavaScript, Python, PHP,
+  Go and Rust and `1410065408` on C++, C#, Java and Kotlin, and on C++ the
+  overflow is undefined behaviour rather than a wrap.
+  `gallery/friendly/bench/intwidth.rgr` is the probe.
+
+  *Speed* is new: `gallery/friendly/bench/` is the same Ranger program, five
+  kernels, each timing itself with `wall_clock_ms`. Kernels only: C++ 260 ms,
+  Kotlin 466, C# 663, Java 760, PHP 801, JavaScript 1076, Rust 2556,
+  Python 2566, Go 143882. (Re-measured after the string-indexing work: C++
+  265, Rust 397, Kotlin 485, C# 684, Go 694, Java 753, PHP 786,
+  JavaScript 1040, Python 2607.) Two of those are the compiler's doing and are
+  written down — `charAt` is O(n) on Go and Rust, and a Ranger map is a plain
+  object on JavaScript.
+
+  *Idiom* is the score that stays on the front page, and it is measured
+  against a published twelve-check table in `gallery/friendly/README.md` so
+  each cell can be disputed against the file it came from. On this compiler,
+  after native enums on twelve targets, Python annotations, PHP typed
+  properties and the ownership work: Swift 92, Kotlin 88, TypeScript 83,
+  Dart 83, C++ 83, C# 79, Scala 79, Python 75, Rust 75, JavaScript 71,
+  PHP 71, Java 67, Go 67. This supersedes the #1024 rescoring below. Swift is
+  top and has never been compiled on the build machine, which is exactly why
+  the three axes are kept apart.
+
+- **`wall_clock_ms` works on PHP, Dart, Scala and Swift.** They fell through
+  to the `*` template, which is `0.0`, so every duration a program measured
+  on those targets was zero.
+
+- **The front-page hero columns are gold, not a magic runtime.** The first
+  column is still “There is no Silver Bullet.” Ranger is more like gold:
+  heavier to start with, and a golden-file test when you target more than
+  one language. The second column is “Stay Dry. Stay Foolish.” — sharing
+  code across platforms is half the problem; AI does not provide the
+  consistent validation, and Ranger does.
+
+- **C++: a `record` nothing aliases is a value, not a `shared_ptr`.**
+  `StaticAnalyzer.analyzeClassSharing` already walks the whole program and
+  decides which classes are aliased and held; the pass already ran for C++
+  compilations; only the Rust writer read the answer. So the same study came
+  out as `struct Point` + `fn manhattan(p: &Point)` on Rust and
+  `class Point` + `int manhattan(const std::shared_ptr<Point>&)` on C++.
+  A record that verdict clears is now a value everywhere it appears — the
+  parameter is `const Point&`, `new Point(3 4)` is `Point(3, 4)` on the stack,
+  and the copying builder in study 08 returns a `Request`. The C++-specific
+  disqualifiers live beside it in
+  [`compiler/CppValueAnalysis.rgr`](compiler/CppValueAnalysis.rgr): an
+  `@(optional)` of the record (an optional object *is* the null pointer on this
+  target), a `cast` to it, a method that hands out bare `this`
+  (`shared_from_this()` needs the pointer), a field of its own type,
+  inheritance in either direction, and membership of a closed family, which
+  keeps the family's own rule. `-strict-ownership` prints
+  `ownership[cpp] class Point -> value` or the reason it did not;
+  `-cpp-shared-classes` restores the old lowering. Classes with behaviour are
+  the same question and wait for `const` member functions: a `const User&`
+  cannot call `who.label()` until the writer emits one.
+
+  Two things the value form needed that the pointer form never did. A
+  parameter the body WRITES THROUGH is `Point&`, not `const Point&`: behind a
+  `shared_ptr` the `const` was on the pointer and `p->x = 1` compiled, and on
+  a value it is on the object. `StaticAnalyzer.markVarAsMutated` has been
+  recording that fact as `needs_cpp_reference` all along; the writer suppressed
+  the `&` for class types because a `shared_ptr` never needed one. And a `T&`
+  does not bind a temporary, so `m.bump((new Point(1 2)))` goes through
+  `rg_arg_ref`, which is what that helper already existed for.
+
+- **Every target's `for` is now that target's own loop.** The question is one
+  question -- can this loop be written over the collection instead of over an
+  index? -- so it is answered once, in
+  [`compiler/ForLoopAnalysis.rgr`](compiler/ForLoopAnalysis.rgr), and each
+  writer spells the answer its own way:
+
+  | target | was | is |
+  | --- | --- | --- |
+  | JavaScript / TypeScript | `for ( let i = 0; i < xs.length; i++)` | `for ( const v of xs)` |
+  | Python | `for i, v in enumerate(xs):` | `for v in xs:` |
+  | Go | `var i int64 = 0; for ; i < int64(len(xs)) ; i++` | `for _, v := range xs {` |
+  | Java | `for ( int i = 0; i < xs.size(); i++)` | `for ( Integer v : xs)` |
+  | Kotlin | `for ( i in xs.indices )` | `for ( v in xs )` |
+  | C# | `for ( int i = 0; i < xs.Count; i++)` | `foreach ( int v in xs)` |
+  | Dart | `for ( int i = 0; i < xs.length; i++)` | `for ( final v in xs)` |
+  | Swift | `for (_, v) in xs.enumerated()` | `for v in xs` |
+  | C++ | `for ( int i = 0; i != (int)(xs.size()); i++)` | `for ( int v : xs )` |
+
+  Two conditions, and both are safety rather than length: the body must not
+  read the index, and must not touch any NAME the collection expression rests
+  on. A foreach form takes one iterator, enumerator or borrow for the whole
+  loop, so a body that appends walks something the index form does not -- an
+  invalidated iterator on C++, a `ConcurrentModificationException` on Java and
+  Kotlin, an `InvalidOperationException` on C#, a different answer on Go and
+  Swift. Every target keeps the index loop there, and `tests/loops-native.test.ts`
+  asserts both halves on all ten. Rust already made this decision
+  (PLAN_RUST_SEMANTIC_IDIOMS K) and es5 is deliberately left out, because
+  `for...of` is ES6.
+
+- **C++: `for ( int v : xs )`.** The generated `for` was always
+  `for ( int i = 0; i != (int)(xs.size()); i++) { int v = xs.at(i); … }`. When
+  the body neither reads the index nor touches any name the collection rests
+  on, it is a range-`for` now — a scalar element by value, everything else
+  `const T&`. Both conditions are what makes it safe rather than merely
+  shorter: a range-`for` holds one iterator pair for the whole loop, so a body
+  that pushes would walk invalidated iterators where the index form re-reads
+  `.size()` every turn. Same decision the Rust writer makes
+  (PLAN_RUST_SEMANTIC_IDIOMS K), and deliberately not an
+  `<algorithm>` / `<ranges>` lowering.
+
+- **C++ and Rust: the preamble goes in only when the program reaches it.**
+  The ordered-map preamble was gated already; these were not. On C++,
+  `template <class T> class r_optional_union` went into every file that had a
+  union — and `Any`, the compiler's own union of every declared class, is one
+  the parser declares for every program, so the answer was always yes. `Any`
+  and its forward declarations now go in only when the program says `Any`,
+  `r_optional_union` only when some `@(optional)` names a closed family, and
+  `rg_arg_ref` only when a call site needs it. The twelve gallery studies lost
+  291 lines; study 07 is 67 lines, from 88. On Rust, `use std::rc::Rc`,
+  `use std::cell::RefCell` and the `RgAnyRef` / `rg_downcast` / `RgIdentical`
+  trio go in only when the cell can reach the output — a shared class, a
+  `@(weak)` field, a closed family, a behaviour-only trait used as a type, or
+  an inheritance family. Six of the twelve Rust studies have none of those and
+  drop all thirteen lines.
+
+  Gate for all three: `bash gallery/friendly/compile.sh` (twelve studies on
+  every target with a toolchain, every `attempts/` file still refused, six
+  targets agreeing on all twelve outputs), the C++ selfhost build, and
+  `scripts/rust-selfhost-check.sh`. The plan is
+  [`docs/plans/PLAN_CPP_IDIOMS.md`](docs/plans/PLAN_CPP_IDIOMS.md).
+
+### Added
+
+- **A smoke effect**, `evg-surface-effect: smoke`, and three presets for it.
+  What makes smoke read as smoke is that it curls, and curls at every size at
+  once, so the field is DOMAIN WARPED — fbm evaluated at a point two other fbms
+  have already moved. One warp gives the billows, the second the tendrils that
+  come off their edges. The bar the field has to clear rises with height, which
+  is what leaves a full floor, wisps above it and black over those rather than
+  a fog that fades out evenly; `evg-fx-height` moves that line, and at 3 or
+  more the same effect is a cloud filling the box. It is lit by comparing the
+  field with itself one step toward `evg-fx-angle` — a gradient, and what gives
+  a cloud its volume. `.fx-stage`, `.fx-cloud` and `.fx-haze` are in
+  `effect-presets.css`, so they are in the gallery demo's background picker and
+  on its contact sheet; the pixel gate holds the effect to banking up along its
+  own floor, thinning toward the top, filling the box when told to, and moving.
+
+- **A background picker on the published effects demo**
+  ([`/ui/demo/?demo=effects`](https://terotests.github.io/Ranger/ui/demo/?demo=effects)).
+  The eleven blocks of `lib/evg/gl/effect-presets.css` are in the rail, and
+  picking one TYPES it into the live stylesheet under the canvas — the box's
+  own declarations kept, the effect's replaced — after which the cascade reads
+  it like any other edit. So the picker has no privileged path into the
+  painter, and what it wrote is left in the editor to be read and changed.
+  Which element a preset lands on is decided by the plugin's LAYER, asked of
+  the painter rather than listed in the page: a source effect becomes the sky's
+  own background, a backdrop effect goes on the pane over it, because it draws
+  what is BEHIND an element and the opaque sky would paint over it a moment
+  later — so rain arrives as rain on the glass, with the stars bending through
+  it. The preset file reaches the bundle as the FILE, so a preset edited there
+  is the one the picker offers, the contact sheet paints and the pixel gate
+  checks; `page-check` reads it too and holds the round trip to it — every
+  preset offered, the file's own numbers in the display list, and the
+  stylesheet in the page saying what is on screen.
+
+- **Three quieter surface effects, and a file of presets.** `plasma-wave`
+  (ribbons of light over a noise field), `raindrop` (drops on the pane, each a
+  sphere's lens over what is behind it — strongest at the rim, nothing in the
+  middle, so the page stays legible through the centre) and `ambient-light` (a
+  slow desaturated wash with bokeh discs in it). All three are plugins in the
+  same registry the starfield and the glass use: a name, a parameter list and
+  one GLSL function, with the box coming from the layout. Two of them are
+  BACKDROP effects, which is what makes a drop a lens rather than a sticker.
+  `lib/evg/gl/effect-presets.css` holds eleven ready blocks — five skies, two
+  plasma fields, two rains, two washes — paste-able into the editor under the
+  gallery's effects demo. `npm run evg:fx:shots` paints all of them into one
+  sheet, and `evg:fx:check` reads the same file through the engine's own
+  cascade and then against pixels, so a preset the cascade refuses fails a
+  check instead of quietly drawing the plugin's defaults.
+
+- **The effects demo's stylesheet is editable in the page.** A textarea under
+  the canvas on `?demo=effects`, holding `effects.css`, applied as you type —
+  and what is typed goes through the WHOLE engine: `EffectsDemo.init` hands the
+  text to `EVGStyleSheet`, the cascade applies it, the layout lays the tree out
+  again, the display list carries whatever effect instances the sheet declared,
+  and the painter looks their names up. Nothing patches a parameter behind the
+  scenes, so `evg-fx-density: 6` on `.fx-sky` reaches the shader the same way
+  it does on a page nobody is editing. What the cascade refuses is reported in
+  the cascade's own words — type `#fx-sky` and it says the selector is
+  unsupported, because `EVGStyleSheet` keeps every declaration it rejected.
+  It is on this page and not on the standalone `lib/evg/gl/fx-demo.html`
+  because the bundle here carries the compiled engine and that page carries
+  only a display list built for it.
+
+- **A switch per effect in the gallery rail**, beside the demo it belongs to.
+  The list is built from the DISPLAY LIST rather than from names written into
+  the page: it knows that the stylesheet declared four effects and what each is
+  called, and nothing more. Turning one off sets the flag the painter reads —
+  the pass is skipped, the shader never runs, a press on a sleeping card goes
+  nowhere, and nothing is rebuilt to stop drawing one shader. The ordinary CSS
+  stays: switch the glass off and the card is still a rounded, tinted,
+  `backdrop-filter`-blurred box, which is the clearest way to see where the
+  effect ends and the stylesheet begins. `page-check` drives the switch in a
+  real page and holds the painter to it — one pass fewer with the sky off, and
+  back again.
+
+- **The surface effects are on the published gallery page** —
+  [`/ui/demo/?demo=effects`](https://terotests.github.io/Ranger/ui/demo/?demo=effects).
+  Every other demo there is a control measured against the component it copies;
+  this one is a MATERIAL, and what it shows is that the effects are declared in
+  `gallery/ui/demo/effects.css` and nowhere else. `EffectsDemo.rgr` holds no
+  shader, no clock, no parameter and no coordinate: it builds a tree, the sheet
+  says which box has which effect, the layout says where the box is, and the
+  painter looks the name up in its registry. The page's own share is four lines
+  — a press, a drag, a release and "is anything still moving" — handed to the
+  driver in `lib/evg/gl/evg-fx.js`, which now runs for any demo whose list
+  carries effects.
+
+- **Liquid glass takes a sweep of light.** A bar crossing the pane at its own
+  angle, flaring where it meets the rim, either parked or travelling:
+  `evg-fx-sweep`, `-sweep-angle`, `-sweep-width`, `-sweep-speed`, `-sweep-at`,
+  `-sweep-edge`, `-sweep-rim` and `-sweep-duty`. The last two are what make it
+  a shine rather than a stripe: `sweep-rim` weights the bar toward the bevel,
+  where real glass catches a moving light, and `sweep-duty` gives the pass a
+  fraction of each cycle and parks it off the pane for the rest — so the pane
+  is clean glass most of the time and the glint is an event. Both are checked
+  against pixels: the flat middle comes back unchanged under a rim-weighted
+  bar, and between passes nothing on the pane is brighter than a pane with no
+  sweep at all. It is off by default, because a pane in a room with nothing
+  moving has no streak on it, and a moving one asks for frames with the same
+  `evg-effect-on: always` a starfield uses. The dashed names are the point:
+  `evg-fx-sweep-speed` reaches the shader as `p_sweep_speed` and nothing in
+  between had to learn either spelling.
+
+- **A surface effect can be switched off, and the demo page has a switch for
+  each one.** `inst.off` on an instance: the painter skips the run, the filter
+  is not live, nothing is compiled or copied, and the driver stops handing it
+  events or counting it busy — so a press on a sleeping pool falls through to
+  what is under it. The frame is not rebuilt, which is the point: stopping one
+  shader must not mean re-uploading every buffer on the page. It is the hook a
+  page's own switch hangs on, and the one `prefers-reduced-motion` would;
+  `fx-demo.html` builds a switch per effect out of the display list and
+  remembers the choice per browser.
+
+- **Liquid glass, as CSS.** A third plugin layer and the effect that needed it.
+  `backdrop` runs a plugin IN PAINT ORDER over what is behind the element — the
+  surface so far is copied where the element paints, the plugin writes it back
+  inside the box, and the element's own background, border and children are
+  drawn on top, sharp. That is what `backdrop-filter: blur()` has always done
+  for one hard-wired filter, now open to any plugin, and it is what a pane of
+  glass needs: one that ran as a post-pass would smear its own label.
+  `liquid-glass` is refraction rather than fog — the page behind dragged toward
+  the rim, compressed into a band a few pixels wide, split slightly into colour,
+  with a specular arc inset from the very edge so it reads as a bevel and not as
+  a border somebody drew. It knows no geometry of its own: the bend follows
+  `fxBoxDistance`, the rounded-box signed distance the preamble now hands every
+  plugin, so a pane is a lens at whatever size the layout gave it and whatever
+  `border-radius` the sheet asked for. Frosting, tint and shape stay ordinary
+  CSS beside it (`backdrop-filter`, `background-color`, `border-radius`), and
+  only the lens is the effect. Checked against stripes, where a displacement is
+  visible: the rim bends, the flat middle stands still, the page around it is
+  untouched and what is drawn over the pane stays exactly its own colour —
+  `npm run evg:fx:check`.
+
+- **A surface effect belongs to an ELEMENT now, and is declared in CSS.**
+  `evg-surface-effect: ripple` was one effect over the whole page, with its
+  parameters as fields on `EVGElement` and its drops pushed in by the
+  application from its own `pointerdown` — every press, anywhere, rippled
+  everything, and a second effect could not exist because its parameters would
+  have had to be fields on every element in every document. Three properties
+  replace all of that: `evg-surface-effect` names what runs, `evg-effect-on`
+  (`press drag hover always`) says what starts it, and `evg-fx-<name>: <number>`
+  carries parameters the engine never reads. WHERE is the element's own border
+  box, because the layout already knows it — so an effect reflows with the box
+  it belongs to and no application holds a coordinate, a clock or a drop.
+  `EVGDisplayList` writes one instance per element under the element's `id`, and
+  the rectangle where that element paints carries `efx` so the effect has a
+  place in paint order. The original whole-surface `list.effect` is untouched
+  and still runs. `npm run evg:fx:test`.
+
+- **Renderer plugins, and a starfield to prove it takes one.** The WebGL
+  painter now looks an effect's name up in a registry rather than branching on
+  it: `registerSurfaceEffect({ name, layer, params, frag })`, where `layer` is
+  `source` (drawn in paint order at the element's background, so the element's
+  content is painted over it) or `filter` (run over the finished surface,
+  clipped to the box, which is how the ripple bends text it knows nothing
+  about). A plugin writes one function, `vec4 fxColor(vec2 p, vec2 local)`, and
+  is handed the box, the radius, the clock and the pointer events; the rounded
+  box mask is applied in the shared `main`, so a plugin cannot paint outside
+  the element that declared it. The ripple became one of these without being
+  rewritten — `RIPPLE_CORE` is one string with two entry points. `starfield` is
+  the second: parallax star layers and two-hue nebula from hashes alone, no
+  state, no uploads, nothing in the display list but a name and nine numbers.
+  `lib/evg/gl/evg-fx.js` is the driver that turns a pointer into the events
+  they read, hit-testing the boxes the list carries. Checked in a real GL
+  context — scoped to its box, under the content, moving with the clock, and
+  leaking nothing outside — by `npm run evg:fx:check`; `npm run evg:fx:demo`
+  serves a page whose every effect comes out of a stylesheet.
+  [`lib/evg/PLAN_EFFECTS.md`](lib/evg/PLAN_EFFECTS.md).
+
+- **The UI gallery is a github.io path.** `gallery/ui` already had the
+  tree-literal demos and the Radix-vs-Ranger playground; neither was in
+  the Pages artifact, so
+  [https://terotests.github.io/Ranger/ui/](https://terotests.github.io/Ranger/ui/)
+  404'd. `deploy-pages.yml` now builds both (`/ui/demo/` and `/ui/web/`)
+  and `/ui/` redirects to the demos while keeping `?demo=`.
+
+- **Two worked examples, as fixtures.** `lib/evg/agent/fixtures/popover.*` is a
+  menu bar whose open menu is anchored by name and becomes a bottom sheet
+  below 600px; `connector.*` is two cards with an arrow between them and a
+  count badge on a corner, in a grid that goes to one column under a media
+  query — the arrow follows without being mentioned. Both are a `.evg.json`
+  and a `.css`, rendered at two widths with
+  `npm run agent:render -- <doc> out.png -w <w> -h <h> -css <sheet>`.
+
+- **Popovers: a surface knows where it fits, and what to be when it does
+  not.** EVG already drew overlay surfaces in a real top layer — after the
+  whole normal tree, outside every clip — and flipped them at a page edge.
+  Four things now turn that into a menu system. `position-anchor: --file`
+  names the box to position against (an `anchor-name` or an `#id`) instead of
+  finding it among the surface's own siblings, so a menu no longer has to be
+  declared beside its trigger; it also marks the element as a surface, as does
+  the new `popover` tag. `position-area: bottom start` is the side and the
+  cross-axis alignment in one declaration, and `position-try-fallbacks:
+  "top start, right start"` is an ordered list of areas tried until one is
+  wholly on the page — `position-try-order: most-space` takes the roomiest
+  instead of the first. `fit-viewport: true` clamps a surface to the room it
+  actually has and, with `overflow` set, `scrollHeight` is the rest of the
+  menu. `presentation: anchored | sheet | fullscreen` and `sheet-below: 600px`
+  cover the case no placement can: at 390 wide an anchored menu is the wrong
+  widget, so it becomes a sheet along the bottom edge with its children laid
+  out again at the page's width. `overflow-y`/`overflow-x` are accepted and
+  set `overflow`, which this engine has one of. And `anchor()` is read in the
+  inset properties — `left: calc(anchor(right) - 12px)` — which places one
+  edge against one edge of the anchor, with both insets on an axis stretching
+  the box between them; that is the badge-on-a-corner case no area can state.
+  [`lib/evg/EVGLayout.rgr`](lib/evg/EVGLayout.rgr),
+  `npm run evg:popover:test`, and the README's
+  [Surfaces](lib/evg/README.md#surfaces-popovers-anchors-and-presentation).
+
+- **Connectors: a line between two elements, drawn by the layout.** A
+  `connector` names two boxes (`from`/`to`, an `anchor-name` such as
+  `--orders` or an `#id`), and EVG writes its `d` on every layout pass from
+  the rectangles they came out as. `from-side`/`to-side` default to `auto`,
+  which picks the facing pair — so the same connector leaves the right edge
+  while two cards sit side by side and the bottom edge once the grid stacks
+  them on a phone. `routing` is `straight`, `orthogonal` or `bezier`;
+  `arrow-start`/`arrow-end` are `open` (stroked) or `triangle` (filled) at
+  `arrow-size`; everything else is the stroke vocabulary a `path` already
+  has. `path` is unchanged and still the right tool when the author owns the
+  geometry. [`lib/evg/EVGConnector.rgr`](lib/evg/EVGConnector.rgr),
+  `npm run evg:connector:test`.
+
+- **Erazer turns a UI screenshot into an EVG layout.** `gallery/erazer`
+  grows colour regions, nests them, and guesses widget classes (button,
+  text field, tab, menu, checkbox, slider, label, icon) instead of tracing the
+  picture as ink the way `EvgBitmapTracer` does. Icons that remain are
+  handed to that tracer as SVG. `npm run erazer:test` paints synthetic
+  UI-library fixtures with a 5×7 face and checks the tree; `npm run
+  erazer -- in.png out.evg.json` is the CLI; `npm run erazer:web:serve`
+  is the live page (paste or pick a screenshot in the tab; also at
+  https://terotests.github.io/Ranger/evg/erazer/ once Pages deploys). `npm run erazer:shots` captures HTML/CSS widgets
+  (login, tabs, menu, toolbar, dialog, buttons, sidebar) and a
+  shadcn/ui-shaped dark zinc dashboard, plus the live page itself.
+  The live overlay is pinned to the image (not the padded stage) with a
+  **tausta** opacity slider. Same-row chips of equal height and fill with
+  one-line labels are promoted to buttons together; a wide thin bar with
+  an optional circular thumb is a **slider**.
+- **CodeGraph diffs two git revisions.** `codegraph_cli … --diff=base..head`
+  (or `--diff=base` against the working tree) and the desktop **Diff**
+  button check each side out as a detached worktree, analyse it the way
+  Open does, and compare classes by name and members by name: fields whose
+  type changed, methods whose signature changed, and methods whose lines
+  the file's line diff touched are `changed`; the rest `added` / `removed`.
+  The explorer opens on a diff page of only the touched classes (amber /
+  green / red), class pages keep the colours on their rows, and the source
+  pane shows touched files merged, removed lines in place on red bands.
+  The desktop rail lists the opened repository's log as base / head
+  pickers, and a pull request field (`12`, `#12`, a URL) fetches
+  `refs/pull/N/head` from origin and diffs from the merge base with the
+  target branch (`gh` when installed, else the remote's default branch);
+  the CLI takes `--pr=`. Rows keep their ink and carry a mark (`+`, `−`,
+  `Δ`) with a tooltip saying why; a `+ N more` row is marked when the
+  folded members include a change, and clicking it lists every member of
+  the class in a drawer that slides in from the left and leaves the chart
+  and the source pane usable — `gallery/ui` gained `DrawerCtl`, a
+  non-modal panel any host can fill, for it. The source pane copies its selection with Ctrl+C
+  (the tab through the clipboard API, the desktop through SDL) and, in
+  the tab, measures with the Noto Sans face it draws with rather than a
+  bitmap font's fixed step, which had spread the tokens of a line apart.
+  `CodeGraphDiff` needs neither git nor the
+  compiler; the web page's EXAMPLE menu diffs `calls.rgr` against
+  `calls_v2.rgr` in the tab.
+  RangerFlow rows gained `tint` / `tintText` and ScriptEditor `lineMarks`
+  for this. `npm run codegraph:diff` is the unit suite.
+
+- **EVG live build** (`gallery/evg/livebuild/`). A demo of streaming an EVG
+  display list to a browser while an agent constructs the tree: thinking
+  tokens, `EVGPatch` ops, Ranger source and frames on SSE. The recipes are
+  scripted (dashboard, settings, invoices) so the pictures always land; a
+  live model that wrote the same ops would use the same socket.
+  The page is a local orchestrator (`agents.mjs`): recipe is the default,
+  Codex / Claude Code / Cursor / Ollama are adapters when those CLIs are
+  present. `npm run livebuild:serve` (no keys). `npm run livebuild:withcursor`
+  drives the local Cursor Agent CLI (`agent login` or `CURSOR_API_KEY`).
+  The prompt plus **Follow up** edits the live phone; Start-over chips
+  (Dashboard / Empty) are the only wipe. `npm run livebuild:test`.
+
+### Changed
+
+- **Generated-code quality scores are recomputed on this compiler.**
+  The twelve `gallery/friendly` studies were compiled again after native
+  loops (#1024), C++ value records, behaviour-only traits as interfaces,
+  and the C++/Rust optional fixes. Rank is now Kotlin 76, Dart 73, C# 72,
+  Python 67, Swift 64, Rust 61, PHP 59, TypeScript 59, JavaScript 58,
+  Java 58, Scala 57, C++ 54, Go 48. PHP and Scala still emit index loops.
+
+- **The front-page Targets section is generated-code quality status.**
+  The heading is "Generated code quality": an index of the thirteen
+  official source back ends, a score table, and the same two lists for
+  every language — what works well, and current limitations. The
+  percentage is the mean of twelve `gallery/friendly` study scores
+  (0–100, how close that file is to code a native developer would keep),
+  not a compile-success score. The "Write for the strictest target" and
+  "Extending it is not a rebuild" boxes come out. Swift 3, LLVM and WASM
+  stay out of the table.
+
+- **The repository root, and the compiler folder, hold the product.** The root
+  had 71 markdown files, nine compiled JavaScript files, eleven buffer and JPEG
+  probes, a rustc log, a Node stack trace and a `pubspec.yaml` naming a Dart
+  package that lives under `gallery/`. It now has six documents and no build
+  output, and `.gitignore` covers every extension a compile run from the root
+  produces. Open plans moved to [`docs/plans/`](docs/plans/README.md), finished
+  ones and seven directories that are not the product — `adventofcode`,
+  `fiddle`, `rust_compiler`, `native`, `features`, `generated`, `versions` — to
+  [`legacy/`](legacy/README.md), each with a README saying what it was. The npm
+  scripts that drove `features/` and `generated/` went with them: they pointed
+  at `.rgr` files in folders that hold only `.clj`, so they had been failing.
+  README no longer offers `versions/<target>/compiler.js` as the rollback; the
+  git history of `dist/rgrc.js` is.
+
+- **`compiler/` holds the compiler.** A walk of `Import` from the entry point
+  reaches 76 of the 134 `.rgr` files that were in the folder. The other 57 were
+  earlier editions kept beside the live file (`ng_RangerFlowParserOrig.rgr`,
+  `ng_FlowWork.rgr`, six `ng_parser*` variants), twenty probes from before
+  `tests/` existed, ten plugin samples that nothing loads by path — a compiler
+  plugin is an npm package reached with `require` — and fifteen `.bat` scripts
+  calling `ranger-compiler -compiler` on `.clj` files. `compiler/index.js`, a
+  1.0 MB generated compiler, and `compiler/package.json`, declaring version
+  2.1.61, went with them; what ships is `dist/rgrc.js`.
+
+- **A compiler file is named after the class in it.** The `ng_` prefix came
+  from the compiler that preceded this one and none of the classes carry it.
+  59 files renamed, every `Import`, npm script, test and document rewritten in
+  the same commit so no file is reachable by two spellings (ISSUES.md #64).
+  `ng_parser_v2.rgr` became `RangerLispParser.rgr`, `ng_parser_std_match2.rgr`
+  `FlowStdMatch.rgr`, `ng_writer.rgr` `CodeWriter.rgr`.
+
+- **The three files over 9000 lines are split by what each part does.**
+  `RangerFlowParser` 9364 → 4702 (`FlowShape`, `FlowCollect`, `FlowTypes`,
+  `FlowTree`, `FlowImport`, `FlowProcess`), `RangerRustClassWriter` 12047 →
+  3056 (`RustCall`, `RustOperators`, `RustClass`, `RustOwnership`,
+  `RustUnion`), `LowIRBuilder` 12302 → 3695 (`LowIRExpr`, `LowIRCollections`,
+  `LowIRStmt`, `LowIRObject`, `LowIRLambda`, `LowIRExtern`, `LowIROwnership`).
+  Each uses the `extension` form `FlowEnterVarDef.rgr` and `FlowStdMatch.rgr`
+  already used, so the class stays in one place and only methods move — every
+  body verbatim. Every compiler file is now under five thousand lines except
+  `Lang.rgr`, which is the `language { }` document, not a class file.
+  The emitted compiler is the same code in a different order, and compiling
+  again from it is a fixpoint.
+
+- **The front-page hero columns are "There is no Silver Bullet." and
+  "Stay Dry."** Ranger is more like golden — a golden-file harness that
+  emits ordinary Swift, Kotlin and JavaScript, not a magic runtime. The
+  definition sits as a small footnote under the first column.
+
+- **The gold Native section is "Native apps without duplicating the
+  logic."** One source of shared logic compiled to Swift and Kotlin,
+  called from SwiftUI and Compose with no bridge; a rule changes once
+  in the `.rgr` file. The Shopify quote and the six-up feature grid
+  come out.
+
+- **The public site title is "Rewrite? Use Ranger."** The front page
+  heading is two lines — "Rewrite?" then gold "Use Ranger." — and the
+  document title, Open Graph title, documentation `<title>` suffix
+  (`Page | Rewrite? Use Ranger.`), and playground tab title all use that
+  line. The docs header still says Ranger.
+
+- **Getting started step 03 is the edit loop, not the old exit-status bug.**
+  The front page's path is now: start from the starter, compile the targets,
+  change `src/Main.rgr` and run it again, then take a gallery package when
+  you need one. Generated output stays ordinary source you can open and
+  diff; the `.rgr` file is the source of truth.
+
+- **EVG is MIT and lives in `lib/evg`.** The layout engine moved out of
+  `gallery/` (AGPL) to `lib/` (MIT) together with the image codecs it needs,
+  which are now the package `lib/image` (`Buffer`, `ImageBuffer`,
+  `RasterBuffer`, the JPEG decoders, `PNGDecoder`, `PNGEncoder`, `Deflate`;
+  moved from `gallery/pdf_writer/src` and `gallery/game_engine/lpc`).
+  `lib/zip` is the package `zip`. The parts of EVG that need the gallery's
+  rasteriser and font engine — `EVGWindow`, `EVGTextFit`,
+  `EVGContextMeasurer`, `EVGRulerView`, `EVGToolbarView` — are the AGPL
+  package `gallery/evg_window`. Every gallery project that draws through EVG
+  now has a `ranger.json` and imports it as `pkg:evg/…` (and `pkg:image/…`,
+  `pkg:evg_window/…`) instead of `../evg/…`, so `lib/evg` compiles the same
+  inside this tree and when fetched alone with `rgrc install`. See
+  LICENSING.md.
+
+- **The JavaScript compiler compiles about twice as fast.** RtHost.rgr
+  (157 files, 108 102 lines) went from 17.9 s to 8.5 s, and the compiler
+  compiling itself from 19.9 s to 6.6 s, with byte-identical output apart
+  from the constructor lines below. Four causes, none of them in the
+  algorithms:
+  - A field with no initial value was left out of the constructor and
+    appeared on the object at first assignment, so one class had as many
+    V8 hidden classes as there were assignment orders (CodeNode: 27). Every
+    property access on such objects went megamorphic and the optimiser
+    deoptimised in a loop. The ES6 writer now initialises every field, to
+    `undefined` where there is no value; `typeof`, `== null` and
+    `JSON.stringify` read the same as before.
+  - V8 gives a field the representation of the first value stored in it.
+    `CodeNode.double_value` and `int_value` began as small integers, and
+    the first fractional literal in a program changed the representation
+    on every node already made, each of which was then rewritten on its
+    next access -- 2.4 s of the RtHost compile, paid by whichever pass
+    first walked the tree. The parser now stores such values once, when one
+    node exists.
+  - `read_file` awaits `fs.readFile`, so every function that reads a file,
+    and every function that can reach one, was emitted `async`: in the
+    compiler that was the whole import, analysis and writer chain, and each
+    call paid for a promise and a heap frame -- 6.3 GB allocated and three
+    seconds of garbage collection per compile. New `read_file_sync`
+    operator, synchronous on JavaScript, used by the compiler's own file
+    reads; the compiler now has no async method.
+  - Flags and classes live on the root context, but `hasCompilerFlag` and
+    `isDefinedClass` walked up the context chain to find them, nine million
+    and seven million times per compile. The root is now cached at fork.
+    `getOpFns`, asked for every call expression and empty nearly every
+    time, no longer builds and copies a list per level of the chain, and
+    `TTypeRegistry.isScalarPrimitive` no longer rebuilds its name list
+    for every element it compares against.
+
+### Fixed
+
+- **A demo that moves on its own now gets a frame without being touched.** Every
+  path that started the gallery page's clock was an INPUT — a press, a key, a
+  focus — because every demo that moved did so in answer to one. A surface
+  effect does not, so `?demo=effects` opened on a still picture of a drifting
+  sky until you poked it. The clock is started on the first paint and when the
+  switcher changes demo; it stops on the first frame whose clock says nothing
+  is moving, which is all of them until something is.
+
+- **A liquid-glass pane wiped everything painted before it, on any real page.**
+  A backdrop effect copies the surface mid-frame, and it was copying from the
+  canvas — but a WebGL2 context asked for `antialias: true`, which is the
+  default and what every page here asks for, has a MULTISAMPLED default
+  framebuffer, and copying out of one is `INVALID_OPERATION`. The copy left the
+  texture black and the pass wrote that black back over the whole page above
+  the pane. A frame with a live backdrop now goes through the offscreen target
+  and is presented at the end. The checks had passed on the broken painter
+  because they rendered with `preserveDrawingBuffer: true`, which on this
+  driver hands out a single-sampled buffer: `fx-check.mjs` now asks for what a
+  page asks for and reads pixels back through a 2-D canvas, and fails three
+  ways without the fix.
+
+- **The UI demo page did not work on a phone.** `gallery/ui/demo` wrote each
+  demo's own width straight onto the canvas and let the rest hang off the
+  right-hand edge, where a finger could not reach it — and the 230px rail took
+  most of a 390px screen before the stage got any. The stage is now scaled to
+  the room the viewport has (`transform` on `#stage`, the wrapper carrying the
+  laid-out size, the backing store sized for the pixels actually on screen),
+  the canvas is the demo's OWN width rather than 1240 for all of them, and
+  under 860px the rail becomes a one-line `controls` disclosure above the
+  stage. `window.__stageScale` publishes the factor, because anything driving
+  the page from outside aims at display-list coordinates.
+
+- **A canvas demo could not be reached from the keyboard at all.** The page
+  handed `state.focus` — its own field, kept for the menubar and nothing else
+  — to every demo's `a11yJson`, so the accessibility mirror was told nothing
+  was focused on nineteen of the twenty. With a roving tabindex that means NO
+  element is a tab stop: Tab walked straight past the dropdown, the tree and
+  the table. Each demo's own focus now reaches the mirror, focus arriving by
+  Tab is reported back to the demo (`onFocus`), and `evg-a11y.js` keeps one
+  entry tab stop while an app names no focus — a roving pattern always has
+  one. Tab is also no longer swallowed: `DropdownDemo.key` answers "taken" to
+  any key at all, so the page called `preventDefault()` on Tab and the focus
+  could neither enter nor leave.
+
+- **The keyboard moved the selection and the highlight stayed behind.** Every
+  pointer handler on the demo page started the animation clock; the keydown
+  handler painted once and stopped. A row's background is a transitioned
+  property, so the one frame a key produced was the frame the transition had
+  not started in — the tree's grey sat on the row the arrow had just left, and
+  moved only when something else repainted. Arrowing the tree, the dropdown
+  and the table now looks like what it does.
+
+- **The table demo had no keyboard.** `main.js` gave it `key: () => false` and
+  `TableDemo` had nothing to hand a key to. It now carries a roving focus over
+  the ring its own tree publishes as focusable — the select-all box (which was
+  not focusable and now is), the sortable headers, the row boxes and the pager
+  — with the arrows to walk it, Home and End, and Enter or Space to work the
+  control you are on. `table.css` grew the `:focus` rules without which none
+  of that was visible.
+
+- **The invoice form's Email validator never changed its mind.** The error was
+  a string assigned once in `FormDemo.init`, so the red ring and "That address
+  is missing an @." stayed on the field whatever was typed into it. It is
+  decided from the value on every rebuild now, and each message says what is
+  wrong — a missing @, a space, nothing before or after it, a host with no dot
+  — rather than that something is.
+
+- **"Find a customer" searched nothing.** It was an `InputCtl` with a
+  magnifier drawn in front of it: a field that looks like an autocomplete and
+  filters no list. It is a `ComboboxCtl` now — the same one the metadata card
+  uses, measured against @base-ui/react/combobox — so typing filters, the list
+  opens under the box, the arrows walk it and Enter takes a row into the
+  field. `ComboboxCtl.applyEdit` is the new seam a host that lets the platform
+  do the editing needs: a keystroke and a browser edit have the same effect on
+  the list, and neither host has to reimplement it. The form claims the arrows
+  back from the text bridge for that field alone (`ownsKey`), because there
+  they walk the list rather than the caret.
+
+- **`evg:view:check` flaked in CI on a landing-only pull request.** The
+  suite draws each scene twice — once with the view baked into the list,
+  once with it on the camera — by rewriting one `file://` HTML file and
+  navigating to it. Chromium will sometimes answer the previous document
+  for that URL, `waitForFunction` sees the leftover `__DONE__`, and the
+  comparison reads the last framebuffer: one of thirty-one checks fails,
+  the rest pass. A unique query on each load is a different navigation;
+  `gl.finish()` lands before the read; a mismatch draws both sides again
+  before it is a failure. The gallery-editors runner also printed only
+  the last thirty lines of a failed suite, which hid the `FAIL` behind
+  later PASSes.
+
+- **The published compiler shipped a thinner `stdlib.rgr` than the one the
+  tests ran against.** `compiler/stdlib.rgr` and `lib/stdlib.rgr` had drifted:
+  the compiler's copy carried the LLVM `case` and `is` templates that let
+  `lowerShapeCase` bind its operand, and the Swift `_ = name` lines that stop
+  swiftc warning once per arm of an exhaustive `match`. Which copy you got
+  depended on where you compiled from. In the repository RANGER_LIB puts
+  `compiler/` first, so CI always exercised the fuller file; `build:dist:copy`
+  is `cp -r ./lib ./dist/lib` and the published package resolves every import
+  from there, so an npm user compiling a `match` to Swift got the warnings and
+  to LLVM got an unmatched operator. `lib/` now holds the merged file and the
+  duplicate under `compiler/` is gone. `compiler/JSON.rgr` was byte-identical
+  to `lib/JSON.rgr` and went the same way. Both imports keep their spelling;
+  resolution finds them one directory later.
+
+- **`.claude/skills/ranger-lang/SKILL.md` said the compiler exits 0 on
+  `[FAIL]`.** It has exited non-zero since 3.5.1, and the copy under
+  `plugins/ranger/` already said so. The two copies had drifted in both
+  directions — the plugin copy still said `(obj.method()).field` does not
+  work — and are now identical and correct.
+
+- **`@media` was silently inert in every CLI tool.** `EVGStyleSheet` evaluates
+  a media query against a viewport the caller states, and a query it cannot
+  evaluate does not apply — but `EVGStyleLoader`, which every `-css` flag goes
+  through, never stated one. So the responsive half of a stylesheet did
+  nothing in the PNG, PDF, HTML, JSON and display-list tools while the same
+  sheet worked in an application, with no warning either way: the page
+  rendered, and it rendered wrong. The tools know their page size before they
+  apply anything, and now pass it.
+
+- **`position: absolute` was dropped inside a `display: grid` parent.**
+  `layoutGrid` left out-of-flow children out of the placement, which is
+  right — an absolute box takes no track — and then nothing laid them out at
+  all: the box kept zero size at (0,0), so an absolutely positioned `div`
+  vanished and a `path` drew its own coordinates in the page's top-left
+  corner with `left`/`top` ignored. The same element under a flex or block
+  parent was placed correctly, which made it look like a `path` bug. The
+  out-of-flow pass is now one function (`EVGLayout.layoutOutOfFlowChild`)
+  that both flow and grid run.
+
+- **An array literal survives a call whose result is dereferenced.**
+  `(box.take(([] _:string ( "a" "b" )))).count()` emitted
+  `box.take("a""b").count()` — the elements where the array should be. Two
+  elements did not parse on JavaScript or PHP; one element parsed and answered
+  the STRING's length, so `take(([] _:string ( "abc" )))` counted 3. Every
+  target, and the compiler reported success either way, which is why
+  `lib/Shell.rgr` and `lib/apple/` build every argument vector with `push`
+  rather than writing it inline.
+
+  `transformDotMethodCallExpr` walked the receiver — that is how it learns the
+  receiver's type and decides this is a method call at all — and then put a
+  COPY of the walked node into the rewritten `call`. Walking an array literal
+  is destructive: the node's children become its elements and the node is
+  marked `is_array_literal`, and the two together are what an array literal is
+  after analysis. A copy is built for re-analysis and carries no analysis
+  result, so it had the elements and no mark: a bare list. The receiver is
+  copied before it is walked now, and that untouched copy is what the rewrite
+  gets. ISSUES.md #85.
+
+  The one-element literal still goes missing on Rust, chained or not — that is
+  #84, in the Rust writer.
+
+- **A failed compile exits non-zero.** `rgrc` printed `[FAIL]` and
+  `Compilation FAILED` and then returned success, so
+  `rgrc x.rgr && node bin/x.js` was satisfied by that zero, ran the
+  *previous* build, and printed what it printed before the change — the edit
+  looked applied and the test looked green when neither was true. Every
+  `&&` in every build script believed the zero, which is why a dozen scripts
+  in this repository read the compiler's log instead of its status. The
+  status now says what the report says: 1 when the run had errors (a parse
+  error, a missing file, any compiler error, a failed `rgrc install`),
+  0 otherwise.
+
+  The code is set rather than the process ended on the spot: node writes a
+  piped stdout asynchronously, and `process.exit()` there drops the error
+  report the status is about — `log=$(rgrc … 2>&1)` would get the status and
+  lose the reason. The new `set_exit_code` operator in `Lang.rgr` spells
+  that on each target (`process.exitCode` on JavaScript,
+  `Environment.ExitCode` on C#, the same immediate exit as `exit` where
+  stdout is unbuffered or flushed at exit).
+
+- **CodeGraph web page: css / evg / zip / cpp did not open from the EXAMPLE
+  menu.** The app could only compile what its VFS held, and the gallery
+  pack (and the C++ fixture) were fetched only for `?example=`. A pick the
+  app cannot serve is now handed back to the page (`consumePendingSample`),
+  which fetches the sources and picks again. The page also awaits the
+  app's methods — the ES6 bundle makes any path that may read a file
+  `async`, and `selfTest()` came back as a Promise, which is why
+  `codegraph:web:test` failed with `nav.startsWith is not a function`.
+- **CodeGraph: a class did not list who uses it through a method.** Rose
+  boxes above a class came from field types only, so `Checkout` showed no
+  `CodeGraphFixtureMain` although `main()` creates one. Classes whose
+  methods mention or call the class are now backrefs too, with the method
+  rows and a dashed `uses` edge from each row.
+
 ## [3.5.1] - 2026-09-17
 
 - **The npm README still said 3.3.0.** The package was 3.5.0; the first line
@@ -22,7 +1066,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`rgrc install` fetches what `ranger.json` names.** `Import "pkg:…"`
   used to resolve only against files already on disk, so a clean checkout
-  of a project that depends on `gallery/evg` had nothing to compile
+  of a project that depends on `lib/evg` had nothing to compile
   against. The compiler now walks the graph, sparse-fetches each git
   dependency at its pinned revision, writes it into the cache
   (`RANGER_PKG_CACHE`, else `~/.cache/ranger/packages/<sha256>`), recurses
@@ -139,7 +1183,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
   cell's text lands in the third cell.
 
 - **A design for the camera on the GPU.**
-  `gallery/evg/PLAN_VIEW_TRANSFORM.md` asks why a canvas rebuilds its whole
+  `lib/evg/PLAN_VIEW_TRANSFORM.md` asks why a canvas rebuilds its whole
   display list for every frame of a pan, when the pan is a translate the vertex
   shader already applies for scroll layers (`uShift`) and the scene has not
   changed. The list would be built in scene space and carry the camera beside
@@ -156,7 +1200,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 - **Two fingers pinch the canvas, and the gestures are one module.** Drag to
   pan, wheel to zoom, a press that does not travel is a click — every
   standalone had written its own, and none of them had a pinch.
-  `gallery/evg/gl/evg-gestures.js` is that handling once, for any EVG canvas:
+  `lib/evg/gl/evg-gestures.js` is that handling once, for any EVG canvas:
   it reads the view the host keeps and hands back another, so the host goes on
   deciding when to paint. The anchor holds the point under the cursor, or
   under the midpoint of two fingers, where it is; a trackpad pinch (a wheel
@@ -251,7 +1295,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
   the page `EVGDisplayList.toBinary()` — three `Int32Array`s and a string
   pool — where it used to hand it JSON: on a board of 3,565 nodes that is
   5,630 ms a frame against 180, and the two bridges describe the same picture
-  to the hundredth (`gallery/evg/gl/list-binary-check.mjs` holds them to it).
+  to the hundredth (`lib/evg/gl/list-binary-check.mjs` holds them to it).
   `scene()` still answers in JSON for anything that wants to read a frame.
 
 - **A flattened outline is kept on the element it belongs to.** `d` is a
@@ -824,7 +1868,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
   for node. 101 + 102 + 17 + 16 assertions and 24/24 target builds; the client
   build an app carries is 113 kB of Kotlin, which is the measured answer to
   whether it fits on a watch. Plan and the phases left in
-  [`PLAN_FIRESIM.md`](PLAN_FIRESIM.md).
+  [`PLAN_FIRESIM.md`](gallery/firesim/PLAN_FIRESIM.md).
 - **A segmented date field, measured against the browser's own.** The
   calendar demo's date box was a formatted label; a person asked for the
   `__/__/____` editor, and shadcn has none to measure (its Date Picker is a
@@ -1046,7 +2090,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
   `ranger/rt_ios.rgr` imports `RealTrainerDemo.rgr` unchanged and compiles to
   19 000 lines of Swift holding the EVG controllers, the cascade, the layout
   engine, the display list and the demo. Nothing about the app is written twice
-  for Apple; `gallery/evg/apple` paints it, as it paints the dashboard.
+  for Apple; `lib/evg/apple` paints it, as it paints the dashboard.
 
   The facade is not a copy of the dashboard's, because the two pages are not
   the same shape. The dashboard is a DOCUMENT -- a fixed width that scrolls, so
@@ -1077,7 +2121,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 
 ### Fixed
 
-- **`gallery/evg`: a grid flag nothing read.** `EVGLayout.layoutGrid` set
+- **`lib/evg`: a grid flag nothing read.** `EVGLayout.layoutGrid` set
   `usingSubgrid = true` when a column template inherited its tracks from the
   enclosing grid, and then never looked at it. The subgrid effect is carried
   entirely by rewriting `colSpec` into the parent's pixel tracks, and the rows
@@ -1361,7 +2405,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
   iPhone, iPad and Apple Watch.** The same `DashboardDemo.rgr` the browser
   page, the gates and the Android port run, compiled to Swift 6 (46 039 lines,
   one file) and painted with CoreGraphics through the new
-  [`gallery/evg/apple`](gallery/evg/apple/README.md) — an `EvgSurface` protocol,
+  [`lib/evg/apple`](lib/evg/apple/README.md) — an `EvgSurface` protocol,
   an `EvgPainter` transliterated from the Android one, and a single `CGContext`
   backend that serves UIKit, SwiftUI and watchOS alike.
 
@@ -1394,7 +2438,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
   source: Kotlin on a JVM (the Wear OS language, with a C1-only run as the
   ART-quality bracket), C++ ahead-of-time and reference-counted (the watchOS
   proxy), and JavaScript on Node. The Kotlin run paints through
-  `gallery/evg/android`, the same painter and surface the `ui` and `pptx`
+  `lib/evg/android`, the same painter and surface the `ui` and `pptx`
   Android ports compile into their APKs, and writes the three PNGs.
 
   The answer is **no, EVG is not too heavy**: the busiest screen is 0.91 ms for
@@ -2290,7 +3334,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 
 - **Three defects in Vela that only a program calling it could reach** — each found by building six charts through the new chart API and comparing the drawing against official Vega-Lite and Vega, and none of them in the API. `%q` was **not a directive** in the time formatter, and an unknown directive answers its own letter, so every chart with `timeUnit: "yearquarter"` — which the official compiler turns into the format `"%Y Q%q"` — labelled its axis `2016 Qq` and said nothing about being wrong. A **grouped bar chart of stated width drew twenty-pixel bars**: which way round the two bands are sized depends on who decided the plot's size, and the sub-scale was always given a fixed twenty-pixel step, which is right only when nobody said how wide the plot is (then the band above it is sized *from* the sub-bands) and leaves a third of every group empty when somebody did — the sub-scale has to span the band it sits in, `[0, bandwidth('x')]`, exactly as the reference writes it. And **the key to a see-through area was drawn solid**, because a legend symbol's opacity was read only off an `opacity` channel and not off the mark (`{"type": "area", "opacity": 0.35}`), which is how every layered chart shades its filled half. All 48 goldens, 4848 drawn primitives, 44 Vega-Lite sources and the 188-example gallery corpus (172 exact, 3 random-by-construction) are unchanged by the three
 
-- **A long value in a dialog field was drawn straight out of the field, across the panel and over the sheet behind it** — `EVGWindow`'s input control drew `c.value` from the field's left edge at full length, with no window and no cut. Clipping alone does not fix it: `SoftPainter` honours a clip rectangle **per draw call** (`textInClip` tests the text's ORIGIN), so a string that starts inside the box is drawn whole, and the WebGL and SDL hosts scissor at their own granularities again. Text that must not escape a box has to be cut to the box on every backend. The cut now lives in one place, `gallery/evg/EVGTextFit.rgr`: the window that fits the field **and** contains the caret (grown left from the caret while there is room, then right with what is left, so typing at the end scrolls the text and moving back brings the earlier text into view), the measured caret offset inside that window, a hit test measured the same way, and the label trimmer the grid already had. `EVGWindow`'s input, the grid's cell labels and the formula field all go through it. The display-list primitives moved to `EVGDisplayList` itself (`addRect` / `addFrame` / `addText` / `addClip` / `addClipEnd`) — `GridView` and `EVGWindow` each had their own encoder for the same commands — so a dialog and the grid behind it cannot drift into two encodings. `npm run datagrid:textfit:test` checks the display list rather than the picture: for every piece of text that starts inside a panel, does it end inside it too? It fails on the code from before the fix. Also: the database window smoke now addresses cells by name (`nav.goto E2`) instead of by pixel, after a merge with master moved the grid geometry under its hard-coded clicks
+- **A long value in a dialog field was drawn straight out of the field, across the panel and over the sheet behind it** — `EVGWindow`'s input control drew `c.value` from the field's left edge at full length, with no window and no cut. Clipping alone does not fix it: `SoftPainter` honours a clip rectangle **per draw call** (`textInClip` tests the text's ORIGIN), so a string that starts inside the box is drawn whole, and the WebGL and SDL hosts scissor at their own granularities again. Text that must not escape a box has to be cut to the box on every backend. The cut now lives in one place, `gallery/evg_window/EVGTextFit.rgr`: the window that fits the field **and** contains the caret (grown left from the caret while there is room, then right with what is left, so typing at the end scrolls the text and moving back brings the earlier text into view), the measured caret offset inside that window, a hit test measured the same way, and the label trimmer the grid already had. `EVGWindow`'s input, the grid's cell labels and the formula field all go through it. The display-list primitives moved to `EVGDisplayList` itself (`addRect` / `addFrame` / `addText` / `addClip` / `addClipEnd`) — `GridView` and `EVGWindow` each had their own encoder for the same commands — so a dialog and the grid behind it cannot drift into two encodings. `npm run datagrid:textfit:test` checks the display list rather than the picture: for every piece of text that starts inside a panel, does it end inside it too? It fails on the code from before the fix. Also: the database window smoke now addresses cells by name (`nav.goto E2`) instead of by pixel, after a merge with master moved the grid geometry under its hard-coded clicks
 
 - **A declared empty constructor produced a body-less `__init__` on the Python target** — `ng_RangerPythonClassWriter` already emits `pass` for an empty body, but it set `hasContent = true` for any class that *declared* a constructor rather than for one whose body actually wrote something. A class with no fields, no parent and `Constructor () { }` therefore compiled to `def __init__(self):` with nothing under it, and Python failed to parse the whole module at the next method (`IndentationError: expected an indented block`). Every other target was unaffected, because only Python's block structure is whitespace. It is now measured the same way `pyWalkBody` already measures a method body — the writer's line and column before and after walking the constructor — and a `super().__init__()` call counts as content, so a subclass with an empty constructor no longer gets both the super call and a stray `pass`. Found by RangerSQL's dialect classes, which are pure behaviour and declare no fields at all. Compiler reproduces itself byte-identically; `compiler-python`, `compiler-conformance`, `compiler-selfhost`, `compiler-record`, `compiler-serialize` and `operator-coverage` pass, and `shapes`' 14 Rust failures reproduce on the unmodified compiler
 
@@ -2309,7 +3353,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 
 - **The rules a photo book has to satisfy belong to the printer, so they are data now** — `gallery/book` could lay a book out and draw it; what it could not do was answer "is this ready to send". `BookPrintSpec` is a supplier's requirements as a value — trim size, bleed, outer **and gutter** safety margins, the extent's minimum, maximum and multiple, the dpi floor and target, colour space, PDF profile, whether they want crop marks — with presets for layflat 210, hardcover A4, softcover A5 and sheet-fed offset, and preflight measures the book against whichever one you name. Hard-coding any of it would have produced an engine that is confidently wrong for every supplier but one: 3 mm of bleed is a European convention and not a law, a multiple of four is one binding's arithmetic, and one service wants CMYK while the next one wants RGB. Three things stayed assertions rather than settings because they are not negotiable. **Page 1 is a recto** — odd pages right, even left, and a cover is always the right-hand side of the sheet it is bound onto. **Single pages, in reader's order**, 1, 2, 3, 4: printer spreads (32–1 / 2–31) are the press's business, and imposing them yourself is how a book comes back bound inside out — the engine designs in spreads and exports leaves, which is the whole point of a page-layout program. And **a blank page is a page**: it takes a leaf, it is counted, and it has to be *in* the file, so `padToExtent` adds real ones rather than leaving a gap that silently moves every page after it onto the wrong side of the leaf. The gutter check is the one that earns its keep: it is a **bigger** margin than the cut edges and it applies to whichever side of the page the spine is on, which is the left of a recto and the right of a verso — a face centred in a spread lands in the fold, and on a cased book the fold takes 15 mm. **The spine is arithmetic and `BookCover` does it**: leaves × caliper for the text block, plus two boards for a case or the wrap for a softcover, with the squares, the hinge and the turn-in giving the cover sheet its real size — built as its own one-page landscape document, so the same renderer, the same PDF writer and the same picture-resolution checks apply to it. It still says, in the output and in the README, to take the supplier's own template before a production run; this exists so a cover can be proofed before that template arrives and so their number can be checked against one. `npm run book:print` writes `interior.pdf` (single pages at trim + bleed, with a **TrimBox** — 210 mm square is delivered as 216 mm square), `cover.pdf`, a `print.json` manifest carrying the fields a print-on-demand API asks for, `preflight.txt`, and `render.sh` — the exact commands with the computed page sizes already in them, because a cover PDF made at a retyped width has the title on the front board and the spine somewhere in the picture. It found a live trap on the way: **the committed `evg_pdf_tool.js` build predates its own `-bleed` flag** and contains no reference to bleed at all, so running it with `-bleed` accepted the argument, warned about nothing, and wrote a PDF at trim size — invisible until a press trims into the artwork. The script recompiles the tool before using it. 40 more assertions, **116 on the engine now, running on JavaScript, Go and Python**, plus the 64 editor ones and 17 in a real browser
 
-- **The book engine got an editor, and it runs in the page** — `gallery/book` could lay a book out and print it; it could not be *used*. Now it can: select a frame, drag it, resize it from eight handles, insert text and picture frames, reorder pages, undo. The frame around the canvas is the **shared** one the spreadsheet, the document and the deck already use — a fourth toolbar in a fourth style would have been the wrong kind of new code — and the selection chrome goes into the same `EVGDisplayList` as the pages, after them, so every host draws a complete editor without knowing what a handle is, and an exported book has none of it. Four rules are taken from the slide editor because they were right there and are right here (an id is not an index; history is snapshots; a drag is one edit; editing is a mode) and one is this program's own and is the whole difference: **every geometry edit re-flows** — resizing a text frame does not move text inside it, it moves text onto other pages, and an editor that does not re-flow after a drag is showing a book that does not exist. The gesture with no equivalent in a slide editor is **Link flow** (Ctrl+L): select two text frames and the story runs from one into the other. It moves no text; it changes where the text is *allowed* to go. **It is not a Node app with a browser attached.** `web/standalone/` compiles the entire engine — model, flow, preflight — to JavaScript and puts it IN the page: the browser hands it font bytes and photographs and draws the display list it gets back through WebGL 2, so a pointer move is a function call rather than a round trip and there is no host process at all (`npm run book:web`). The Node-hosted variant stays as `book:window`, for driving the editor from a script. Three findings came out of building it, all of the kind a screenshot makes look fine. **Snapping per-delta means a frame on a guide can never be dragged off it** — every one-point step is pulled back onto the line — so a drag is now measured from where it *began*. **A host that hands over every font face with `addFaceBytes` gets a renderer that draws correctly and measures with a 3×5 bitmap fallback**, because only `loadFontBytes` sets `hasFont`; the page was drawing the title in exactly the right typeface, at the wrong widths, so nothing ever wrapped. And **a WebGL page needs `@font-face` for the faces the engine measured with**, since `evg-webgl.js` rasterizes runs with the browser's canvas 2D and cannot see the engine's. The serverless page's self test now asserts the title wraps *and* that it is set in the display face, which is the pair that catches all three. Four things moved into `gallery/evg` because the book editor was the second caller: `EVGImageDecode` (PNG/JPEG bytes → pixels — it had been sitting in the deck viewer with a note on it saying it was not deck-specific), `EVGSelectChrome` (where the eight handles are and which edges each one owns — both editors now number their handles from the same file and read `applyResize`'s answers out of it), `EVGContextMeasurer` (EVG text measurement backed by a host's own renderer, which is what makes the flow engine measure with the faces the screen paints with), and `EVGDisplayList.offsetBy` / `.appendFrom`. The sample book is typeset rather than filled in — the showcase's editorial palette, Cinzel and Josefin Sans, a leaf ornament as a vector frame, captions on the pictures, first-line indents after the first paragraph — because a sample set entirely in the UI face proves nothing about a page-layout engine. **80 assertions on the engine (76) run on JavaScript, Go and Python; 64 more cover the editor and the host seam; 17 run in real headless Chrome on WebGL**, and `pptx`, `docx_viewer`, `datagrid` and the EVG toolbar suites are unchanged by the extractions (33 / 220 / 100 / 125 / 25, 244, 113, 23)
+- **The book engine got an editor, and it runs in the page** — `gallery/book` could lay a book out and print it; it could not be *used*. Now it can: select a frame, drag it, resize it from eight handles, insert text and picture frames, reorder pages, undo. The frame around the canvas is the **shared** one the spreadsheet, the document and the deck already use — a fourth toolbar in a fourth style would have been the wrong kind of new code — and the selection chrome goes into the same `EVGDisplayList` as the pages, after them, so every host draws a complete editor without knowing what a handle is, and an exported book has none of it. Four rules are taken from the slide editor because they were right there and are right here (an id is not an index; history is snapshots; a drag is one edit; editing is a mode) and one is this program's own and is the whole difference: **every geometry edit re-flows** — resizing a text frame does not move text inside it, it moves text onto other pages, and an editor that does not re-flow after a drag is showing a book that does not exist. The gesture with no equivalent in a slide editor is **Link flow** (Ctrl+L): select two text frames and the story runs from one into the other. It moves no text; it changes where the text is *allowed* to go. **It is not a Node app with a browser attached.** `web/standalone/` compiles the entire engine — model, flow, preflight — to JavaScript and puts it IN the page: the browser hands it font bytes and photographs and draws the display list it gets back through WebGL 2, so a pointer move is a function call rather than a round trip and there is no host process at all (`npm run book:web`). The Node-hosted variant stays as `book:window`, for driving the editor from a script. Three findings came out of building it, all of the kind a screenshot makes look fine. **Snapping per-delta means a frame on a guide can never be dragged off it** — every one-point step is pulled back onto the line — so a drag is now measured from where it *began*. **A host that hands over every font face with `addFaceBytes` gets a renderer that draws correctly and measures with a 3×5 bitmap fallback**, because only `loadFontBytes` sets `hasFont`; the page was drawing the title in exactly the right typeface, at the wrong widths, so nothing ever wrapped. And **a WebGL page needs `@font-face` for the faces the engine measured with**, since `evg-webgl.js` rasterizes runs with the browser's canvas 2D and cannot see the engine's. The serverless page's self test now asserts the title wraps *and* that it is set in the display face, which is the pair that catches all three. Four things moved into `lib/evg` because the book editor was the second caller: `EVGImageDecode` (PNG/JPEG bytes → pixels — it had been sitting in the deck viewer with a note on it saying it was not deck-specific), `EVGSelectChrome` (where the eight handles are and which edges each one owns — both editors now number their handles from the same file and read `applyResize`'s answers out of it), `EVGContextMeasurer` (EVG text measurement backed by a host's own renderer, which is what makes the flow engine measure with the faces the screen paints with), and `EVGDisplayList.offsetBy` / `.appendFrom`. The sample book is typeset rather than filled in — the showcase's editorial palette, Cinzel and Josefin Sans, a leaf ornament as a vector frame, captions on the pictures, first-line indents after the first paragraph — because a sample set entirely in the UI face proves nothing about a page-layout engine. **80 assertions on the engine (76) run on JavaScript, Go and Python; 64 more cover the editor and the host seam; 17 run in real headless Chrome on WebGL**, and `pptx`, `docx_viewer`, `datagrid` and the EVG toolbar suites are unchanged by the extractions (33 / 220 / 100 / 125 / 25, 244, 113, 23)
 
 - **A tool that says what this reader does not understand, and then most of the answer** — every fixture in the pptx gallery was written by the same hand as the reader, so every fixture is understood by construction; two decks from outside turned up six defects in an afternoon, all of them the same shape: an element walked straight past, drawing nothing and saying nothing. `npm run pptx:audit -- deck.pptx` walks every part of a package through the reader's OWN parser and reports what it never looks at, most-used first, in **two** lists — *known and deliberately not drawn* (3-D, embedded fonts, hyperlinks, per-script font fallbacks, animation beyond the build) and *UNREAD, nobody decided about these*. The difference between those lists is the difference between a decision and an oversight, and it turns "the slide looks wrong" into a work order; `npm run pptx:audit:check` runs it over every fixture and fails when one says something nobody has decided about. Pointed at the two decks the list was 24 and 39 kinds long, and it was mostly saying one thing: **text is inherited, not stated**. DrawingML states nine levels of list style, `a:lvl1pPr` … `a:lvl9pPr`, and this reader read the first — and only from the shape itself — so every sub-bullet in every real deck came out in the top level's size, colour and indent. A list style is nine levels now, every field paired with a "was this stated" flag because they are MERGED down a chain: master `p:txStyles` → the master's own placeholder → the layout's placeholder → the shape → the paragraph. The order cost a defect to get right: a deck built by anything but PowerPoint leaves `p:txStyles` as a generic black nobody meant and puts the real typography on the master's PLACEHOLDER, which sits above it — and the placeholder merge was applying its default run properties to every run before the level each paragraph sits at had been consulted, which marked them all as sized and coloured. Beside it: **`a:normAutofit`**, which is PowerPoint writing down how far it already shrank the text to make it fit (ignoring it is an overflow with a known cause); **bullets with their own colour, size and face**, and a layout that uses the deck's own `marL`/`indent` rather than a level's worth of invented indent; a paragraph's own `<a:buNone/>` and a stated `marL="0"` treated as decisions rather than silences; **`a:highlight`**, the colour behind a run; and the same fallback gap the emoji had one block down the codepoint chart — **a bullet is a geometric shape** (● ○ ■ ▪) that the text face does not have, so every list drew a column of empty boxes until Noto Sans joined the fallback pool. The two decks now report 9 and 22 kinds, **all deliberate, nothing unread**. `31-inherited-text.pptx` pins it down and round-trips byte for byte, which needed the writer to state what the levels resolved to — there is no master left to inherit from — and turned up one more instance of a defect this repository keeps meeting: `to_int` FLOORS, so `emu(-18pt)` biased and floored a negative twice and wrote -228601 EMU where the file said -228600, moving every hanging bullet by a fraction of a pixel
 
@@ -2346,7 +3390,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 
 - **A dot asks what the thing can do** — member completion, with a guess at the type behind it. Typing `.` opens the list with no prefix (because `body.` is already a question) and the answer comes from reading BACKWARDS for where the receiver was declared and classifying what is on the right of the `=`: an array literal offers `push` / `map` / `length`, a quoted string offers `toUpperCase` / `split`, `sheetRows(…)` is known to return rows so its members are an array's, `usedRows(…)` offers `toFixed`, an object literal offers **its own keys**, and `rows[i]` takes one step down through the subscript. There is no type checker and there is not going to be one on a keystroke — what there is, is the four ways a value gets its shape in a report script, which covers nearly every line anyone writes; when none of them matches the guess is `any` and the list is everything, which is what a type checker says about `any` too and is better than an empty popup. The member lists are **the methods ComponentEngine actually implements**, read off the engine rather than off the JavaScript standard: offering `.flatMap()` because JavaScript has it would be offering to write a line that cannot run. The Ranger plugin answers `this.` from the file — every `fn`, `sfn` and `def` in it, labelled `method`, `static` and `field` — because in a language with no imports to chase, the file is the scope. 121 unit checks and 83 in the browser
 - **The editor suggests, and its clipboard stopped lying** — autocomplete is the third question a language plugin answers, beside colours and problems: `complete(lines, line, col)` returns labelled candidates, two letters open the list, **Ctrl+Space** opens it whatever the prefix, arrows choose, Enter or Tab accepts and Escape closes. Accepting **replaces the word being typed** rather than appending to it. What is in the list is the plugin's opinion and the order is the whole of it: for TSX the **workbook API first** (`sheetRows`, `formatNumber`, `param`), then keywords, then every word already in the file — a report script is mostly the first and third and almost never `instanceof`; for Ranger the same shape with operators first. Neither plugin parses to answer, because `complete` runs on a keystroke. The popup is drawn into the display list like everything else, so WebGL and OpenGL both get it without knowing what a completion is, and it is **mirrored into the DOM** for assistive technology — the textarea becomes a `combobox` with `aria-expanded` and `aria-activedescendant`, the options live in a hidden `listbox`, and the live region says "6 suggestions, sheetRows selected". **Copy and cut now answer from the model.** Letting the hidden textarea serve Ctrl+C was right for a selection inside one line — the mirror holds exactly that — and silently wrong for every other: three selected lines copied one, and cut copied without deleting. `selectionText()` and `cutSelection()` come from the buffer now, the chords are let through to the browser so `copy` / `cut` / `paste` fire on the textarea (which is the only way to reach the system clipboard without a permission), and `metaKey` counts as well as `ctrlKey`, which is what made it look broken on macOS. Also: double click selects a word and triple click the line, through `EditorWord`, so a word means the same thing to the mouse as it does to Ctrl+arrow. And the header's **fps meter is gone** — the page deliberately does not redraw when nothing changed, so a frames-per-second reading of an idle editor is 2 and means nothing; the numbers worth watching (lines, tokens, lex and check times, draw commands) are in the status bar and come from the editor rather than from the loop. 102 unit checks and 77 in the browser
-- **A click handed the keyboard back, and the page redrew for nothing** — two defects a real browser session found that 52 passing checks did not. **Clicking into the code editor and then typing did nothing at all**: the browser moves focus on mousedown *after* the handler runs, and the canvas is deliberately not focusable (it is `aria-hidden`; the focusable element is the textarea that mirrors the caret's line), so the default action took the keyboard straight off it and gave it to `<body>`. One `preventDefault` on `pointerdown` fixes it — and the reason no test caught it is that **every test reached the editor with the keyboard**, by Tab or a programmatic focus, and none had ever clicked; `keyboard.mjs` now opens with a real mouse click and types after it. Second, the page ran at **4 fps** because the animation loop called `scene()` on every frame — build the display list, walk it, serialize it to JSON, ~1.4 ms — and then compared the string with the last one and threw it away. The loop now asks `revision()` first, a few string joins over the document version, the caret, the selection, the scroll line and the blink phase, and builds a scene only when that changed: idle went from 60 rebuilds a second to **2**, which is the caret, and which is why the blink now comes off the clock rather than off a frame counter. Third, and this one is everyone's: a Chrome profile put **160 ms — 36% of the frame — in `getShaderParameter`**, because `renderDisplayList` compiled and linked both of its shader programs on *every call*, and asking for `COMPILE_STATUS` is synchronous — it makes the CPU wait for a compile the driver was entitled to defer. `gallery/evg/gl/evg-webgl.js` caches the two programs and their attribute and uniform locations per GL context now, so the DataGrid's own WebGL page gets the same fix. A full redraw of the editor measures 2.9 ms of GL plus 1.4 ms of scene building on software rasterization in headless Chrome. Regression checks added for both: a mouse click that hands over the keyboard, and an idle second that redraws a handful of times rather than every frame (58 checks)
+- **A click handed the keyboard back, and the page redrew for nothing** — two defects a real browser session found that 52 passing checks did not. **Clicking into the code editor and then typing did nothing at all**: the browser moves focus on mousedown *after* the handler runs, and the canvas is deliberately not focusable (it is `aria-hidden`; the focusable element is the textarea that mirrors the caret's line), so the default action took the keyboard straight off it and gave it to `<body>`. One `preventDefault` on `pointerdown` fixes it — and the reason no test caught it is that **every test reached the editor with the keyboard**, by Tab or a programmatic focus, and none had ever clicked; `keyboard.mjs` now opens with a real mouse click and types after it. Second, the page ran at **4 fps** because the animation loop called `scene()` on every frame — build the display list, walk it, serialize it to JSON, ~1.4 ms — and then compared the string with the last one and threw it away. The loop now asks `revision()` first, a few string joins over the document version, the caret, the selection, the scroll line and the blink phase, and builds a scene only when that changed: idle went from 60 rebuilds a second to **2**, which is the caret, and which is why the blink now comes off the clock rather than off a frame counter. Third, and this one is everyone's: a Chrome profile put **160 ms — 36% of the frame — in `getShaderParameter`**, because `renderDisplayList` compiled and linked both of its shader programs on *every call*, and asking for `COMPILE_STATUS` is synchronous — it makes the CPU wait for a compile the driver was entitled to defer. `lib/evg/gl/evg-webgl.js` caches the two programs and their attribute and uniform locations per GL context now, so the DataGrid's own WebGL page gets the same fix. A full redraw of the editor measures 2.9 ms of GL plus 1.4 ms of scene building on software rasterization in headless Chrome. Regression checks added for both: a mouse click that hands over the keyboard, and an idle second that redraws a handful of times rather than every frame (58 checks)
 - **The SQL box shows the schema and offers examples written for it** — a prompt with no manual is not much help, and the one thing a person needs before writing a `SELECT` is the names of the tables and their columns. The box now lists them (`sales(id*, region, country, month, revenue, units)`, a star marking a key column, which is what decides whether a sheet built from the query can be edited) and offers five one-click examples generated from that schema — first rows, a `GROUP BY` over a text column and a numeric one, a `LIKE` filter, a `ORDER BY … DESC LIMIT`, and a `COUNT(*)` — so each of them runs as it stands instead of being a template to adapt. Both are asked of the session every time the box opens, so they are right after a reconnect too. A test parses every generated example and checks it names a table of this database. Dialog labels are also trimmed to the panel now (`EVGTextFit.fitLabel`, the same cut the input already used): a status line or a column list is text somebody else wrote, and it must not run out of the window
 
 - **The chart API runs in the browser, at `/evg/chart-api/`, and JavaScript calls it directly** — every other page in the EVG gallery is drawn ahead of time and published as a file, which proves the API built a chart *once, on a build machine, in Node*, and says nothing about whether the thing that drew it still runs where a reader is. `gallery/vela/tools/vela_chart_web.rgr` compiles the API to a browser bundle that publishes the compiled classes themselves — `VlChart`, `VlChartMark`, `VlDataset` — so the page's **primary language is JavaScript** and `chart.bar().x("region")` in the editor is those classes' own methods with no binding layer in between (the page counts the calls with a `Proxy` and hands the finished chart back to `VelaChartApi.draw`). **Ranger is the second tab**, through a small dispatcher over the same methods, and **the same chart in either language draws the same SVG byte for byte** — which is the whole claim the page makes, so the browser check asserts it for all eight presets rather than assuming it. The rest of the entry describes that dispatcher: `chart.bar().x("region")` calls `VlChart.bar()` and then `VlChartMark.x("region")`, the chart redraws as you edit, and the Vega-Lite those calls built and the Vega it compiles to are on the tabs beside it. Editing the **data** redraws too — the difference between a live page and a picture of one. It is an interpreter over the real methods rather than a second implementation: there is no chart type in that file and no specification is written by hand, so a name the API does not have is refused *by name* (`line 2: a chart has no method 'colour'`, `'x' needs its argument in quotes: region`, `the data has no column called 'profit'` — the last being the API's own check running client-side, because the dataset is there). `npm run showcase:api` opens it in Chromium and checks **through** the page: every preset draws a different chart, an unknown method is refused, editing the data redraws, the inferred column types are shown, the specification and the Vega are both present, and a page error or console error fails the run — **22 checks**. One thing worth knowing for anyone shipping a Ranger bundle to a browser: the compiler writes a `#!/usr/bin/env node` shebang, and a `<script>` is not a shell — left in, the page loads nothing and says nothing.
@@ -2359,7 +3403,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 
 - **A connection window for the database-backed workbook (Ctrl+D)** — until now the only sign of which engine a sheet was talking to was a line in the status bar. The window shows engine, data source and table as editable fields, and under them what was actually negotiated: rows loaded, the key columns that make the sheet writable (or the reason it is read only), what the engine can do for itself (`DBCapabilities.describe()`) and what Ranger had to do instead (`DBSession.lastFallback`). Connecting is the **host's** part, like opening a file picker: **Connect** leaves a request behind (`takeDbRequest()` → `"connect"` with driver, DSN and table) and the host opens the engine and calls `bindDatabase`; `web/serve.mjs` services it with `GridDbLauncher`, and a host that ignores it keeps the sheet it already has. Typing another engine into the field and pressing Enter switches a live workbook — DuckDB to RangerDB and back — which the window smoke now drives through the same events a person sends. Demo rows are only seeded into `:memory:`: pointed at a file, a table that is not there is reported rather than invented
 
-- **Vela has a chart API: marks and channels, called rather than written** — `gallery/vela/src/VlChart.rgr`. A program that wanted a chart used to have to write a specification out as text, which is how `gallery/datagrid` builds its twenty chart types: three hundred lines of string concatenation, quote by escaped quote. The API writes the same Vega-Lite **value** instead, and `toSpec()` hands it to `VlCompile` and `VlRuntime` exactly as pasted text is handed to them — the fluent surface is a writer of specifications and not a second implementation of anything, which is AntV G2's idea and the reason none of this can drift away from the engine. Four things follow from that and from holding the data (`VlDataset`, an ECharts-style value beside the chart rather than inside it): a **view's encoding is inherited by its marks**, so an area and the line on top of it are two marks with one set of axes and one legend, resolved at emit time into a `layer` that states every channel in full; a **channel need not say what it is** — a column of ISO dates is temporal, of numbers quantitative, of anything else nominal, read off the rows (Observable Plot's ergonomics); a **column the data does not have is an error** rather than the empty axis Vega-Lite would draw and not mention; and what the API does not cover is **written out by hand into the same specification**, where the layer that knows refuses it by name (`a bin written with 'step' is not compiled here`) instead of the API keeping its own list of what the layer below supports. Checked three ways: `tests/chart_test.rgr` builds ten charts and compares the **Vega** each compiles to against a hand-written Vega-Lite specification, then runs each one (71 checks, and two matching refusals fail rather than pass); `tools/reference/chart_api.mjs` gives the six charts of `tools/vela_chart.rgr` — a file with no specification text in it — to the **official** Vega-Lite and Vega and compares the ink to a quarter of a pixel (**6 of 6**); and `tests/run_cpp.sh` requires the same 71 checks to pass and the same six charts to come out byte for byte from a `g++` binary with no JavaScript underneath. It also has a page of its own on the published EVG showcase — **Charts, called**, `gallery/evg/showcase/pages/chart_api.tsx`, the only page there that no specification was written for: each chart is printed with the calls that built it, and those lines are read out of the generating tool's own source at the markers around each chart's calls, so the code the page shows and the code that drew the page cannot drift apart (without the source the tool refuses to write the page). Getting code onto an EVG page turned up one thing worth knowing: **JSX text is tokenised as if it were code**, so a double quote in it opens a string and `x("region")` came out as `x(region )` — a line goes on as a string *literal* in an expression container instead, which is the one place the parser keeps a quote. Design, surface and what is still missing (interaction, a host API, composition beyond a layer) in [`gallery/vela/CHART_API.md`](gallery/vela/CHART_API.md). `npm run vela:chart`, `npm run vela:showcase && npm run showcase`
+- **Vela has a chart API: marks and channels, called rather than written** — `gallery/vela/src/VlChart.rgr`. A program that wanted a chart used to have to write a specification out as text, which is how `gallery/datagrid` builds its twenty chart types: three hundred lines of string concatenation, quote by escaped quote. The API writes the same Vega-Lite **value** instead, and `toSpec()` hands it to `VlCompile` and `VlRuntime` exactly as pasted text is handed to them — the fluent surface is a writer of specifications and not a second implementation of anything, which is AntV G2's idea and the reason none of this can drift away from the engine. Four things follow from that and from holding the data (`VlDataset`, an ECharts-style value beside the chart rather than inside it): a **view's encoding is inherited by its marks**, so an area and the line on top of it are two marks with one set of axes and one legend, resolved at emit time into a `layer` that states every channel in full; a **channel need not say what it is** — a column of ISO dates is temporal, of numbers quantitative, of anything else nominal, read off the rows (Observable Plot's ergonomics); a **column the data does not have is an error** rather than the empty axis Vega-Lite would draw and not mention; and what the API does not cover is **written out by hand into the same specification**, where the layer that knows refuses it by name (`a bin written with 'step' is not compiled here`) instead of the API keeping its own list of what the layer below supports. Checked three ways: `tests/chart_test.rgr` builds ten charts and compares the **Vega** each compiles to against a hand-written Vega-Lite specification, then runs each one (71 checks, and two matching refusals fail rather than pass); `tools/reference/chart_api.mjs` gives the six charts of `tools/vela_chart.rgr` — a file with no specification text in it — to the **official** Vega-Lite and Vega and compares the ink to a quarter of a pixel (**6 of 6**); and `tests/run_cpp.sh` requires the same 71 checks to pass and the same six charts to come out byte for byte from a `g++` binary with no JavaScript underneath. It also has a page of its own on the published EVG showcase — **Charts, called**, `lib/evg/showcase/pages/chart_api.tsx`, the only page there that no specification was written for: each chart is printed with the calls that built it, and those lines are read out of the generating tool's own source at the markers around each chart's calls, so the code the page shows and the code that drew the page cannot drift apart (without the source the tool refuses to write the page). Getting code onto an EVG page turned up one thing worth knowing: **JSX text is tokenised as if it were code**, so a double quote in it opens a string and `x("region")` came out as `x(region )` — a line goes on as a string *literal* in an expression container instead, which is the one place the parser keeps a quote. Design, surface and what is still missing (interaction, a host API, composition beyond a layer) in [`gallery/vela/CHART_API.md`](gallery/vela/CHART_API.md). `npm run vela:chart`, `npm run vela:showcase && npm run showcase`
 - **`gallery/rangersql` — a SQL parser, generator and dialect transpiler in Ranger, and RangerDB's SQL front end.** SQLGlot-inspired rather than a port: tokenizer → parser → one common AST → generator, with a `SqlDialect` answering only the questions engines disagree on. The AST is a flat arena addressed by int (`SqlAst.nodes[45]`, not `node.parent.args["expressions"][0]`) because a tree of objects with parent pointers is pleasant on a GC target and painful on Rust, C++ and Swift; a node carries a kind, its text, flags and `(role, child)` pairs. Expressions are precedence climbing — one table of binding powers instead of term/factor/comparison/conjunction — and comments are tokens the parser hands to the node they were written beside, so `SELECT 1 /* c1 */ + 2 /* c2 */, 3 /* c3 */` round-trips exactly. Covers SELECT with joins, CTEs, set operations, subqueries, CASE, CAST, window functions, `IN`/`BETWEEN`/`LIKE`/`IS NULL`, array subscripts and JSON operators, plus INSERT/UPDATE/DELETE. Measured against **SQLGlot's own `tests/fixtures/identity.sql`** (980 statements it regenerates character for character, vendored with attribution): 519 identical, 3 differing, 458 not yet parsed — with the remaining buckets named in the README (DDL is 175 of them) and the identical count asserted as a baseline so a change that quietly parses less fails. Cross-checked against SQLGlot itself by `tools/sqlglot_oracle.py`: of the 522 statements RangerSQL parses, SQLGlot reads 520 of its outputs as the *same query*, the two exceptions being optimizer-hint comment placement. `Sql.transpile` moves a statement between SQLite, Postgres and MySQL (`IFNULL` ↔ `COALESCE`, `LIMIT 10, 20` → `LIMIT 20 OFFSET 10`, `x::INT` → `CAST(x AS INT)`, backtick quoting, no `NULLS LAST` on MySQL). **`gallery/rangerdb/src/SqlFront.rgr`** plans a parsed statement into the `QuerySpec` / `DBMutation` RangerDB already executes, so `capabilities.sqlText` is now true and the contract suite's SQL section runs on RangerDB, SQLite and DuckDB alike (65/65 each, 94 for RangerDB with its engine-internal and front-end tests); the planner refuses rather than guesses, naming what was in the way. The whole library is ordinary Ranger with no host bindings: 12/12 targets compile, and the RangerDB suite including the SQL front end passes identically on JavaScript, Python and native C++
 - **`gallery/rangerdb` — a database API with three engines behind it, and a DataGrid that edits through it.** The interface is a `QuerySpec` (table, columns, filter, sorts, groupBy, aggregates, offset, limit) rather than SQL text, because a `query(sql)`-only API forces every backend to own a SQL parser before it can answer anything — RangerDB would have had to be a SQL implementation before it could be a database, and the grid would be building strings to say "sort by column 3". SQL stays as an escape hatch and `SqlText.rgr` renders a spec into it for the engines that speak it, with every value travelling as a `?` parameter rather than as text. Results cross as `DataChunk`s — column vectors, a chunk at a time — which is what DuckDB's execution format already is, what a virtualised grid page wants and what a chart series is. Backends declare `DBCapabilities` and `DBSession` executes whatever they did not claim over the chunks that came back, so an engine is never asked to pretend. **RangerDB** itself is columnar and chunked: row groups of 1024, a scan that hands out the stored vectors when nothing is deleted, column pruning driven by the spec, streaming aggregation that never materialises the rows it sums, early scan stop for an unsorted `LIMIT`, tombstone deletes, and a whole-table text snapshot. Indexes, joins, a SQL front end, transactions and a WAL are listed as milestones rather than left as hidden gaps. Every call is synchronous on purpose (a spreadsheet repaints in a loop, Ranger has no generics for a `Task<T>`, and `async` is honoured by one class writer), so the asynchronous DuckDB driver is confined to a worker thread with the main thread blocking on `Atomics.wait` and collecting the reply with `receiveMessageOnPort`. One contract suite runs on all of them: `rangerdb` 53/53 + 19 engine-internal tests, `sqlite` (`node:sqlite`) 53/53, `duckdb` (optional `@duckdb/node-api`) 53/53; RangerDB's 72 also pass from the same source on JavaScript, Python and native C++, and the portable half compiles for 12/12 targets. `GridDbSource` makes a sheet out of a query and an `UPDATE` out of an edited cell — read-only without key columns, a refused value restored rather than left on screen, and sorting/filtering that re-runs the query instead of ordering the loaded page — verified over all three engines by `npm run datagrid:db:test` (93/93). **Ctrl+Q opens a SQL box inside the editor**: what is typed is parsed by RangerSQL and planned into the same `QuerySpec` a sheet built in code uses, so a typed `SELECT` is an ordinary editable database sheet (sort, filter, write-back and formulas all keep working); a statement beyond the planner is handed to the engine as text and the sheet says it is read only, and RangerDB — whose SQL is that planner — refuses it with the reason instead. The same thing is the `db.sql` command, so a host drives it over HTTP, and `datagrid:db:window:smoke` opens the box the way a person does (command, text events, Enter). Two bugs in the new code, found by the suite: binding a spec-driven sheet left the previous sheet's raw SQL in place, so the next sheet re-ran the old query; and `RangerDbBackend.lastError` was never cleared on success, so one refused statement made every later query look like a failure. Host backends now report their primary keys (`pragma_table_info` on SQLite, `duckdb_constraints()` on DuckDB), without which a sheet built from a typed query had no address to write an edit back to. `npm run datagrid:db:window` opens the ordinary WebGL editor window on a live database instead of an .xlsx — the host picks DuckDB if it is installed, SQLite if not and RangerDB if there is no host database at all, seeds a demo table when the one it is pointed at is empty, and `--db-dsn` points it at a real file; `npm run datagrid:db:window:smoke` drives that same host with no browser, posting the click/type/Enter events the browser posts and checking the scene it would have drawn. `npm run rangerdb:bench` times the same queries per engine and the README explains which columns are about the engines and which are about the API's row-at-a-time write path
 - **The playground shows shapes, on twelve targets** — the browser bundle always carried every writer the `rgrc` CLI has, but the UI offered three (JavaScript, Kotlin, Swift 6). The target picker now lists **JavaScript/TypeScript, Python, Go, Rust, C++, C#, Java, Kotlin, Swift 6, Dart, PHP and Scala**, each with its own highlighter, and four `shape` / `case` / `group` examples come with it — the closed variant family, exhaustive `match`, methods on a family, and group capabilities — so the point of PLAN_SHAPES.md ("one source, each target's own representation") can be seen by switching the dropdown: a tagged object on JavaScript and Python, a native `enum` on Rust and Swift, an interface on Kotlin and C#, a variant on C++. LLVM is left out because it has no lowering for shapes (`case` over a shape case fails to match argument types), and Swift 3 because the Swift 6 writer supersedes it. Two things the wider target list exposed: **Java output was empty in the playground** — the Java writer leaves the requested output file empty and writes one file per class beside it, and the reader returned that empty exact match rather than the code; it now shows every file that has content, each under its own banner. And **Scala cannot compile `RangerProcess.rgr`** at all (a `for`-loop with `continue`), so the five process examples mark it unsupported and the picker greys it out with the reason on hover instead of dropping compiler errors into the output pane. The example and target are both in the URL now (`?example=shape-value&lang=rust`)
@@ -2539,7 +3583,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 ### Known gaps
 
 - **`@serialize(true)` does not work for `cpp` or `rust`** — not a template gap: `systemclass JSONDataObject` and `JSONArrayObject` declare no C++ or Rust type at all, so these targets have no JSON representation to serialize into. Needs a design decision, not a template
-- Unary minus, `range`, `min`, `abs(int)`, `round`, `pow` and `log` remain unimplemented; see [PLAN_OPERATORS.md](./PLAN_OPERATORS.md) §5
+- Unary minus, `range`, `min`, `abs(int)`, `round`, `pow` and `log` remain unimplemented; see [PLAN_OPERATORS.md](docs/plans/PLAN_OPERATORS.md) §5
 
 ## [3.2.1] - 2026-08-01
 
@@ -2608,9 +3652,9 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 
 - **`prepublishOnly` no longer runs the whole repository suite** — publishing the compiler ran all 56 test files, including the gallery, game-engine and native-toolchain suites. Those need SDL2, `g++`, Cannon and game fixtures that ship with neither the repo nor the package, so `npm publish` failed on the publisher's machine for reasons unrelated to the compiler (missing `SDL2/SDL.h`, `gallery/game_engine/games/ylos/index.tsx` and `physics_race/index.tsx` are absent from the repository entirely). `prepublishOnly` and `.github/workflows/publish.yml` now run `npm run test:publish` — 44 files, 355 tests, ~90s — covering parsing, type checking and code generation for every target backend. `npm test` still runs everything, and `ci.yml` is unchanged.
 
-- **`build:dist` now includes `build:dist:module`** — `dist/api.js` was not rebuilt by the release build, which is how it drifted behind `bin/output.js`
+- **`build:dist` now includes `build:dist:module`** — `dist/api.js` was not rebuilt by the release build, which is how it drifted behind `dist/rgrc.js`
 
-- **`dist/api.js` rebuilt from current sources** — the committed programmatic-API bundle predated several compiler fixes, so `require("ranger-compiler")` shipped older behaviour than the `rgrc` CLI. `scripts/patch-chain-desugar.js` now patches `dist/api.js` as well as `bin/output.js`, and `build:dist:module` runs it after `tsc`
+- **`dist/api.js` rebuilt from current sources** — the committed programmatic-API bundle predated several compiler fixes, so `require("ranger-compiler")` shipped older behaviour than the `rgrc` CLI. `scripts/patch-chain-desugar.js` now patches `dist/api.js` as well as `dist/rgrc.js`, and `build:dist:module` runs it after `tsc`
 
 ## [3.1.1] - 2026-06-23
 
@@ -2641,13 +3685,13 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 
 ### Added
 
-- **`ProcessUiHost` notify suppress** — `beginSuppressUiNotify` / `endSuppressUiNotify` / `isUiNotifySuppressed` for batching parent↔child sync without re-entrant UI notify loops ([PROCESS_UI_NOTIFY.md](PROCESS_UI_NOTIFY.md))
+- **`ProcessUiHost` notify suppress** — `beginSuppressUiNotify` / `endSuppressUiNotify` / `isUiNotifySuppressed` for batching parent↔child sync without re-entrant UI notify loops ([PROCESS_UI_NOTIFY.md](docs/plans/process/PROCESS_UI_NOTIFY.md))
 - **Process view DTO regression fixture** — [tests/fixtures/process_view_dto_assign.rgr](tests/fixtures/process_view_dto_assign.rgr) (cross-class field assignment with method call on RHS)
-- **Docs** — [PROCESS_UI_NOTIFY.md](PROCESS_UI_NOTIFY.md), [PROCESS_UI_VIEW_MODELS.md](PROCESS_UI_VIEW_MODELS.md); README `@process` quick start
+- **Docs** — [PROCESS_UI_NOTIFY.md](docs/plans/process/PROCESS_UI_NOTIFY.md), [PROCESS_UI_VIEW_MODELS.md](legacy/docs/PROCESS_UI_VIEW_MODELS.md); README `@process` quick start
 
 ### Fixed
 
-- **Parser: assignment RHS method calls** — `row.field = this.helper(index)` no longer splits the call into invalid `=` operands ([PROCESS_UI_VIEW_MODELS.md](PROCESS_UI_VIEW_MODELS.md)); fix in [compiler/ng_RangerFlowParser.rgr](compiler/ng_RangerFlowParser.rgr) (`repairAssignMethodCallRhs`)
+- **Parser: assignment RHS method calls** — `row.field = this.helper(index)` no longer splits the call into invalid `=` operands ([PROCESS_UI_VIEW_MODELS.md](legacy/docs/PROCESS_UI_VIEW_MODELS.md)); fix in [compiler/ng_RangerFlowParser.rgr](compiler/ng_RangerFlowParser.rgr) (`repairAssignMethodCallRhs`)
 
 ### Changed
 
@@ -2719,7 +3763,7 @@ engine, Mermaid, Figma, CodeGraph, Rave — and is not in the npm tarball.
 - **Kotlin int/int division** — Casts operands with `.toDouble()` to avoid integer truncation (`compiler/Lang.rgr`)
 - **Kotlin `open fun` warnings** — `open` modifier now only emitted when a class actually has subclasses (`compiler/ng_RangerKotlinClassWriter.rgr`)
 - **TypeScript `instanceof` with structural types** — `typeof` in `case` context no longer emits `instanceof Record<string,any>` for mapped types; collapses to `Object`/`Array` at runtime (`compiler/ng_LiveCompiler.rgr`)
-- **npm package bin path** — Changed from `bin/output.js` to `dist/rgrc.js` so the published package contains a valid binary
+- **npm package bin path** — Changed from `dist/rgrc.js` to `dist/rgrc.js` so the published package contains a valid binary
 
 ### Changed