Data-driven memory model per target: the Next pages in 8 KiB pages/slots, the 128K in 16 KiB banks. New page N, slot S directive maps any 8 KiB page into a slot (including odd pages 16 KiB banking can’t express); bank N, slot S now targets any window, not just $C000.
Paging-aware !test simulator: runs paged code with a live MMU — NEXTREG, the NEXTREG I/O ports ($243B/$253B) and the 128K paging port ($7FFD) remap slots during execution.
Device-variant selection: --ram (or fantasm.toml[assembler] ram) 2mb/1mb/512k range-checks bank/page numbers against the real RAM.
Paging builtins_page, _bank and _slot — the current instruction’s physical 8 KiB page, its 16 KiB bank, and slot index.
NEX generation checks: warn when the output has no code, or the entry point lands in an empty bank.
Online update check: --check-updates reports whether a newer FantASM is available; a throttled notice also shows on the startup banner (disable with FANTASM_NO_UPDATE_CHECK or the update-check build feature).
Fixed
An empty parenthesised operand (e.g. ld a,()) is now a syntax error instead of silently assembling as (0).
SLD output now conforms to the sjasmplus SLD v1 format: L label records replace the deprecated F, the Z device record carries the source file, spurious T records are gone, the non-standard E record is removed, and <page> numbers are banking-correct.
Changed
Test coverage expanded from 304 to 341 tests.
[1.7.4] - 2026-07-17
Fixed
--lsp no longer writes the version banner to stdout, which corrupted the JSON-RPC stream.
_asmpc / _codesize now resolve consistently (_asmpc = current instruction PC, _codesize = live PC).
Out-of-range jr/djnz now errors instead of silently truncating the offset.
!test init_reg/assert_reg rejects non-settable operands ((hl), af') instead of mapping them to A/HL.
Block-graphics glyphs (codes 128–143) are no longer falsely flagged as non-ASCII.
Changed
Large internal maintainability refactor (no behavioural change).
Test coverage expanded from ~206 to 304 tests, including a self-contained byte-encoding oracle for the base Z80 instruction set.
[1.7.3] - 2026-07-15
Added
Rhai host API: define_label, symbol introspection (symbol_exists, constant_names, label_names), and data emission from blocks — emit_byte, emit_word, emit_bytes, emit_string, emit_string_zero (these advance the PC, so labels placed after a block stay correct).
Rhai language: enabled the array/map/blob packages and range iteration (for i in 0..n), making build-time table generation practical.
Documentation: new docs/rhai.md reference covering the entry points, the full ctx host API, sandbox limits, and worked examples.
LSP: context-aware completion and hover for the Rhai host API inside !rhai blocks.
Fixed
!rhai blocks wiped prior output: a block clobbered every byte emitted before it (and peek/poke read stale data) because the script ran against an empty copy of the emitter. Blocks now see and preserve the real output.
Rhai error locations: compile and runtime errors from a block are reported at the offending source line instead of the !rhai directive line.
Changed
Rhai expressions are read-only: mutating assembler state (define_constant, emit_*, poke, …) from a function invoked via rhai(...) in an expression now errors clearly instead of being silently discarded — do such work in a !rhai block.
iz80 vendored in-tree: the Z80 CPU core is now part of the workspace at crates/iz80 (previously a sibling checkout), so building from source needs no separate repository.
[1.7.2] - 2026-03-30
Added
Tracing Features: Implemented compile-time log filtering with release_max_level_warn in Cargo.toml.
LSP Default Logs: Changed the default tracing level to WARN in release mode for both the CLI and LSP server for a cleaner output.
Changed
Documentation: Updated README.md to include references to LSP support, unit testing, and instruction timing.
Assembly Pipeline: Downgraded “assembly_completed_successfully” from INFO to DEBUG to prevent it from appearing in standard release builds.
[1.7.1] - 2026-03-27
Fixed
Expression Parser: Fixed Error [E1018]: Unclosed parentheses when a label name (e.g. word) coincides with a directive mnemonic alias. The token reader now preserves the original source spelling, and the expression parser recovers it to treat such tokens as ConstLabel references rather than directives.
[1.7.0] - 2026-03-25
Added
Rhai Scripting: Full integration of Rhai embedded scripting engine. Supports !rhai { ... } blocks, external scripts (!rhai "file.rhai"), and expression calls (rhai("func", args...)).
Scripting API: Exposed symbols, constants, memory (peeks/pokes), and diagnostics (warn/error) to Rhai with AST caching for performance.
Security Sandboxing: Implemented a sandboxed Rhai engine with operation limits, expression depth caps, and a whitelist of safe packages.
Enhanced Diagnostics: Added fuzzy symbol suggestions, diagnostic hints, and detailed banking/address context to errors and warnings.
Namespacing & Macros: Hierarchical MODULE scoping (gated) and unique, deterministic local label renaming for macro expansion.
Features & Performance: Incremental assembly for LSP, memory overlap detection, and a plugin-style output format registry.
Observability: Structured tracing events and multi-span diagnostics for improved error reporting in CLI and LSP.
Maintenance: Resolved all build warnings and improved feature gating for minimal and full builds.
Changed
Core Architecture: Decoupled core assembler logic from file IO and split it into specialized pass modules.
Optimization: Significantly reduced heap allocations across emission, instruction encoding, and macro handlers.
LSP Improvements: Decoupled core logic from tower_lsp using domain types and added signature help metadata.
Fixed
NEX & SNA Formats: Corrected Next bank mapping/ordering and fixed SNA 48K PC-on-stack regression.
CLI & Core: Fixed -O origin initialization, multi-pass script execution, and symbol reference tracking in read-only evaluations.
[1.6.3] - 2026-02-28
Added
LSP Hover: Integrated instruction timing (T-states) into hover tooltips for all Z80 and Z80N instructions.
LSP Hover: Added support for conditional timing (taken/not taken) and block instruction timing (repeated/final) in tooltips.
Instruction Metadata: Added missing hover metadata for LDI, LDIR, LDD, and LDDR instructions.
Fixed
Assembler Panic: Resolved a crash when encountering duplicate labels or constants defined via -D flags.
Redefinition Error: Fixed an issue where global defines (via -D) would cause an “Attempt to redefine label or constant” error when used with include directives.
LSP: Refined diagnostic mapping and improved logging for the Language Server.
[1.6.2] - 2026-02-28
Added
LSP Features: Full support for go-to-definition, find-references, and hover for all labels and constants.
LSP Features: Integrated workspace symbol search and code completion for instructions, directives, and symbols.
LSP Features: Added signature help for instruction operands and directive parameters.
Instruction Metadata: Embedded comprehensive instruction set reference into the binary for standalone LSP support.
Changed
LSP Performance: Implemented in-memory assembly and ProjectSnapshot state restoration for high-performance, incremental analysis.
LSP Architecture: Introduced a dedicated LSPQuery interface to cleanly separate IDE features from the core assembler.
Diagnostics: Significantly improved project root detection and multi-file diagnostic reporting across complex projects.
[1.6.1] - 2026-02-27
Changed
Directive Handling: Completely redesigned the internal directive processing system using a trait-based DirectiveRegistry for improved extensibility and maintainability.
Internal Refactoring: Migrated core directive logic to a more robust Result-based architecture, providing better error propagation and more accurate diagnostics.
[1.6.0] - 2026-02-26
Added
Z80 Simulator: Integrated iz80 emulator for automated testing.
!test Directive: New block directive for writing unit tests directly in assembly.
Test Commands: Added init_reg, init_mem for setup and assert_reg, assert_mem, assert_cycles for verification.
CLI Test Runner: Added --test flag to execute all !test blocks and report results.
[1.5.0] - 2026-02-26
Added
Instruction Timing: Implemented a comprehensive T-state calculation system for all Z80 and Z80N instructions.
System Variable: Added $tstates (or tstates) variable to expressions, allowing users to query accumulated timing at any point.
Variable Timing: Accurate calculation for conditional jumps (JR, CALL, RET), block instructions (LDIR, CPIR, etc.), and NEXTREG.
Accurate Nextreg Timing: NEXTREG n, n' is recorded as 20 T-states, while NEXTREG n, A is 17 T-states.
[1.4.3] - 2026-02-26
Added
CLI Improvement: Added explicit build subcommand (e.g., fantasm build main.asm). The previous behavior of running fantasm main.asm still works as the default.
[1.4.2] - 2026-02-26
Changed
CLI Improvement: Significantly improved the usage and help output, including detailed descriptions of all options and subcommands.
CLI Improvement: Enhanced init subcommand help with better parameter descriptions and metavars.
[1.4.1] - 2026-02-26
Added
CLI Improvement: Running fantasm with no parameters now displays help text instead of attempting to build or showing an error.
[1.4.0] - 2026-02-26
Added
Project Initialization: Added fantasm init command for scaffolding new Z80/ZX Next projects.
Interactive Scaffolding: Support for interactive prompts with cursor key navigation (via dialoguer) to set project name, target, and format.
Safety: Added overwrite protection and -f/--force flag for project initialization.
[1.3.6] - 2026-02-26
Changed
Documentation Overhaul: Reorganized and cross-referenced all documentation.
Entry Point: Completely rewritten docs/index.md as a central documentation hub.
Diagnostics: Renamed docs/ASSEMBLER_OUTPUT.md to docs/diagnostics.md and added back-references.
Instructions: Consolidated docs/z80n.md and docs/Z80_INSTRUCTIONS.md into a unified docs/instructions.md.
README: Streamlined README.md to focus on quick start and direct links to the new documentation structure.
[1.3.5] - 2026-02-26
Changed
Internal Refactoring: Consolidated all output format handling (NEX, SNA, SLD, Intel HEX, Binary) into the formats module.
Assembler Cleanup: Simplified the main Assembler struct by moving format-specific configurations and evaluation logic into dedicated modules.
Modularization: Moved ForwardReference, IfBlock, and TokenReader to dedicated modules to improve codebase maintainability.
[1.3.4] - 2026-02-25
Changed
Diagnostic System: Enhanced visibility and color-coding for diagnostics. Progress messages now use the Info level, and !message directives use a dedicated Message level.
Shebang Support: The assembler now correctly detects and ignores shell shebang lines at the start of source files.
Documentation: Renamed and updated docs/ASSEMBLER_OUTPUT.md to docs/diagnostics.md. Added docs/instructions.md with a full instruction set reference.
Fixed
Corrected line numbering when source files contain a shebang.
Improved accuracy of diagnostic error codes across all parsing stages.
[1.3.3] - 2026-02-25
Added
Directives: New !target and !format directives to set machine targets and output formats within the source.
NEX v1.3: Added support for CRC-32C checksums, automatic RAM detection, and entry bank configuration.
SLD Improvements: Upgraded Source Level Debugging to a 10-field format with better position tracking and macro support.
Changed
Format Refactoring: Modularized all output handlers into the formats module.
Optimization: NEX files now only include banks containing data or explicitly requested, reducing file size.
ZX Spectrum Support: Expanded character mapping for block graphics and special symbols.
Fixed
Fixed bug where !format and !target failed when using reserved keywords.
Automatic output extension synchronization based on the selected format.
Resolved missing source line info in second-pass errors.