vanta-lang 0.28.0__tar.gz

vanta_lang-0.28.0/CHANGELOG.md

@@ -0,0 +1,786 @@
+# Changelog
+
+Notable changes to Vanta, newest first. Versions correspond to git tags.
+
+## v0.28.0 — 2026-10-20
+
+- Installable Vanta. `pip install vanta-lang` (or `pipx install vanta-lang`)
+  now installs the `vanta` command without a checkout. A `setup.py` build hook
+  copies `runtime/vanta_runtime.hpp` and the game kit into the wheel as
+  `compiler/runtime/` and `compiler/templates/`, and `MANIFEST.in` keeps the
+  same files in the sdist. The driver resolves either layout, so a checkout and
+  an installed wheel behave the same.
+- `vanta doctor` reports the Python and C++ compiler versions, the resolved
+  runtime header and game kit paths, compiles a one-line runtime probe, and
+  makes a best-effort SDL2 / SDL2_ttf / SDL2_image check. Missing SDL only
+  warns: non-game programs need nothing beyond the C++ compiler.
+- `vanta new` keeps working from an installed wheel because the starter points
+  at the game kit inside the installed compiler.
+- Packaging checks. CI gains a `package` job that builds the wheel and sdist,
+  runs `twine check`, installs the wheel into a fresh venv, and exercises
+  `--version`, `doctor`, a hello program, `new`, `check`, and a headless game
+  run on Linux and Windows. `.github/workflows/release.yml` repeats the smoke
+  test on version tags, attaches the wheel and sdist to the GitHub release, and
+  publishes to PyPI through Trusted Publishing when the `PUBLISH_PYPI`
+  repository variable is set.
+- Metadata is release-ready: SPDX `MIT`, license files, classifiers, project
+  URLs, and `setuptools>=77`. 588 tests total.
+- Docs: README and the tutorial lead with `pipx install vanta-lang`,
+  `vanta doctor`, and the installed-command workflow; the reference gains an
+  installing/running section and the architecture notes describe the build
+  hook and layout resolution.
+
+## v0.27.0 — 2026-10-20
+
+- Breakout polish. `examples/breakout.vnt` now has three walls of 4, 5, and 6
+  rows (125 bricks total), with diagonal gaps in the later walls. Clearing a
+  wall serves the next one; clearing the third wins. The score carries across
+  walls, and the HUD shows the current level and best score.
+- Pause. P or Space freezes the paddle, ball, collisions, and ball animation
+  while events and drawing keep running; a centered `PAUSED` label shows the
+  state. Esc and the close button still quit. `gamekit/sdl.vnt` gains the
+  `KEY_SPACE` and `KEY_P` symbols.
+- Score persistence. The best score is read from `breakout.score` at startup
+  and only rewritten when the run beats it. The optional second program
+  argument changes the score path, so tests and headless runs stay out of the
+  working tree; `breakout.score` is git-ignored.
+- Per-sound gain. `gamekit/audio.vnt` gains
+  `sound_load_gain(audio, path, gain)`: it loads a WAV like `sound_load` and
+  scales every mono S16 sample in place. Gain is clamped to 0..1, so it
+  attenuates without clipping; `sound_load` remains the full-volume shortcut.
+- Floating-point determinism. The driver now passes `-ffp-contract=off` to
+  GCC/Clang (and `/fp:strict` to MSVC), so `f32` expressions are not
+  contracted into fused multiply-adds. The breakout autopilot therefore
+  reaches the same frame 5969 on x86-64 and Apple arm64; without the flag the
+  FMA-capable Mac took 7070 frames.
+- The breakout headless probe now freezes the three-wall clear
+  (`cleared 125 lives 3 level 3 best 125 frames 5969`) and then loads a higher
+  score in a one-frame run to prove it is not overwritten. The sound probe
+  loads a stereo file at half gain and checks the folded samples scale from
+  6000 to 3000, then loads it at gain 2.0 and checks the clamp keeps the
+  original 6000 peak. 586 tests total.
+- Docs: README, tutorial, reference, roadmap, and the kit comments describe
+  levels, pause, persistence, and gain. The frozen pong and strike runs are
+  unchanged; breakout's frozen run deliberately records the new mode.
+
+## v0.26.0 — 2026-10-20
+
+- `str` now owns its storage automatically. It is an immutable,
+  reference-counted value: literals and command-line arguments are zero-copy
+  static views, while `str_concat`, `to_str_i32`, `to_str_f32`, `file_read`,
+  and `StrBuilder.to_str()` return owned buffers. Copies share the buffer and
+  the last copy frees it.
+- The fixed 64 KiB process-lifetime string pool is gone. Long-running string
+  loops no longer exhaust a global limit, `file_read` reads arbitrarily large
+  files (up to the `i32` length limit), and `str_pool_reset()` remains only as
+  a compatibility no-op that invalidates nothing.
+- `file_read` and `file_write` stay byte-exact: embedded NUL bytes are kept in
+  the returned `str`, counted by `str_len`, and written by `file_write`. C
+  functions and `print_str` still see a `const char*` and stop at the first
+  NUL.
+- The C boundary is unchanged for existing code: extern declarations keep
+  `str` as `const char*`, direct calls convert at the call site, and a C
+  function returning `str` has its result copied into an owned value. Small
+  generated adapters let extern functions with `str` signatures be used as
+  `func(str)` values and let Vanta functions/builtins with `str` signatures be
+  passed to C callbacks.
+- `Arena` now constructs and destroys non-trivial element types, and
+  `arena.reset()` runs those destructors. `alloc::<str>`, arrays of `str`, and
+  structs containing `str` therefore work without leaking or double-freeing.
+- 15 new tests (13 net, after replacing the two pool-exhaustion tests): large
+  file reads, pool-free allocation loops, string reset compatibility,
+  builder/arena lifetime, arena string destruction, owned `List<str>`, const
+  strings, embedded NUL round-trips, extern `str` arguments, extern `str`
+  function values, and C callbacks with `str` arguments and returns. 586
+  total.
+- Documentation: the reference, tutorial, architecture notes, README, roadmap,
+  and file-I/O example all describe owned strings; every new snippet was
+  executed with its output frozen.
+
+## v0.25.0 — 2026-10-20
+
+- Checked pointer access: `p.at(i, size)` reads, writes, and compound-assigns
+  through a `ptr<T>` after checking `0 <= i < size`. The pointer has no length
+  of its own, so the caller supplies the accessible count. `ptr<void>` is
+  rejected, nested array elements work
+  (`rows.at(row, row_count).at(column)`), and the new `examples/ptr_at.vnt`
+  demonstrates the read/write paths.
+- An out-of-bounds pointer index stops the program with
+  `vanta: pointer index I out of bounds (size N) at line L`. The raw `p[i]`,
+  `ptr_cast::<T>(p)`, and `ptr_offset(p, n)` escape hatches are unchanged, and
+  `size` remains a programmer promise — null is still `ptr_is_null`'s job.
+- 10 new tests: pointer `at` reads/writes/compound assignment, nested array
+  access, `ptr<void>` rejection, size type checking, the `let`-pointer and
+  temporary-pointer write rules, generated-code shape, the new example, and
+  out-of-bounds read/write failures. 573 total.
+
+## v0.24.1 — 2026-10-20
+
+- `vanta game.vnt` is shorthand for `vanta run game.vnt`: a bare source path
+  now compiles and runs. Installing the checkout once with
+  `python -m pip install -e .` creates the `vanta` command, so games launch
+  without repeating `python main.py` or spelling out link flags.
+- `vanta new game.vnt` writes a playable starter — a paddle, a falling block,
+  three lives, and a frame-limited mode for headless smoke tests. Its imports
+  point at the checkout's game kit relative to the new file.
+- The driver links SDL2, SDL2_ttf, and SDL2_image automatically when it sees
+  their extern block names. Explicit `--link` values still work and are
+  deduplicated; custom C libraries still use `--include-dir`, `--lib-dir`,
+  and `--link`. On Windows the compiler's own `bin` directory is added to the
+  child `PATH`, so the SDL DLLs are found without a manual environment setup.
+- `vanta build --bundle` (Windows) writes `build/<name>/<name>.exe`, walks the
+  executable's PE imports with `objdump`, and copies every non-system DLL it
+  loads — SDL2, SDL2_ttf, SDL2_image, and their codec dependencies — beside
+  the executable. It also copies `examples/assets` and the kit font, so the
+  bundled example games run from a folder with only Windows on `PATH`.
+- Compile failures now print a platform-specific install hint for missing SDL
+  development libraries (MSYS2 package names on Windows, `brew` on macOS, and
+  `apt-get` on Linux), and MSVC users are told why the MinGW import libraries
+  cannot be used.
+- 7 new tests: command normalization, auto-link detection and ordering, custom
+  externs staying unlinked, explicit-link deduplication, starter generation,
+  overwrite protection, and a Windows bundle that runs with a system-only
+  `PATH`. 563 total.
+
+## v0.24.0 — 2026-10-20
+
+- The fourth playable game. `examples/strike.vnt` is a one-screen wave
+  shooter: left/right arrows (or A/D, or a gamepad stick/D-pad) move the
+  ship, the cannon fires on a fixed cadence, and three waves of six saucers
+  descend, drift, and bounce off the walls. A bolt destroys a saucer; a
+  saucer that touches the ship or slips past the bottom costs one of three
+  lives. Clear all eighteen to win. The ship is an animated four-frame
+  strip, the saucers are one white texture tinted per wave, the HUD is
+  `text_draw`, and the shot/hit/boom sounds are WAV files. With no input the
+  autopilot lines up under the lowest saucer and clears the game without
+  losing a life at frame 1020 — the suite freezes those counts. The game
+  imports nine of the ten kit modules (all but `rng.vnt`) and links SDL2,
+  SDL2_ttf, and SDL2_image.
+- `gamekit/collide.vnt`, the tenth module, is pure Vanta with no externs and
+  no SDL dependency: `collide_rects`, `collide_point`, `collide_circles`,
+  and `collide_circle_rect`. Rectangles are `(x, y, w, h)`; edges that only
+  touch are not overlaps, `collide_point` is half-open, and the circle tests
+  compare squared distances, so none of them calls `sqrt`. The pure module
+  gets its own headless test on every machine with a C++ compiler.
+- New generated assets: `ship_anim.png` (four 24x24 frames), `enemy.png`,
+  `laser.png`, and `laser.wav` / `hit.wav` / `boom.wav`, all from
+  `examples/assets/gen_assets.py`.
+- No compiler changes: the kit and the game are plain Vanta. The new tests
+  are the collision semantics and the frozen strike run, for 556 total.
+- Documentation: the game-kit chapters in the tutorial and reference now
+  cover ten modules and collision, the README lists the fourth game and the
+  ten-module kit, and the game-kit README documents the new helpers. Every
+  new snippet was executed with its output frozen.
+
+## v0.23.0 — 2026-10-20
+
+- `extern` functions can return function values. A signature like `func
+  signal(sig: i32, handler: func(i32) -> void) -> func(i32) -> void` now
+  compiles: the generated `extern "C"` declaration folds the declarator into
+  the name (`void(*signal(int32_t, void(*)(int32_t)))(int32_t)`) instead of
+  emitting a bare function type where C needs a name. Returned values are
+  ordinary function values — call them, store them, or hand them back to C.
+  Pointer-to-function returns (`ptr<func(...)>`) and nested function-typed
+  returns (`func() -> func() -> i32`) spell correctly too; an array or list
+  of function values is still rejected as an extern return, since C cannot
+  return those by value. `examples/extern_return.vnt` with
+  `examples/extern_return_lib.c` is the buildable demo: C picks a function,
+  returns null for an unknown id, and the program calls, compares, and
+  null-tests the result.
+- Function-value equality. `==` and `!=` compare function values by address;
+  values of the same type are accepted, different signatures are a compile
+  error, and ordering is rejected with a message pointing at `==`/`!=`. A
+  null built with `ptr_null::<func(...)>()` compares equal to any null of its
+  type, and `ptr_is_null` now accepts function values as well as pointers, so
+  the explicit null test needs no cast or sentinel. Struct equality follows:
+  a function-valued field no longer blocks comparing the whole struct, because
+  the field compares by address like any function value. Still no closures:
+  equality compares plain function pointers.
+- Tests: 11 new cases cover the checker, generated declarations (including
+  nested and pointer-to-function returns), equality emission, struct equality
+  with a function field, and a real C fixture that hands function pointers
+  back across the boundary. 554 total.
+- Docs: the reference's Function values section gains the equality rules and
+  a frozen snippet, its Extern section gains a runnable `signal` example, and
+  the tutorial, README, and version banners follow. Every new snippet is
+  executed with its output frozen; the frozen pong and breakout runs are
+  unchanged.
+
+## v0.22.0 — 2026-10-19
+
+- Sprite animation. `gamekit/anim.vnt` (a ninth module) is a frame clock over
+  `tex_draw_src` for a horizontal strip of equal frames. `anim_new(count, fw,
+  fh, fps)` describes the strip; `anim_tick(anim, dt)` advances the clock by
+  the time the game hands it and *returns* the updated clock — structs are
+  values, so `anim = anim_tick(anim, dt)` is the idiom — the frame wraps, and
+  `anim_draw` blits the current frame through `tex_draw_src`. Nothing reads a
+  wall clock, a dead texture draws nothing, and an empty strip (zero frames)
+  stays on frame 0. The assets script grows `ball_spin.png` (four 10x10
+  frames, a highlight orbiting the ball), and `examples/breakout.vnt` now
+  spins its ball from it with a fixed 1/60 s step. The animation is purely
+  visual: the physics is untouched, and the frozen headless run still prints
+  exactly `cleared 40 lives 3 frames 2064`.
+- Text sprites. `gamekit/text.vnt` gains `TextSprite` — the render-once path
+  for text that redraws every frame. `text_sprite` renders one string into a
+  texture (same colours as `text_draw`, with `text_sprite_ok` as the test and
+  a dead sprite for a failed font or an empty string), `text_sprite_draw`
+  blits it with no TTF call at all, and `text_sprite_free` destroys it;
+  `text_draw` is unchanged. The alternative — a bounded cache keyed by
+  (font, size, string, colour) — was weighed and rejected: the kit has no
+  hidden state to put it in, pool strings can be invalidated under a cache,
+  and an explicit handle is the kit's shape with the same measured win.
+- The measured before/after ships as `examples/text_bench.vnt`: one 24 pt
+  string, both paths, counts stable and milliseconds the machine's. On the
+  development machine (headless dummy driver, software renderer) 40000 draws
+  went from ~130 ms via `text_draw` to ~4 ms via one sprite — about 30x. A
+  smoke test asserts the two output lines' shape and never the numbers, the
+  rule being that timings are never frozen. 3 new tests (543 total).
+- Docs: the tutorial gains an Animated sprites section and the render-once
+  paragraph in Text on screen; the reference's kit chapter lists nine
+  modules, and both READMEs follow. Every new snippet is executed with its
+  output frozen, and the frozen runs of pong and breakout are re-verified
+  unchanged.
+
+## v0.21.0 — 2026-10-19
+
+- Game controllers. `gamekit/gamepad.vnt` (an eighth module) wraps SDL2's
+  `SDL_GameController` API: `pad_open(index)` returns a `Pad`, with `pad_ok`
+  as the test, `pad_attached` for the unplug check, and `pad_button` /
+  `pad_axis` polling the current state. A missing controller — none plugged
+  in, or an index out of range — opens *dead*, the same shape as a dead
+  `Screen`, `Tex`, or `Sound`: every other call is a guarded no-op, so a
+  keyboard-only machine stays playable. `pad_open` starts SDL's refcounted
+  gamecontroller subsystem and `pad_close` stops it, so pads close before
+  `screen_close`'s `SDL_Quit`. Axes stay raw — sticks span -32768..32767
+  with 0 at rest, triggers 0..32767 — and the `PAD_BUTTON_*` / `PAD_AXIS_*`
+  constants name the standard controls, extended share/paddle/touchpad
+  buttons included. This is polling, not events: the event loop stays
+  keyboard-focused.
+- `examples/sdl_gamepad.vnt` (raw C calls, SDL2 core only) opens a controller
+  by index and polls A, d-pad-left, the left stick, and the left trigger;
+  with no controller it reports the dead path and exits cleanly. The two new
+  headless tests open index 9999 — out of range on every machine — so their
+  frozen output is hardware-independent, and the existing games still build
+  without the module. 2 new tests (540 total).
+- The tutorial gains a Gamepads section (dead-handle semantics, raw axis
+  ranges, polling vs events), the reference adds the module to the kit
+  chapter, and both READMEs count eight modules. The new snippets join the
+  frozen-output doc checks.
+
+## v0.20.0 — 2026-10-19
+
+- Sprites. `gamekit/image.vnt` (a seventh module) wraps SDL2_image:
+  `tex_load` decodes a PNG or BMP file into a `Tex` — a handle plus the
+  decoded size; a missing or unreadable file comes back dead, so `tex_ok`
+  is the test. `tex_draw` blits at natural size, `tex_draw_src` blits one
+  rectangle of the texture (sprite-sheet frames), and `tex_draw_ex` rotates
+  by a `f64` angle in degrees and/or flips with the new `SDL_FLIP_*`
+  constants, about the texture's own centre — and none of the three take a
+  scratch rect: SDL copies the rectangles during the call, so the helpers
+  build them on a tiny transient arena. `tex_tint` and `tex_alpha` set a
+  colour and an opacity multiplied into every later draw of that texture.
+  Importing the module means linking SDL2_image; `sdl.vnt` gains
+  `SDL_QueryTexture`, `SDL_RenderCopyEx`, the colour/alpha mods, and
+  `SDL_DestroyTexture` (moved there from `text.vnt`, where it would have
+  collided in the flat namespace).
+- Sound files. `gamekit/audio.vnt` gains `sound_load` / `sound_ok` /
+  `sound_play` / `sound_free`: 16-bit PCM WAV at 44.1 kHz, mono or stereo,
+  decoded by `SDL_LoadWAV_RW` into a buffer SDL allocates. Stereo is folded
+  to mono in place at load, so the `Sound`'s byte count halves; any other
+  rate, sample format, or channel count loads as a dead sound, and playing
+  or freeing one is a no-op — games stay quiet on machines with no device.
+  The game holds the `Sound` across plays and hands the buffer back with
+  `sound_free`.
+- `examples/sdl_texture.vnt` (raw C calls, SDL2_image): loads PNG and BMP
+  files, draws tinted, draws a sheet region flipped, rotates 90 degrees,
+  and checks every draw by reading pixels back from a forced software
+  renderer — exact on every machine, headless included.
+  `examples/sdl_sound.vnt` loads `examples/assets/blip.wav`, prints the
+  file's spec, queues it, and drains the device. The seven assets (three
+  PNGs, one BMP, three WAVs) are generated by the committed
+  `examples/assets/gen_assets.py` — nothing is vendored.
+- `examples/breakout.vnt` is the third playable game and the worked example
+  for both additions: a four-row wall tinted over one white brick texture,
+  a ball and paddle loaded from files, and WAV hits. With no key held the
+  paddle auto-plays, so the headless run is one exact trajectory: it clears
+  all 40 bricks with all three lives intact at frame 2064, and the test suite
+  freezes `cleared 40 lives 3 frames 2064` (the frame cap is only a
+  backstop).
+- CI installs SDL2_image on all three platforms, so the new tests run
+  everywhere; the sprite and sound-file snippets join the frozen-output doc
+  checks. 5 new tests (538 total).
+
+## v0.19.0 — 2026-10-19
+
+- SDL2 audio. `examples/sdl_audio.vnt` plays a synthesized tone through the
+  device's *queue* API — `SDL_OpenAudioDevice` with a hand-built
+  `SDL_AudioSpec` (its `callback` field a true C function-pointer type),
+  `SDL_QueueAudio`, `SDL_PauseAudioDevice`, `SDL_GetQueuedAudioSize` — and
+  `examples/sdl_audio_cb.vnt` puts a Vanta function in the spec's `callback`
+  field instead, so SDL runs it on its audio thread; callback state travels
+  through the `userdata` pointer, as with any C callback. Under SDL's dummy
+  driver both run headless in real time, which is how the tests cover them.
+- `ptr_null::<T>()` builds the null pointer explicitly — the value C APIs ask
+  *for*, where `ptr_is_null` only tests one C hands back. `T` may be a data
+  type (`void` gives the anonymous `ptr<void>`) or a function type, which
+  makes it a null callback: the empty slot a queue-mode `SDL_AudioSpec`
+  carries (`SDL_OpenAudioDevice` also wants NULL, not `""`, for "the default
+  device"). Like the other pointer builtins it takes no arguments; there is
+  still no `nil` literal.
+- The game kit gains `gamekit/audio.vnt` (six modules now): `audio_open` /
+  `audio_ok` / `audio_close`, `audio_play_tone(aud, freq, ms, buf, capacity)`
+  — fills a caller-owned `i16` buffer with a square wave, queues it, and
+  returns the samples queued (0 for a dead device, nonsense values, or an
+  SDL error; a tone longer than the buffer is cut short) — plus
+  `audio_pending` (the bytes still queued) and `audio_wait`. Failure is
+  quiet: with no working device every call does nothing, so games keep
+  running silently. The kit ships no sound files; tones are generated.
+- `examples/pong.vnt` beeps: 880 Hz on a player paddle hit, 660 Hz on an AI
+  hit, and low/high tones on points. The beeps are fire-and-forget, so the
+  headless run is unchanged (`player 0 ai 5 frames 576`).
+- The audio tests need no library beyond SDL2 core, so CI gains no packages;
+  they run under `SDL_AUDIODRIVER=dummy`, whose device paces consumption in
+  real time, so queueing and draining stay deterministic. Examples:
+  `sdl_audio.vnt`, `sdl_audio_cb.vnt`, `gamekit/audio.vnt`. 12 new tests
+  (533 total).
+
+## v0.18.0 — 2026-10-19
+
+- `ptr_offset(p, n)` moves a pointer `n` elements with its element type kept
+  (`p + n` in the generated C++). The offset must be an integer (`i32`;
+  narrow values promote) and may be negative; `ptr<void>` is rejected —
+  `cannot offset a ptr<void> (it has no element size); ptr_cast it to a
+  typed pointer first`. C out-parameters are the motivating case:
+  `TTF_SizeUTF8(font, text, &w, &h)` reaches its second slot with
+  `ptr_offset(scratch, 1)` instead of a second allocation.
+- Text rendering, through SDL_ttf. `examples/sdl_text.vnt` draws with the
+  raw C API — `TTF_Init` / `TTF_OpenFont`, `TTF_SizeUTF8`,
+  `TTF_RenderUTF8_Blended` into a texture, `SDL_RenderCopy` — with
+  `SDL_Color` declared as a Vanta struct of four `u8` channels passed to C
+  by value (the layout was verified against a C mirror).
+- The game kit gains `gamekit/text.vnt`: `font_open` / `font_ok` /
+  `font_close`, `text_measure` (writes width and height into a caller
+  scratch block), `text_draw(screen, font, x, y, text, scratch, r, g, b)`,
+  and `text_quit`. The scratch layout is 10 `i32` slots: `[0] w`, `[1] h`,
+  `[2..5]` source rect, `[6..9]` destination rect — one `arena.alloc`
+  covers measure and draw. A font that failed to open measures 0x0 and
+  draws nothing instead of crashing.
+- `examples/pong.vnt` now draws its score as text (the pip rectangles are
+  gone) and links `SDL2_ttf`; the headless run is unchanged
+  (`player 0 ai 5 frames 576`).
+- The kit ships a font: `examples/gamekit/fonts/tom-thumb.ttf`, a 3x5
+  pixel monospace face (CC0/CC-BY 3.0; credits in `fonts/LICENSE.md`), so
+  examples, docs, and CI depend on no system fonts.
+- CI installs SDL_ttf everywhere (`libsdl2-ttf-dev`, `sdl2_ttf`,
+  `mingw-w64-x86_64-SDL2_ttf`); the SDL_ttf tests skip when it is missing,
+  like the SDL2 tests. Examples: `ptr_offset.vnt`, `sdl_text.vnt`,
+  `gamekit/text.vnt`. 14 new tests (521 total).
+
+## v0.17.0 — 2026-10-18
+
+- Narrow integers: `i8`, `u8`, `i16`, `u16`. They store their exact width —
+  a `u8` field is one byte (`uint8_t` in the generated C++) — and read as
+  `i32` in arithmetic, C's integer promotion. Assigning any integer into a
+  narrow slot keeps the low bits, but a *literal* that does not fit is a
+  compile-time error (`initializer: value 300 out of range for u8`), and the
+  same check covers literals beside a narrow value (`x == 300`). Narrow types
+  work everywhere a type is written: fields, arrays, `ptr<u16>`, `List<u8>`,
+  and `extern` signatures. Pushing to a narrow `List` element type now emits
+  an explicit template argument so wider values still convert.
+- `ptr_cast::<T>(p)` reinterprets a pointer's element type
+  (`reinterpret_cast` semantics, unchecked): view the same memory as another
+  type, or give a `ptr<void>` from C a useful element type again. Any data
+  type is a legal target, `void` included (erasing the type); function-type
+  targets are rejected (`ptr_cast cannot target a function type`).
+- `for x in xs` iterates a `List<T>` or an array element by element. The loop
+  variable is a read-only copy, one per iteration; `break`/`continue` mean the
+  same as in range loops; anything else is a compile error (`cannot iterate
+  over ptr<i32>; for-each supports arrays and Lists`). A list's length is
+  re-read every pass, so do not grow one mid-walk.
+- Struct equality: `==`/`!=` on user structs compare field by field — numbers
+  by value, `str` by content, arrays element-wise, nested structs
+  recursively. A field with no equality (pointer, function value, `List`,
+  `Quat`/`Matrix4`) is a compile error naming the path (`cannot compare struct
+  'Outer' with '==': field 'inner.p' (ptr<i32>) has no equality`). Every
+  comparable struct gets non-member `operator==`/`!=` emitted — all
+  declarations before all definitions, so nesting order does not matter.
+- Enum types may now appear in `extern` signatures (parameters, returns,
+  `ptr<Enum>`, `List<Enum>`); the generated C++ names the fixed-`int32_t`
+  enum and forward-declares it ahead of the `extern "C"` block, so the C side
+  declares `int32_t` or a matching C enum. The old "pass `enum_to_i32(...)`
+  instead" limitation is gone.
+- Examples: `narrow_ints.vnt` plus a C fixture (exact-width parameters and a
+  C mirror struct reading a Vanta struct's bytes for the layout check),
+  `foreach.vnt`, `struct_eq.vnt`, `ptr_cast.vnt`, and `enums_extern.vnt` plus
+  a C fixture. 52 new tests (507 total).
+
+## v0.16.0 — 2026-10-18
+
+- C callbacks: an `extern` parameter typed `func(...)` is now a C function
+  pointer, so C libraries can call back into Vanta code. Pass any function
+  value — a Vanta function or another `extern`. The generated C++ spells the
+  callback inline where it appears (`int32_t(*v_f)(int32_t)` in a
+  declaration, `int32_t(**v_slot)(int32_t)` through a `ptr<func(...)>`), so
+  no aliases are needed before the namespace.
+- An `extern` cannot return a function type yet: the error says so and
+  suggests wrapping the C function in a shim (`extern function 'get' cannot
+  return a function type yet; wrap it in a C shim that calls it`).
+- Codegen fix: struct types in extern signatures are now namespace-qualified
+  and forward-declared ahead of the `extern "C"` block, so
+  `func f(p: ptr<State>)` in an `extern` compiles (previously the bare
+  `State` name was emitted before any declaration).
+- `examples/callbacks.vnt` + `examples/callbacks_lib.c`: a callback C calls
+  twice (`f(f(x))`) and a visitor with a `ptr<i32>` user-data pointer.
+  A libc `atexit` test exercises callbacks on every platform. 8 new tests
+  (455 total).
+
+## v0.15.0 — 2026-10-18
+
+- `List<T>` can be edited in place: `xs.insert(i, v)` inserts at index `i`,
+  shifting the rest right (`i` may be `len(xs)`, the same as `push`), and
+  `xs.remove(i)` removes and returns the element at `i`, shifting the rest
+  left. Out-of-range indexes stop the program with
+  `vanta: insert index I out of bounds (size N) at line L` /
+  `vanta: remove index I out of bounds (size N) at line L`.
+- `xs.sort(cmp)` sorts a list in place with a comparator — a function value
+  `func(T, T) -> i32` returning negative, zero, or positive for less-than,
+  equal, greater-than. It is a stable, `O(n log n)` merge sort: elements the
+  comparator calls equal keep their order.
+- The comparator is fully checked: a missing, wrongly-typed, or wrong-arity
+  comparator is a compile error naming the expected signature, e.g.
+  `'sort' expects a comparator func(i32, i32) -> i32, got func(i32, i32) -> bool`.
+- Codegen fix: function-pointer aliases may now mention structs by value —
+  struct forward declarations are emitted before the aliases — so comparators
+  over `List<Struct>` work.
+- `examples/lists.vnt` now demonstrates insert, remove, and a comparator
+  sort (stable ties included); 17 new tests (447 total).
+
+## v0.14.0 — 2026-10-18
+
+- Added the game kit: `examples/gamekit/` packages the SDL2 plumbing as four
+  importable modules — `sdl.vnt` (`extern` declarations, `EV_*`/`KEY_*`
+  constants, the `Screen` lifecycle), `input.vnt` (event accessors),
+  `gfx.vnt` (clear, filled rect, outline, present), and `rng.vnt` (bounded
+  integers and floats, random signs).
+- `examples/pong.vnt`, the second playable game, is built on the kit: W/S
+  or Up/Down against a tracking AI, wall bounces, contact-point steering,
+  first to 5 wins. `match` picks the serve direction.
+- Pong runs headless like the other SDL examples: a frame-limit argument
+  plus `SDL_VIDEODRIVER=dummy`. The frozen headless run: the AI wins 5-0 in
+  frame 576. `gamekit/rng.vnt` has no SDL dependency, so it gets its own
+  test that runs on every machine with a C++ compiler.
+- No compiler changes: the kit is plain Vanta, and the language needed
+  nothing new — struct fields typed `ptr<void>` (the `Screen` handle), a
+  failure value carried by C's own NULLs instead of a nil literal, and
+  ordinary imports all already worked.
+- 2 new tests (430 total).
+
+## v0.13.0 — 2026-10-18
+
+- Added `match`: branch on an enum value with `Enum.Member:` arms (several
+  members per arm, commas between them) and an optional `else:` fallback.
+  Arms run top to bottom; the first match wins. `examples/match.vnt` walks
+  a little state machine:
+
+  ```vanta
+  match g.state:
+      State.Menu:
+          print_str("fresh start")
+      State.Playing, State.Paused:
+          print_str("in game")
+      else:
+          print_str("somewhere else")
+  ```
+
+- The checker proves coverage: when every member has an arm, no `else` is
+  needed, and a missing member is a compile error that names the members
+  it needs — add a member to an enum later and every match that must
+  handle it says so. A member used by two arms, a member of a different
+  enum, and a misspelled member are errors too.
+- `match` arms have their own scope, and `break`/`continue` inside an arm
+  still control the enclosing loop: `match` is not a loop, and codegen
+  keeps it that way (an if/else chain rather than a C++ `switch`). The
+  matched value is evaluated exactly once.
+- `match` on numbers, strings, or structs is a compile error; it is a
+  statement, not an expression. `match` joins the reserved keywords.
+- 25 new tests (428 total).
+
+## v0.12.0 — 2026-10-18
+
+- SDL2 support, shown end to end. `examples/sdl_window.vnt` opens a window
+  and clears it to a colour; `examples/sdl_game.vnt` is the first playable
+  Vanta game — move the paddle with Left/Right (or A/D) to catch falling
+  coins, Esc or the close button quits. Both are pure `extern`
+  declarations, so no SDL headers are involved at compile time:
+
+  ```powershell
+  python main.py run examples/sdl_game.vnt --lib-dir C:/msys64/mingw64/lib --link SDL2
+  ```
+
+- Pointers widen to `ptr<void>` implicitly, matching C's conversion to
+  `void*`: any `ptr<T>` is accepted where `ptr<void>` is expected, which
+  is how opaque C handles (`SDL_Window`, `SDL_Renderer`, ...) are typed.
+  The narrowing direction stays an error, and a `ptr<void>` cannot be
+  indexed — it has no element type.
+- New builtin `ptr_is_null(p) -> bool`: compares any pointer (including
+  `ptr<void>`) against null so failed calls can be handled. Pointer
+  bindings can be reassigned with `mut`, and user functions may take and
+  return pointers.
+- Fixed: functions returning pointers never compiled — the implicit
+  default return was invalid C++ (`T*{}`); a fallthrough now yields
+  `nullptr`. Same bug class as the v0.11.0 `str` fix.
+- Both SDL examples take an optional frame-limit argument and run headless
+  under `SDL_VIDEODRIVER=dummy`, so the test suite builds, links, and runs
+  them for real; CI installs SDL2 on Linux, macOS, and Windows. 20 new
+  tests (403 total).
+
+## v0.11.0 — 2026-10-18
+
+- Added enums: `enum Name:` declares a fixed set of named members, numbered
+  from 0 in declaration order and written `Name.Member` (e.g.
+  `State.Playing`). An enum is a first-class type — variables, struct
+  fields, function parameters and returns, arrays, `List<T>`, function
+  values, and imported modules all accept enum values unchanged.
+- Values compare with `==` and `!=`. Ordering comparisons on enums, and
+  compares between different enums or against numbers, are compile errors.
+  `enum_to_i32(v)` returns a member's number for printing, arithmetic, or
+  passing to an `extern` function (extern signatures cannot take enum types
+  directly yet). Enum values cannot be constructed (`State(1)` is an error),
+  and enum types have no fields — `s.Menu` suggests `State.Menu`.
+- Fixed: functions returning `str` never compiled — the implicit default
+  return that codegen appends was invalid C++ (`return const char*{};`).
+  A function that falls through now yields the empty string.
+- Fixed: a type declared after a function of the same name (`func P()` then
+  `struct P:`) is now reported as a collision instead of silently shadowing
+  the function.
+- New example `examples/enums.vnt`: a tiny state machine switching on a
+  `State` enum, plus `enum_to_i32` and iteration over an array of members;
+  plus 42 tests (383 total).
+
+## v0.10.0 — 2026-10-18
+
+- Added `StrBuilder`, an arena-backed string builder: `arena.str_builder()`
+  creates one growing buffer, `append_str` / `append_i32` / `append_u32` /
+  `append_f32` / `append_f64` / `append_bool` append (formatted exactly like
+  the matching `print_*`), `len(b)` reads the byte count, `clear()` resets it
+  for reuse, and `to_str()` returns the current contents as a `str` — copied
+  into a fresh arena block, so the result stays stable across later appends,
+  growth, and `clear()`. Growth doubles from 32 bytes, and the fixed string
+  pool is never touched.
+- Like `List<T>`, a builder is a handle: copies alias the same buffer, appends
+  work through a plain `let`, and helpers can take a `StrBuilder` parameter
+  and append to the caller's builder. `arena.reset()` invalidates the builder
+  and the strings taken from it.
+- New example `examples/str_builder.vnt`: building a line once, reusing the
+  buffer with `clear()`, and a helper that appends through its parameter;
+  plus 28 tests (341 total).
+
+## v0.9.0 — 2026-10-18
+
+- Added dynamic lists: `List<T>`, a growable array backed by an `Arena`.
+  `arena.list::<T>()` creates an empty list, `xs.push(v)` appends (growing by
+  doubling from a capacity of 4), `xs.pop()` removes the last element, and
+  `len(xs)` reads the size. Element access reuses the v0.7.0 checked
+  `xs.at(i)` — reads and writes, with out-of-bounds errors naming the list
+  size and source line — plus the unchecked `xs[i]` form.
+- A list is a handle: copies alias the same storage, and passing one to a
+  function lets the function append to the caller's list. Since a list is an
+  indirection like `ptr<T>`, element writes and `push`/`pop` work through a
+  plain `let`; `mut` only controls rebinding. `List<void>` and `List<Arena>`
+  are compile errors, and `arena.reset()` invalidates the arena's lists.
+- New example `examples/lists.vnt`: particles in a list, integrated through a
+  function call, with checked reads and writes and a pop; plus 39 tests
+  (313 total).
+
+## v0.8.0 — 2026-10-18
+
+- Added trigonometry: `sin`, `cos`, and `tan` for `f32` and `f64`, plus
+  `atan2_f32`/`atan2_f64` — the angle of the vector `(x, y)`, the usual
+  "heading toward a point" operation. Angles are radians, and the f32/f64
+  pairs follow the existing `sqrt_f32`/`sqrt_f64` naming. They are callable
+  like any builtin and usable as function values.
+- Extended `examples/arrays_and_math.vnt` with a 45-degree unit vector and
+  its heading recovered through `atan2`, plus 7 tests (274 total).
+
+## v0.7.0 — 2026-10-18
+
+- Added bounds-checked array access: `xs.at(i)` checks the index against the
+  fixed size of `xs` before touching memory. Reads return the element, and
+  writes (`xs.at(i) = v`, including compound forms) obey the normal mutability
+  rules. An out-of-range or negative index prints
+  `vanta: index I out of bounds (size N) at line L` to stderr and exits 1.
+  Plain `xs[i]` stays unchecked.
+- `at` composes with nested arrays — `g.at(y).at(x)` reads and
+  `g.at(y).at(x) = v` writes — and rejects `ptr<T>` receivers with "a pointer
+  has no length", since pointers have no size to check against.
+- Codegen emits `vanta::at_checked` for reads and `vanta::at_checked_ref` (a
+  real reference, so writes land in the array) for writes, carrying the
+  access's source line into the failure message.
+- Added `examples/bounds.vnt`, plus 29 tests (267 total).
+
+## v0.6.0 — 2026-10-18
+
+- Functions are first-class values. A `func(P1, P2) -> R` type names any
+  function with that signature (omit the arrow for `void`), and values can be
+  stored in variables, passed as arguments, returned, kept in struct fields and
+  arrays, or allocated from an arena. The same call syntax invokes them:
+  `f(x)`, `handlers[0](x)`, `op.run(x)`, `pick()(x)`.
+- Values are plain function pointers — there are no closures, so nothing is
+  captured. Vanta functions (emitted with their `fn_` prefix), `extern`
+  functions, and builtins like `print_str` all work as values.
+- Rejected on purpose: `len`/`print_fmt`/`write_fmt`/`assert` and type names as
+  values, `==`/`!=` on function values, function values in `const`
+  initializers, and function types in `extern` signatures (C callbacks come
+  later).
+- Local bindings now shadow functions of the same name in call position, so
+  the canonical `func apply(f: func(i32) -> i32, ...)` works even when a
+  function named `f` exists.
+- Codegen emits one `using FnPtrN = R(*)(...)` alias per distinct function
+  type, innermost first; type names matching `FnPtr<digits>` are reserved.
+- Added `examples/dispatch.vnt`, plus 51 tests (238 total).
+
+## v0.5.0 — 2026-10-18
+
+- 2D arrays work end to end. Nested array types and literals (`[[i32, 8], 4]`)
+  already parsed, but writes through pointers and struct fields were rejected;
+  assignment targets are now validated by walking the whole storage chain, so
+  arena-backed grids (`arena.alloc::<[i32, 8]>(h)`) and `mut` struct grids are
+  writable at any depth while `let` bindings and parameters stay immutable.
+- Array literals and call argument lists may span lines: the lexer ignores
+  newlines inside `[...]` and `(...)`.
+- Added `examples/grid.vnt`: a stack checkerboard, a struct-held heightmap,
+  and an arena-backed dynamic grid, plus 11 tests (187 total).
+
+## v0.4.0 — 2026-10-18
+
+- Added `import "path.vnt"`. An import merges another file's declarations
+  into the program: paths resolve relative to the importing file, imports are
+  transitive, and each file is loaded once, so diamonds are fine. Import
+  cycles and missing files are compile errors. Declarations merge into the
+  existing flat namespace — imported functions, structs, constants, and
+  externs are used by their bare names. `import` is now a reserved word.
+- Errors inside imported files now name the file that contains them: every
+  AST position carries its source file, and `CheckError` prefers it.
+- Added `examples/imports_demo.vnt` with its module
+  `examples/imports_demo_lib.vnt`, plus 12 tests (176 total).
+- New `compiler/loader.py` owns import expansion; `_frontend_only` now goes
+  through it.
+
+## v0.3.1 — 2026-10-18
+
+- Added `file_exists(path)`, `file_write(path, data)`, and `file_read(path)`.
+  `file_read` allocates from the string pool (valid until `str_pool_reset()`)
+  and returns `""` on any failure; a file too large for the pool fails loudly
+  with a specific message instead of truncating. `file_write` returns the byte
+  count or `-1` on failure.
+- Added `examples/file_io.vnt`: reads a file named on the command line and
+  writes a copy to `<path>.copy`, reporting both byte counts.
+
+## v0.3.0 — 2026-10-18
+
+- Added `extern "lib" { ... }` declarations. Extern functions are declared
+  without bodies, type-checked like any other function, and called under their
+  original names; the generated C++ puts them in an `extern "C" {}` block
+  outside `namespace vanta_user`, so the linker sees unmangled symbols.
+- Added `--include-dir`, `--lib-dir`, and `--link` (all repeatable) to `build`
+  and `run`: `-I`/`-L`/`-l` on GCC-style toolchains, `/I`/`/LIBPATH:`/`<lib>.lib`
+  on MSVC.
+- Added `examples/extern_demo.vnt` with its C side in
+  `examples/extern_demo_lib.c`, plus an end-to-end integration test that
+  compiles the C library, links it, and checks the output.
+- Repository history: the tags v0.1.1 through v0.2.5 were re-cut so that each
+  tagged commit reports its own version from `--version`; the stored version
+  string had lagged the tags before v0.2.2's sync and again until v0.2.6.
+
+## v0.2.6 — 2026-10-18
+
+- Added `print_fmt(fmt, args...)` and `write_fmt(fmt, args...)`. Placeholders are
+  `{}` and are resolved at compile time: the type checker counts them and checks
+  each argument's type, and the code generator turns each one into the matching
+  printf conversion. A literal/integer mismatched format is a compile error, not
+  a runtime surprise.
+- Format literals support `{{` and `}}` for literal braces, and `%` is escaped
+  automatically so a stray percent cannot corrupt the output.
+- Added a process-lifetime string pool with `str_concat`, `str_len`,
+  `to_str_i32`, `to_str_f32`, `to_str_bool`, and `str_pool_reset`. Exhaustion
+  fails loudly rather than corrupting memory.
+- Added `str_to_i32` and `str_to_f32`, without which command-line arguments
+  could not be used as numbers.
+- Added `examples/report.vnt`.
+- New `compiler/formats.py` holds the format parser shared by the checker and
+  the code generator.
+
+## v0.2.5 — 2026-10-18
+
+- Added `arg_count()` and `arg_str(i)`; the generated `main` now receives
+  `argc`/`argv` and hands them to the runtime
+- `python main.py run prog.vnt a b` now passes `a b` through to the program
+
+## v0.2.4 — 2026-10-18
+
+- Added `examples/life.vnt` — Conway's Game of Life on a 40x20 torus, drawn as a
+  character grid
+
+## v0.2.3 — 2026-10-18
+
+- Added `write_i32`, `write_u32`, `write_f32`, `write_f64`, `write_bool`, and
+  `write_str` — like their `print_*` counterparts but with no trailing newline
+- Registered `print_newline()`, which had been sitting unreachable in the runtime
+- Added `abs_i32`, `abs_f32`, `min_i32`, `max_i32`, `min_f32`, `max_f32`,
+  `floor_f32`, `ceil_f32`
+
+## v0.2.2 — 2026-10-18
+
+- Added `rand_f32()` — xorshift32, returns `f32` in `[0, 1)`
+- Added `rand_seed(seed: i32)` to select a random stream
+- Random state is fixed at startup, so programs are reproducible until seeded
+- Added 7 tests (type checker, codegen, and an end-to-end determinism test)
+- Fixed: `compiler.VERSION` still reported `0.1.0` and the generated C++ header
+  hardcoded `0.2.0`. Both now report `0.2.2`, and the header reads the shared
+  `VERSION` constant instead of a literal, so it cannot drift again.
+
+## v0.2.1 — 2026-10-17
+
+- Added `examples/boids.vnt` — 30 boids on a 100x100 torus, deterministic init
+- Added an end-to-end integration test asserting the four quadrant counts sum
+  to 30, so the simulation cannot silently stop placing every boid
+
+## v0.2.0 — 2026-10-17
+
+- Added the `str` type, with escape sequences `\t`, `\n`, `\"`, `\\`
+- Added `print_str`
+- `==` and `!=` on `str` compare contents via `strcmp`, not pointers
+- Added `Vec2.normalized` and `Quat.dot`
+- Added `translation`, `scale`, and `from_quat` builtins returning `Matrix4`
+
+## v0.1.3 — 2026-10-17
+
+- Added fixed-size arrays: `[T, N]` types, array literals, indexing, and `len(xs)`
+- Added Quat math: `Quat * Quat`, `Quat * Vec3`
+- Added Matrix4 extras: `Matrix4 * Matrix4`, `Matrix4 * Vec3`
+- Documented `examples/arrays_and_math.vnt`
+
+## v0.1.2 — 2026-10-17
+
+- Added `const` declarations (compile-time values, emitted as C++ `constexpr`)
+- Added `assert(cond)`
+- Added return-type inference when `-> T` is omitted
+- Added 3-argument `range(start, end, step)`
+- Added element-wise `Vec2` / `Vec3` equality and inequality
+- Fixed mixed-literal return-type inference
+
+## v0.1.1 — 2026-10-17
+
+- Added compound assignment `+=`, `-=`, `*=`, `/=`
+- Added `break` and `continue`, with loop-context checking
+- Added `examples/loops.vnt`
+
+## v0.1.0 — 2026-10-17
+
+- Initial working compiler:
+  source → lex → parse → type-check → C++17 → native binary
+- Types: `i32`, `u32`, `f32`, `f64`, `bool`, `void`, `ptr<T>`
+- Structs, `component`, and `system` declarations
+- Non-copyable stack-scoped `Arena` allocator
+- Built-in `Vec2`, `Vec3`, `Matrix4`, `Quat`
+- Examples: `examples/vector_math.vnt`, `examples/physics.vnt`