# Zhex roadmap

Build a readable language from small, composable words. The Go interpreter lets us try the syntax and settle behavior before choosing a compiled implementation.

## Done

The first language milestone runs real programs with checked types and console input and output.

- WebAssembly compiler: `zhex compile` ships with browser and WASI targets, byte-identical to the interpreter across the examples corpus (#7).

- Numbers: `Int` widened to signed 128-bit — literals, arithmetic, comparisons, parsing, printing, JSON and XML integers, and map keys all carry the new width, with overflow a language error at the 128-bit bounds; `zhex compile` builds keep 64-bit Ints and fence wider values (#167).
- Interpreter: typed words, inferred locals, conditions, bounded loops, and checked flows. Mutation words return their receiver — `list.append`, `array.resize`, `map.remove`, `buffer.add-line`, and `buffer.set-line` return the collection they mutated, making mutation flows chain (#156).
- Working examples: composition, console input, FizzBuzz, Fibonacci, factorial, palindrome checking, a recursive GCD, and a times table.
- Executable specification: tests cover syntax, types, scope, arithmetic boundaries, Unicode, and failure paths.
- Getting started: documentation, a public examples website, just recipes for development, and local highlighting packages for Vim/Neovim, VS Code, and Zed.
- Website: Astro-powered topic documentation and an editorial redesign with a new logo, syntax-highlighted examples, and a published design system with a concept archive.
- Licensing: the repository is public and published under the MIT license.
- Editors: syntax highlighting for Vim/Neovim, VS Code, and Zed, with installation and usage documented on the website's docs page.
- Agents: AGENTS.md, an llms.txt site index, and agent-readable examples make Zhex easy for humans to review and AI agents to write.
- Errors: built-in diagnostics point at the source, carry stable cataloged codes, and can report as JSON; user words declare success types and infer a single escaping Result family through `try`, then callers propagate with `try` or recover lazily with `catch`. Multiple uncaught families are rejected; explicit `Result<T, E>` signatures remain supported. Results cannot be silently discarded. Structured Error values expose code, origin, details, and causes; a named reporter can observe explicit handled reports and each unhandled terminal failure without external delivery by default. `console.exit` provides deliberate statuses from 0 to 255; `console.fail` writes a message to stderr and exits with status 1. Both close active `file.stream` loops on termination.
- Input: `read-line`, `text.to-int`, file, buffer, and argument reads return explicit Results. Callers choose a fallback with `catch`, propagate through compatible fallible words with `try`, or let the program boundary report an unhandled failure.
- Insight: `zhex run --trace` streams JSONL step events — word calls, bindings, flow steps, returns — so people and agents can watch a program run; the event vocabulary is documented in llms.txt.
- REPL: `zhex repl` keeps words and values across entries, enters multiline blocks and delimited expressions with editable terminal auto-indentation, four-space Tab and bracketed paste support, echoes expression values, redefines words with a note, lists signatures with `words`, recovers from errors, and traces with `--trace`.
- Vocabulary: rich text work ships — sixteen `text` words, with literal split, join, and prefix/suffix checks added by the first standard-library story (#57), `Buffer` and `File` types, guaranteed-close `file.stream` loops, whole-file reads through `file.read`, checked report output through `file.write` with the first built-in trailing constant default (#58), and program arguments via `console.arg`.
- Vocabulary: collection composition ships — `list.map`, `list.filter`, and `list.fold` run ordinary function-value callbacks (explicit or word-name partials, no lambda syntax) once per element left to right, with fresh outer lists, shared elements, an unchanged source, and the traversal guard held throughout (#60), and `list.find`, `list.any`, and `list.all` short-circuit over the same callback contract, with `find` returning `Option.Some` or `Option.None` (#61); Result-returning callbacks and Result fold accumulators are rejected, and the registered `score-report` example demonstrates all six words.
- Vocabulary: deterministic ordering ships — `list.sort` returns a stable ascending copy of `List<Int>`/`List<String>` values in code-point string order, and `list.sort-by` ranks any list by an Int or String key callback evaluated once per element in source order under the traversal guard (#62); both return fresh outer lists with shared elements and unchanged sources, equal keys keep source order, and the registered `sorting` example demonstrates both words.
- Vocabulary: file inspection ships — `file.list(folder)` returns one level of a folder's bare entry names, dot entries included, as a fresh sorted `List<String>` inside a `Result` under the shared million-element limit, `file.exists(path)` answers existence as a plain `Bool` where a missing path is `false` (postfix `try`/`catch` selects the checked `Result<Bool, FileError>` form), and `file.size(path)` and `file.free-space(path)` report a regular file's bytes and the bytes available on a path's volume inside Results (#73); failures carry the stable codes `file-list`, `file-exists`, `file-size`, and `file-free-space`, and the executable example was deferred until `file.make-folder` made a deterministic one possible.
- Vocabulary: lexical path words ship — `file.join(base, child)` concatenates with the native separator and cleans, with an absolute child replacing the base (`file.join("a/b", "/c")` → `/c`) so untrusted absolute components never nest under a base; `file.base(path)`, `file.extension(path)`, and `file.directory-of(path)` decompose a path into its final element, final-dot suffix (dot included, `.bashrc` for the dotfile), and everything but the final element (#74); all four are pure `String` words with no filesystem access, and the registered `paths` example demonstrates them.
- Vocabulary: destructive file operations ship — `file.make-folder(path, parents = false)` creates one folder level or, with `parents = true`, every missing ancestor while tolerating an existing folder, `file.delete(path)` removes a file or an empty folder and refuses a nonempty one, `file.delete-folder(path, recursive = false)` removes an empty folder or, with a deliberate `recursive = true`, the whole tree best-effort (part may be gone before the first failure), and `file.move(source, target, overwrite = false)` renames files and folders, replaces an existing file only with `overwrite = true`, refuses folder targets in both modes, and fails cross-device moves with the platform's error (#75); the mode arguments are built-in trailing constant defaults, failures carry the stable codes `file-make-folder`, `file-delete`, `file-delete-folder`, and `file-move`, and the registered `file-work` example pays #73's deferred-example debt with a deterministic make-folder → write → list → size → free-space → delete round trip.
- Vocabulary: JSON heterogeneous trees ship — `json.parse(raw)` returns `Result<Json, Error>` over `Json`, a host-predeclared recursive choice (`Null`, `Bool`, `Text`, `Number(literal)`, `List`, `Object`) that programs never declare; trees are ordinary data — constructible, storable in records, matched with plain `match` — while recursion stays host-only (#76). `json.encode` accepts trees: `encode(parse(raw))` preserves key order and number literals byte-for-byte and normalizes whitespace to compact; `Json.Number` literals are validated against the JSON number grammar at encode, strictness (duplicate keys, depth 256, the million-element cap, UTF-8/surrogates, JSON Pointer paths) is shared with `json.decode` with no new codes, and JSON depth 256 plus word-call depth 256 put a recursive word over a maximally deep tree exactly at the call-depth edge. The registered `json-tree` example counts a heterogeneous payload recursively and round-trips it.
- Vocabulary: predicate selection ships — `list.select(values, predicate)` keeps the elements a `(T) -> Bool` predicate accepts, unmodified, and `array.select(values, predicate)` keeps whole rows of a rank-2 array, passing each row to the predicate as a fresh `List<T>` and preserving the rectangle (#70); both follow the #60 callback contract, visit every element or row without short-circuiting, return fresh outer collections with shared elements and unchanged sources, reject Result-returning predicates at check time, and arrays of any rank besides 2 report `array.select requires a rank-2 array` at runtime; the updated `collections` example demonstrates both words.
- Language: indefinite iteration and distinguishable EOF ship — `while condition` repeats an indented body while its `Bool` condition holds, evaluated before each pass; it is a statement of type `Unit`, is rejected as a binding or assignment right-hand side, has no `break`/`continue`, and may run forever by design with no iteration limit, and `read-line` keeps its `Result<String, InputError>` shape while its end-of-input failure carries a `reason` detail of `end-of-file` versus `read-failed` for a read failure, read with `error.detail` (#72); both land as #65's prerequisites, and the registered `collatz` example demonstrates the loop.
- Language: the string-context Int exception ships — `+` concatenates when exactly one operand is `Int` and the other is `String` (the Int renders as `int.to-string` does, chains associate left to right, and two `Int` operands still add numerically), and `print` accepts an `Int` directly (#83); `Bool` and every other type stay strict in these positions, and the no-implicit-conversions law keeps every other position strict.
- Language: the reserved zero-argument `main` entry word ships — a file whose top level has no statements may define `word main`, and `zhex run` and `zhex compile` invoke it as the entry point, with a failing Result inside reporting like a top-level `try` and parameters failing the `main-parameters` code (#134); imports stay words-only, and beside top-level statements, in a module, or in the REPL `main` stays an ordinary word, so one file can both run and be imported by its test (collapsing the AoC day splits is the separate follow-up).
- Vocabulary: typed XML decode ships — `xml.decode(text, defaults)` returns `Result<T, Error>`, schema-directed exactly like `json.decode` over the same supported types on the stdlib encoding/xml tokenizer (#79); attributes map onto record fields verbatim with a collision failing the decode, repeated same-named elements collect into `List<T>`, absent elements use defaults or `Option<T>` (no null marker), text-only elements decode as `String`/exact-integer `Int`/`true`|`false` `Bool`, and strictness rejects unknown elements and attributes, mixed content, namespace-prefixed or `xmlns`-resolved names, DTD/entity declarations, and undefined entities, with predefined and numeric entities decoded and no network ever; limits mirror JSON (depth 256, one million elements) and failures carry `xml-syntax`, `xml-type`, `xml-field`, `xml-range`, and `xml-depth` with element paths. The registered `xml-config` example decodes an embedded service configuration.
- Vocabulary: environment configuration ships — `env.get(name)` answers the process environment as a total `Option<String>` (an unset name is `Option.None`, a set-but-empty name is `Option.Some("")`) and `env.load(path = ".env")` reads KEY=VALUE lines into the environment inside `Result<Unit, Error>`, common-Error family like `json.parse`, with first assignment wins — a key already in the environment, or set by an earlier line of the same file, is never overridden (#64, the environment half; the path words shipped as #74); blank lines and whole-line `#` comments are skipped after leading trim, one matching pair of surrounding single or double quotes on the value is stripped, `KEY=` sets the empty string, a malformed line fails `env-parse` naming the line number and a read failure `env-read` with lines before a malformed one staying applied, the `.env` trailing constant default stays deferred for partials like `file.write`'s `append`, and `env` joins the reserved module names; the registered `env-config` example demonstrates both words.
- Vocabulary: text code points as numbers ship — `text.to-code-points(text)` returns a string's code points (the unit `text.length` already counts) as a fresh `List<Int>` in order and `text.from-code-points(list)` rebuilds text, so character classification becomes ordinary Int arithmetic instead of the slice/`text.to-int`/`try` dance the AoC days carried, the #157 review's top finding (#160); a code point that is not valid Unicode — negative, above U+10FFFF, or a surrogate half — fails the stable `text-code-point` code, and to-code-points past one million elements fails `collection-limit` before materializing; no `Char` type, the values are `Int`s, and no example was registered (the motivating programs are the AoC working areas, and the wasm-subset examples cannot take new host words yet).
- Vocabulary: floored modulo ships — `int.mod-floor(value, modulus)` gives wrap-around-correct modulo where a nonzero result has the modulus's sign, so dials, circular buffers, and grids need no hand-rolled fix-up of `%`'s truncation (the silent-wrong-answer trap 2025 day 1 carried as a permanent helper, #161); `%` keeps its documented truncation toward zero, a zero modulus fails the existing `division-zero` code, and the sign adjustment cannot overflow.
- Vocabulary: map extraction ships — `map.keys(map)` returns a fresh `List<K>` and `map.values(map)` a fresh `List<V>`, both in documented insertion order (the order `for k, v in map` traverses), so a map's data flows into the `list` composition words without a hand loop (2025 day 8's three-line workaround, #162); both hold the one-million-element `collection-limit` before materializing, extraction is a read with no traversal-guard interaction, and String, Int, and Bool keys extract alike. No new codes.
- Vocabulary: list membership ships — `list.contains(values, item)` answers "is this present" in one word over `List<Int>`/`List<String>`, riding `list.sort`'s constrained overloads so the third collection namespace matches `text.contains` and `map.contains` without generic equality (#163); the scan is linear, stops at the first equal element with the traversal guard held, an empty list is `false`, other element types fail at check time with a `list.any`-and-a-predicate hint, and `List<Bool>` stays out (weak demand — the overload set stays closed where `list.sort` drew it). No new codes.
- Vocabulary: positional insert ships — `list.insert(values, index, value)` places a value at the zero-based insertion point, chosen over a comparator sort because `list.sort-by` already ranks by key and the missing primitive was insertion, so rule-based ordering stays a user-side insertion sort (the 2024 day 5 shape, #164); valid indices run `0` through the length inclusive (index == length appends; a strict element-index law would forbid inserting into an empty list), out of range fails the stable `list-range` code at runtime with the family's plain/checked split — plain calls diagnose, `try`/`catch` select `Result<List<T>, Error>` — and the mutation-receiver, iteration-guard, and element-limit rules match `list.append` exactly. No new codes.
- Diagnostics: the mutation-receiver branch-tail trip hints its fix — when an `if` arm ends in a mutation call and the other arm is `Unit`, the stable `branch result types must match` first line gains `hint: <word> returns the <kind> it changed; bind it as `let stored = <word>(...)` or give both branches the same type` (#165, the ergonomics remainder after #156 made every mutation word return its receiver and statement position kept discarding non-Result values); the message, position, and caret are unchanged, plain value mismatches stay hintless, and the rule is written into the contract's branching section and AGENTS.md's hint list.
- Language: with blocks ship — `with <namespace>` directly under a `flow` seed line fixes the seed: every step receives the original seed as its first argument (never the previous step's result), bare step names resolve through the namespace first (`append` under `with list` is `list.append`) and then as ordinary words with the seed, the last step's value is the block's value, and the namespace may be built-in or a used module (#153); the `flow` keyword may be dropped exactly on the expression line above `with` — same indentation, no blank or comment line between — fusing that line (including a `let`/`var`/assignment right-hand side, which then receives the block's value) while a naked expression anywhere else keeps its discarded no-op meaning (#154); a step resolving nowhere fails the new `with-step` code naming both tries, a `Result` seed must be handled first (mirroring `flow`), a Unit seed fails `with-seed` at the first step with a hint naming the seed line, an unfusable `with` line fails `with-location`, `with` joins the reserved keywords, `--trace` emits a `with-step` event per step, the wasm compiler learns no new node kind (a flow cursor that never updates), and the registered `with-blocks` example demonstrates both forms.
- Language: word doc comments ship — a contiguous block of full-line `##` comments at column 1 directly above a `word` declaration becomes that word's doc, with one optional leading space stripped per line, lines joined with newlines, and a blank line or plain `#` comment detaching the block while `##` anywhere else stays a plain comment (#93); `words` prints the doc indented four spaces beneath the signature (a blank doc line renders empty, module words qualified), docs live on the word so a redefinition replaces or clears one without affecting signature compatibility, user words only — records, choices, and built-ins get none — and a REPL comment-only line now joins the next line's entry, so a doc block shares its entry with the word it documents while `words` typed after a comment line still runs.
- Tooling: doctests ship — a doc line of the form `## > expression` is a doctest whose expected output is the doc lines that follow until a blank doc line, the next `## >` line, or the doc's end (a blank line returns the doc to prose; prose directly after an example reads as output and mismatches), and `zhex doctests <file.zhex> [--report=text|json]` compiles the file like a run without executing its body, then checks and evaluates each documented word's examples in the owning module's scope (bare calls resolve inside the module), comparing the REPL echo of the value with the expected lines (#94); a mismatch or an expression that fails to check or evaluate is a diagnostic pointing at the doc line with the stable codes `doctest-mismatch` and `doctest-check` in the catalog and `--report=json`, any failure exits nonzero, a bare `Result` stays rejected so fallible examples use `try`, passing runs print nothing, and plain `zhex run` never executes docs; `just doctests` sweeps every example with one built binary as part of `just test`, seeded on every public word of `examples/modules/math.zhex` (md and html deferred); `zhex test [path]` runs every `*.test.zhex` file as its own process plus every other `.zhex` file's doctests (#97) — per-file PASS/FAIL lines with the captured failure line, a summary (`N files: X passed, Y failed`), exit 1 on any failure, `--report=json` failures in the diagnostic envelope (`test-failed` for a plain failed check), and `--gaps` listing public words referenced by no doctest and no test file — seeded by `examples/modules/math.test.zhex` over the one-word sibling `test` module's `check(condition, label)`, and `just doctests` now runs `bin/zhex test examples`.
- Rich values: explicit binding annotations, nominal records with named constructor arguments and optional field defaults, block-valued bindings, transparent type aliases, and one-parameter choices with exhaustive matching, homogeneous shared `List<T>` and shaped `Array<T>` collections, inferred `Map<K, V>` with built-in `Option<V>` lookup, plain list/array reads and mutations with optional checked forms, insertion-ordered map operations, and collection traversal with bindings and mutation guards. Typed JSON decoding with explicit record defaults and encoding for the supported value subset is also available. Dates, times, durations, instants, and named zones support calendar and elapsed-time operations.
- Text utility: `text-stats` reads a file two ways — whole-buffer counts and a streamed uppercased echo — with program arguments, streamed lines, and guaranteed close, all through the new vocabulary (#28) — and becomes the workload for measurements (#4).
- Measurements: the interpreter runs text-stats at 8-9 ms per pass with stable allocation profiles by mode (docs/measurements.md); readability review recommends a line-filter tool as the next application, with number-to-text ceremony flagged for a future language story.
- Tools: the line-filter tool ships as the first end-to-end application — `zhex run examples/filter.zhex <pattern> <file>` prints matching lines verbatim, streaming the file; wrong arguments fail with a usage line and a missing file reports its natural FileError (#81).
- Modules: `use math` loads sibling files, words are importable unless underscore-private, calls are qualified, cycles and reserved names diagnose with paths, and the REPL adopts modules per session — with a two-file corpus example and docs sections to match.
- Modules: the pure-Zhex `md` Markdown report module ships as a validated sibling module beside a two-file `md-report` example (#77) — fragment-returning words (heading, paragraph, bullet/ordered lists, link, fenced code block, tables added by owner decision), per-position escaping with `max(3, longest run + 1)` fences, percent-encoded link targets that neutralize `javascript:`/`data:` schemes, strict header-width table rows, and verbatim paragraphs; the example composes records and lists into a buffer and prints, with no host words or editor changes.
- Modules: the html composition module ships (#78) — a pure-Zhex sibling module with the guarantee "escaped unless raw": `html.escape-text` pins Go `html.EscapeString` semantics over `&`, `<`, `>`, `'`, `"` (stays in the module; no second workload justified host promotion), `html.attr(name, value)` builds one pre-escaped attribute and `html.element(tag, attributes: List<String>, content)` joins them with text escaping left to `escape-text`, `html.page` emits the doctype document with an escaped title, `html.raw` is the identity bypass documented against every escaping property, and `html.link` allows only relative, `http`, `https`, and `mailto` targets, rejecting every other scheme (including `javascript:` and `data:`) with the `html-url-scheme` code; the registered `modules/html-page` example composes a page and one rejected link.
- Website: in-browser examples ship — the site build compiles the 22 in-subset examples to browser WebAssembly artifacts (about 111 KB raw, 38 KB gzipped each; WebAssembly garbage collection, roughly Chrome 119+, Firefox 120+, and Safari 18.2+), the examples page runs them in the visitor's browser through a small shim, the 14 examples outside the compiler subset stay fenced with notes naming the construct the compiler does not cover yet, and a build-embedded differential gate re-runs every artifact and fails the site build unless each stdout matches the Go interpreter byte-for-byte (#106).
- Website: the Game of Life demo — the compiled example runs in the browser with play, pause, and step over its parsed generations, byte-checked against the interpreter on every build (#90).
- Website: one shared artifact fetch and lazy demo init on the examples page — no double downloads, demos load when scrolled into view (#113).
- Website: the demos move to their own page — a 25 by 25 Game of Life (glider plus toad, blinker, and beacon) runs 54 generations as the first demoSpecs manifest row with its browser artifact and derived verify pins, playback loops with an end-of-run beat and no dead controls, and the examples page links to the page from its top (#115).
- Website: the demos grow to four evolving Game of Life runs — the Gosper glider gun (54 by 54, 120 generations of streaming gliders), the acorn (60 by 60, the methuselah's first 150 generations), and diehard (24 by 24, all 130 generations to its extinction) join the patterns intro, each with its own board, title, and blurb, per-demo verify pins (board size, frame count, stdout size cap, artifact-oracle byte match), and a stage that adapts per board with cells never below 12px (#116).
- Website: the browser playground ships — the full Go interpreter compiles to a WebAssembly engine (`cmd/zhex/engine`, built by `just engine` into `site/public/`) that runs source strings with the interpreter's own diagnostics and holds REPL sessions with the terminal's entry laws; the playground page lazy-loads it behind its cover click, run and REPL modes share a stdin box and caret diagnostics rendered from the report envelope, examples cards open in it with their module maps resolved, share links carry source, input, and mode in the URL fragment, and an interactive read-line seam wakes the paused engine on browser input (#91 engine, #88 playground, #122 seam).
- Advent of Code 2025: all twelve days solved in Zhex under `aoc/2025/` — one main-based file per day (words plus the `main` entry word, #176) with its `*.test.zhex` suite, sample inputs under `samples/` — published as doors on the year-general advent-of-code page (year tabs, honest per-door status labels, per-day outlines from the `aocSpecs` rows, and browser run panels on the compiled days, re-run byte-for-byte against the interpreter by the build's verify-wasm gate); the whole suite runs green with `bin/zhex test aoc` (37 files), and the closing verification sweep re-ran all twelve days clean (12/12 PASS) on a fresh tree (#123 epic).
- Advent of Code 2023 and 2024: the two archive years solved under `aoc/2023/` and `aoc/2024/` — 25 days each in the 2025 idiom (one main-based file per day with its test file, sample inputs only, every part-2 answer carried by two independent community references recorded per day in the findings logs) — published as doors on the advent-of-code page's year tabs with honest statuses (2023 day 25 prints the year's completion star; 2024 day 24 stands at part 1 with its part-2 solver honestly pending as #168); the verification sweeps re-ran every day — 2023's sweep passed 23 of 25 days and its two latent input-shape flags were fixed and regression-pinned (#169 day 10, #170 day 14), 2024's sweep passed all 25 — and the whole three-year suite runs green with `bin/zhex test aoc` (189 files), 61 doors solved in full plus the one honest part-1 door (#136 epic).
- Dogfooding: the bounded REPL front end investigation ships — a Zhex-written driver (`tools/dogfood/repl.zhex`) owns prompts, dispatch, and EOF policy over the per-run `repl.*` seam words, a transcript matrix diffs both binaries across 29 scripted cases plus 350 generated entries with the two accepted divergences pinned, and the design note lives in `docs/repl-dogfood-note.md` (#65); full interpreter self-hosting stays out of scope.
- Language: the three #166 expression-grammar gaps close. Postfix `catch` binds beyond statements (#181) — the one-line fallback also lands on assignment right-hand sides and inside call arguments at expression boundaries (parenthesized, short-form, or grouped), the fallback extending to the argument's boundary, with a trailing ungrouped catch on a short-form call's last argument guarding the whole call exactly as trailing `try` does, while the block handler and lone-name binding stay statement forms. Postfix chains mix indexed and field reads freely (#182) — `space.bytes[i].x` means exactly what naming the intermediate means, field-then-index staying open as before, with the named-intermediate diagnostics unchanged. Arrays gain rank 1 (#183) — one-dimensional tables create, read, write, resize, and iterate like any other rank, rank 0 still fails `array-rank` with `min_rank` 1, `array.select` keeps its rank-2-only rule, and day 19's one-column workaround fell away with byte-identical output.
- Compiler: the native Go target ships — `zhex compile <file.zhex> --target=native` emits a self-contained program directory (readable `main.go`, `go.mod`, the `zhexrt` runtime sources) and builds it with the Go toolchain, or writes the sources with the one `go build` instruction when Go is absent; native keeps the interpreter's full 128-bit Ints, runtime failures render as `zhex run`'s diagnostics through a source-position table, cross-compilation follows GOOS/GOARCH, the corpus differential gate in `just test` holds every in-subset example byte-identical (stdout, stderr, exit status) while generic choices, `json.decode`/`xml.decode`, the temporal words, `file.free-space`, `error.set-reporter`, constructor partials, checked indexed writes, and fallible callbacks fence `not-available-in-build`, and the measured speedup is a 10.6× geometric mean over the interpreter, 3.9–70× per workload (#185, four phases; data on #6).
- WebAssembly: the prelude grows lists and buffers amortized and WASI line I/O is buffered (#187) — list and buffer headers carry a capacity with doubling appends (floor 4) with every len-is-capacity consumer switched, `buffer.to-text` joins in two passes, stdout batches in a 32KB adapter buffer flushed on fill, before stderr, before stdin reads, and at exit, and read-line drains a persistent stdin buffer — so text counts go from 115× slower than the interpreter to 4.6× faster, the 100k-line growth case that did not finish runs in 109 ms, and the factory benchmark's BFS drops from 947 ms to 19 ms (before/after on #6); the residual flow-chain and network losses are the prelude insertion sort and map.put grow-by-one, filed as #188.
- Performance: the cross-language benchmark suite ships under `performance/` — six benchmarks (fibrec, intloop, stringbuild, wordcount, gridsim, filterstream), one file per engine with the same algorithm and byte-verified identical output (Zhex interpreted and native, hand-written Go, C, JavaScript under Node and Bun, Ruby, Python, PHP sources shipped); `run.sh` discovers engines at run time, compares every output before any timing, and reports warm-up + median-of-five wall times with versions pinned and absent engines marked NOT INSTALLED under the fairness law in its README (#190, extending #184; `just perf`, deliberately outside `just test`; the recorded run puts native's geomean with the Node/Bun engines at 48.6 ms and the interpreter 3.5–69× above native).

## Next

Grow the language's reach: a dedicated domain and funding. This is the proposed order; each step needs working examples and tests.

- Standard library: the researched inventory ships — 121 registered words; what remains is small and triaged.
  - The proposals and dependency order live in `docs/standard-library-plan.md` (#30).
  - Open gap tickets in the Inbox: #159 bitwise and stack words, #168 the 2024 day 24 part-2 solver analysis.
- WebAssembly: the A3 WASI runner runs a compiled module under a standalone wasm runtime.
  - `file.*` words work against one preopened directory.
  - It compiles today but stays runtime-untested; `docs/wasm-plan.md` tracks it open.
  - Compiled wasm builds use 64-bit Ints by design — WebAssembly has no wider integer type, and wider values refuse with a named limit (#178 ruled the boundary final); the native Go target keeps the interpreter's full 128-bit width (#185).
- Domain: buy a dedicated domain for the language and point it at the published site.
- Funding: enable GitHub Sponsors or Open Collective and pursue the researched channels (#26).
  - A sponsor section on the site.
  - The grant and visibility channels from the funding research.

## Future

These are directions to explore. Their order and implementation remain open, and there are no delivery dates yet.

- Rich values: generic records and words, and user-defined error types with readable operations and formatting.
- Application libraries: grow through small CLI, HTML-processing, web-server, game, and database experiments.
- Development tools: formatting, language-server support, and published editor packages as the syntax settles.
- Development insight: record-and-replay runs, debug-adapter support, and agent tools, so people and AI agents can see and debug what a program is doing (see docs/diagnostics-plan.md).
- Module growth: exposure lists, import renames, subfolder paths, and computed module constants, composing on the simple use-and-underscore design when each earns its place.
