59 Commits

Author	SHA1	Message	Date
andrew	899476c6dd	Merge branch 'main' into 12	2026-08-06 12:40:18 -04:00
andrew	39a0c60bf3	Merge branch 'main' into 36	2026-08-06 12:38:05 -04:00
Logikoma	fd6521d381	Stop pointer parameters leaking value-pool slots ... Create structure parameters before allocating their representation, then keep pointer references in the call variable's inline slot. Add an 8,000-call regression and document the remaining by-value structure escape limitation. Co-authored-by: andrew <andrew@aklabs.net> Co-authored-by: OpenAI Codex (GPT-5) <noreply@openai.com>	2026-08-06 12:33:31 -04:00
Ishikawa	a29c7f34fe	Fix generator teardown leaks, add RETURN-in-GEN and LOOP conditions on DO EACH ... Review findings and follow-ups from PR #61 review: - runtime_generator.c: akbasic_runtime_release_generator() now releases the forGeneratorEnv of every scope it walks through. Abandoning a generator that was itself suspended inside a FOR EACH over another generator stranded the inner generator's pool slot; a loop doing so exhausted the twelve-slot pool and died far from the cause. - runtime.c/runtime.h: new akbasic_runtime_unwind_to_environment(), the shared teardown for the error unwinds in pump_generator() and call_function() -- both previously bare prev_environment() loops with the same suspended-generator blindness. - runtime_commands.c: bare RETURN standing in a GEN's own frame ends the generator exactly as END GEN does -- a GEN is a function at heart. RETURN with a value there is refused (values leave a GEN only through EMIT). The no-frame error message now says "GOSUB, DEF, or GEN". - runtime_structure.c: LOOP WHILE/UNTIL composes with DO EACH -- checked after each trip with the loop variable still holding that trip's value; a condition that stops the loop abandons the generator exactly as EXIT does. Previously the condition was silently ignored, while the verb reference documented it as working. - parser_commands.c: trailing tokens after the generator call on a FOR EACH/DO EACH line are refused at parse. Previously they sat unparsed and blew up only after the loop completed, when the parent scope resumed the line mid-statement -- an error at the loop's end pointing at its start. - tests/generators.c: pool-exhaustion tests for the nested-abandonment and LOOP-condition paths, RETURN semantics tests, and a direct test of the unwind primitive. Three new golden pairs cover RETURN, LOOP conditions and the misplaced-condition parse error. - docs: RETURN and LOOP-condition semantics in 04-control-flow.md and 11-verb-reference.md; corrected the self-recursion analogy (functions are re-entrant here). TODO.md 1.10 records the generator design decisions the code comments were already citing, plus the zero-arg parameter-list limitation. MAINTENANCE.md gains the abandoned-generators invariant those comments also cited. Co-Authored-By: Andrew Kesterson <andrew@aklabs.net> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-08-06 11:55:59 -04:00
Tachikoma	f7e8d4b82b	Implement generators: GEN, EMIT, END GEN, FOR EACH and DO EACH (issue 57) ... Adds generator support per the plan in issue 57: - environment.h: isGenerator/generatorFn on a GEN call's own environment, isEachLoop and forGeneratorEnv on a FOR EACH/DO EACH loop's own environment. - runtime.c: splits akbasic_runtime_prev_environment() into akbasic_runtime_detach_environment() (return to parent without releasing) and akbasic_runtime_release_environment() (give variables and the pool slot back, on any environment); prev_environment() is now the two in sequence. akbasic_runtime_call_function() refuses to call a GEN like an ordinary function. - verbs.c/verbs.h/scanner: new keywords GEN, EMIT, EACH, IN and the compound verb "END GEN" (built by a new akbasic_parse_end(), the same trick akbasic_parse_print() uses for PRINT #). - parser_commands.c: akbasic_parse_gen() (modelled on multi-line DEF), akbasic_parse_end(), and EACH branches in akbasic_parse_for()/ akbasic_parse_do(). - runtime_generator.c (new): akbasic_cmd_gen, akbasic_cmd_emit, akbasic_cmd_end_gen, and the invoke/pump/release machinery FOR EACH, DO EACH, NEXT and LOOP share. EMIT walks up to the nearest isGenerator ancestor rather than assuming it is standing directly in the GEN's own call frame, because a GEN body may nest its own FOR/DO/GOSUB around an EMIT -- the issue's own ROOMOBJECTS example does exactly that. - runtime_commands.c/runtime_structure.c: EACH branches in cmd_for/cmd_do, matching EACH branches in cmd_next/cmd_loop, and forGeneratorEnv release on every path that can abandon a live generator (EXIT, a NEXT that pops for a mismatched loop variable). Deviates from the plan in one place: FunctionDef gained an isGenerator flag (not in the plan's field list) because refusing a GEN called like a function has to happen before anything is pushed. Relying on EMIT's own isGenerator check for that case doesn't work: akbasic_runtime_call_function() drives its own step loop the same way akbasic_runtime_pump_generator() does, and a BASIC-level error inside that loop is swallowed by process_line_run() as reported-but-not-propagated, so the call would silently "succeed" with a meaningless return value instead of failing. Also: a zero-argument parameter list is not supported by the DEF/GEN parameter parser this reuses (a pre-existing limitation, not generator-specific); every generator in the tests takes at least one parameter as a result. Tests: tests/generators.c (pool exhaustion under repeated EXIT, calling a GEN like a function, EMIT outside a GEN, self-recursion, sibling/nested invocations) and tests/language/flowcontrol/generators_*.bas -- the issue's own ROOMOBJECTS example in both loop shapes, an empty generator, non-numeric EMIT, nested/interleaved invocations, and three error-path golden cases. Docs: control-flow chapter 4 gets a GEN/EMIT/FOR EACH/DO EACH section, the verb reference gets GEN/EMIT/END GEN entries and updated FOR/DO/NEXT/LOOP/EXIT rows, and architecture chapter 14 documents the detach/release split and the two-environment generator invocation. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-06 10:02:43 -04:00
andrew	cdb9be03c6	Merge pull request 'Fix Doxygen gate failures on main' (#60) from 56-doxygen-gate-fixes into main ... Reviewed-on: #60	2026-08-06 08:45:37 -04:00
Tachikoma	809a9bf64d	Fix Doxygen gate failures on main ... Four independent defects that made 'doxygen Doxyfile' exit 1: - runtime.h: a stacked doc block above akbasic_runtime_new_function was left directly above akbasic_runtime_call_function's declaration with no function in between, so Doxygen glommed both blocks onto call_function and duplicated the @param obj/@param dest entries. Moved the block back to sit directly above new_function. - sprite.h/akgl.h/sprite_akgl.c: three #AKGL_*/#AKBASIC_SHAPE_* Doxygen autolinks pointed at libakgl symbols outside this Doxyfile's INPUT, so they could never resolve. Converted them to plain code spans. - scanner.c: peek(), peek_next() and match_next_char() were each missing @param obj (and match_next_char also cm/truetype/falsetype). Filled in the missing entries. - Doxyfile: the error.h include graph hit DOT_GRAPH_MAX_NODES at exactly the default of 50. Raised it to 100. Verified 'doxygen Doxyfile' now exits 0 with graphviz installed. Refs #56 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-05 23:48:07 -04:00
Tachikoma	a15e172c2a	Take libakerror 2.0.2, libakstdlib and libakgl 0.9.0 ... Bumps all three ak* submodules to their current main, applies what their upgrade notes require, and retires the two workarounds they make obsolete. libakerror 2.0.1 -> 2.0.2 (63 commits). Two of its fixes were this repository's own filed issues, and both workarounds are gone: - It namespaces its embedded `coverage` target now, the same CMAKE_SOURCE_DIR test it already applied to `mutation` (its issue #15). The add_custom_target() shadow that renamed it on the way past could only ever fire on a name the dependency has stopped using, so it is deleted rather than left as dead code. - It installs akerrorConfigVersion.cmake at SameMajorVersion (its issue #16). MAINTENANCE.md said to add a `1.0` floor to our find_dependency calls when this landed; the floor is now `2.0`, and we have no find_dependency calls to add it to, so the paragraph says that instead of an instruction nobody can follow. Its IGNORE context also changed shape: `__akerr_last_ignored` was an extern pointer, and is now a per-translation-unit `static akerr_last_ignored` holding a copy, so the pool slot can be released. Nothing here referenced the symbol, but it costs us 1.35 MiB of thread-local storage -- 38 TUs x 37,296 bytes, measured as the entire TLS segment of build/basic, where 2.0.1 produced no TLS segment at all -- plus 84 -Wunused-variable warnings. Filed upstream as libakerror issue #37 and recorded in MAINTENANCE.md rather than patched here, because patching a submodule forks it. libakstdlib gains directory and file-metadata wrappers with no version bump. aksl_snprintf keeps its `int *count` -- an intermediate commit removed it and the merge put it back -- but now reports the required length on truncation rather than 0. Every call site here reads it only after a successful return, so nothing moved. The directory wrappers close the gap DIRECTORY was refused for (libakstdlib issue #10). The verb is still unwritten, so it still refuses, but it no longer blames a wrapper that exists: the message is "DIRECTORY is not implemented yet" and tests/disk_verbs.c asserts both that it says so and that it does not name libakstdlib. What writing it would need is akbasic issue #55. libakgl moves to the current main at 0.9.0. It registers libccd and tg as submodules, so a tree that only ran `git submodule update --init --recursive` before the bump needs it again or the configure fails on a missing libccd/src/ccd/config.h.cmake.in. Verified: 114/114 default, 116/116 under -DAKBASIC_WITH_AKGL=ON, docs_examples green in both. libakerror's UPGRADING.md documents a 2.0.3 that project() never stamped, so the version tables read 2.0.2 -- libakerror issue #38. Co-Authored-By: Andrew Kesterson <andrew@aklabs.net> Co-Authored-By: Claude Code (Claude Opus 5, claude-opus-5[1m]) <noreply@anthropic.com>	2026-08-05 23:26:15 -04:00
Tachikoma	5c58f4c16d	Add native RND and ASC functions ... Implement bounded random integers with lazy clock seeding and add ASC as the inverse of CHR. Cover dispatch, validation, deterministic LCG output, UTF-8 round trips, function reference, and the breakout tutorial. Closes #16. Co-authored-by: andrew <andrew@aklabs.net>	2026-08-05 21:17:47 -04:00
Logikoma	e20fd445a4	Make renumber scratch runtime-owned ... Co-authored-by: Andrew Kesterson <andrew@starfort.tech>	2026-08-05 18:36:08 -04:00
Tachikoma	61e08812e3	Reset scratch per line and unwind dead scopes in host function calls ... akbasic_runtime_call_function()'s body loop drives process_line_run() directly, skipping the per-line prologue akbasic_runtime_step() provides. The call environment's value scratch therefore accumulated across the whole body, and any body past about ten real lines died with 'Maximum values per line reached' -- a limit that is supposed to be per line. The loop now runs the same prologue step() does. A body that died also left its call scopes active: nothing popped them, so a host absorbing script errors drained the twelve-slot environment pool after twelve dead calls. The loop now unwinds to the caller's environment on every exit path. New: akbasic_runtime_clear_error(), the missing half of host revival. A run's first BASIC-level error latches deliberately, and set_mode(RUN) alone cannot un-decide that; a host that absorbed the error calls this beside it. Both defects and the revival dance are pinned in tests/user_functions.c. Co-authored-by: andrew <andrew@aklabs.net> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc	2026-08-04 20:05:41 -04:00
Tachikoma	f9742ed5a5	Cut akbasic_Runtime's static footprint from 10.75 MiB to 2.40 MiB ... Nothing in this interpreter mallocs; every pool is a fixed array sized by an AKBASIC_MAX_* constant, so sizeof(akbasic_Runtime) is a compile-time number and most of it was headroom nobody was using. Measured concurrent-use high-water marks off examples/breakout and examples/megademo -- the two most demanding programs this interpreter runs -- against each pool's ceiling: AKBASIC_MAX_ENVIRONMENTS 32 -> 12 (measured peak concurrency: 6-7) AKBASIC_MAX_FUNCTIONS 64 -> 8 (measured: 0, neither program uses DEF FN) AKBASIC_MAX_ARRAY_VALUES 4096 -> 2048 (measured peak: 1618 slots) AKBASIC_MAX_SOURCE_LINES 9999 -> 2048 (measured: ~1270-1496 non-blank lines) AKBASIC_SYMTAB_MAX_SLOTS 256 -> 172 (no caller ever requests more than 128) AKBASIC_SYMTAB_MAX_KEY 64 -> 24 (longest identifier measured: 11 chars) AKBASIC_MAX_LINE_LENGTH 256 -> 80 (Commodore BASIC's own line limit) AKBASIC_MAX_VARIABLES (128) is untouched on purpose: breakout alone reaches 121 of 128 concurrent named variables, so it has the least slack of any pool measured and is not a shrink candidate. akbasic_Variable.name shrinks from AKBASIC_MAX_STRING_LENGTH (256) to AKBASIC_SYMTAB_MAX_KEY: every variable name is registered with akbasic_symtab_set() right after this field is populated (akbasic_environment_create(), src/environment.c), and that call already refuses anything AKBASIC_SYMTAB_MAX_KEY characters or longer. The wider field was headroom nothing could ever put a byte into. Two defects surfaced while testing the line-length drop against the golden corpus, both fixed here because the 80-byte ceiling makes them routine rather than theoretical: - sourcepath (runtime.h) was borrowing AKBASIC_MAX_LINE_LENGTH by accident. It holds a directory, not a line of BASIC, and this checkout's own test paths are 81+ characters deep -- every golden test failed to load until this split into its own AKBASIC_MAX_SOURCE_PATH_LENGTH, backed by PATH_MAX the way libakerror already sizes its own path buffers. - src/sink_stdio.c's stdio_readline() called aksl_fgets() but never checked its own documented contract: a full buffer with no trailing newline means the line was longer than the buffer, and the unread remainder is still in the stream. Unchecked, the next readline() picks that remainder up as its own statement -- a real line silently becomes two wrong ones instead of a clean AKBASIC_ERR_BOUNDS refusal. At 256 bytes this was theoretical; at 80 it is not, so it now refuses loudly. tests/value_pool.c's test_pool_is_untouched_by_scopes() was pinned to the old 4x1024=4096 pool math (four max-size arrays proving nothing leaked); rewritten to 2x1024=2048 for the same proof against the new AKBASIC_MAX_ARRAY_VALUES. Known consequence, tracked in andrew/akbasic#32 rather than worked around here: two files in the protected tests/reference/ corpus (language/functions/mod.bas, language/flowcontrol/nestedforloopwaitingfor command.bas) have 82-character lines and cannot be shortened -- MAINTENANCE.md and CMakeLists.txt:585 are explicit that tests/reference/ is never edited to suit this interpreter. Twelve tests/language/ cases and one docs/18 line are in the same position but are this project's own content. Shipping 80 anyway, with the fallout tracked rather than hidden, was an explicit call on this PR rather than something decided here. Verified: cmake --build build-akgl && ctest --test-dir build-akgl, 97/112 (15 known failures, all AKBASIC_MAX_LINE_LENGTH-related, filed as #32). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-04 20:05:41 -04:00
Tachikoma	b434be1901	Port onto libakstdlib 2b79aca and convert the eight bool predicates ... akbasic's src/ now calls libakstdlib 313 times and raw libc 7 -- 2.2% bypassed, against 86.4% on the same tree before this. The submodule bump 669b2b3 -> 2b79aca needed no source change of its own: the release is drop-in for what akbasic already used. Seven of the eight sites the earlier port left on raw libc change their own signature rather than swallowing an error, per andrew's ruling on libakstdlib#38. word_is, the is_waiting_for pair, the scanner's is_at_end, peek, peek_next and match_next_char, format.c's overflow, and sink_akgl's scroll/newline/putchar_at/echo_line/edit_key chain all return an akerr_ErrorContext * and hand the answer back through an out parameter. is_waiting_for and is_waiting_for_any are a public header change; every call site that used one as a term in a condition hoists it into a statement first. verb_compare is the eighth and stays on strcmp. bsearch(3) fixes the comparator's signature, so there is no out parameter to report through -- which is what libakstdlib#38 concluded. It carries a comment saying so and saying why the bypass is safe there. Six snprintf sites stay raw because they want truncation as an answer rather than an error, and aksl_snprintf cannot express that until libakstdlib#34 hands the required length back. Each of the six says so at the site. Two of them, in host.c, are a latent defect rather than a decision: a host type name over 31 characters truncates silently and two sharing a prefix then collide, where structtype.c refuses the same case. DLOAD leaked a file descriptor. Its read loop sat inside an ATTEMPT and the PASS in it returned past CLEANUP, so a scan error left the file open. Hoisting the loop into its own helper to convert fgets fixes it. Refs libakstdlib#26, libakstdlib#38 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-03 21:23:32 -04:00
Tachikoma	3342f2b569	Make GRAPHIC select the text plane ... Co-authored-by: Andrew Kesterson <andrew@aklabs.net>	2026-08-03 08:08:34 -04:00
Tachikoma	c5d13f00f6	Repoint the TODO.md citations that no longer resolve ... Its own SS0-SS9 structure survived the move to the tracker, so 133 citations still resolve and are left alone. Thirteen did not. Six named another repository's TODO.md by a section number: libakstdlib 1.6, 2.2.2 and 2.3, and libakgl's file. Those repositories dropped their numbering entirely, so each now names UPGRADING.md, an issue, or the tracker. Three cited 'TODO.md section 12', which has never existed here -- the defect list is SS6. TODO.md itself caught two others of that class earlier. The CMakeLists comment carried a stale premise with it: eleven defects 'deliberately reproduced and not yet fixed' stopped being the rule when SS0.1 retired the fidelity constraint. Four told a reader to record work in TODO.md; the scanner defect is issue #4, the audio_tables mutation gap is #25, and the UI gaps are libakgl #79 and #80. Verified: cmake --build build && ctest --test-dir build, 112/112. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 22:01:28 -04:00
Tachikoma	3b32a682a1	Give BASIC menus, dialogs and HUD labels over libakgl's UI helpers ... Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that wanted a title screen had to draw one out of CHAR and GETKEY, which is what both breakout tutorials make a reader do. The interesting part is the impedance mismatch. libakgl's UI is immediate mode -- widgets are re-declared inside a frame bracket every frame and clay borrows their text until the bracket closes -- and a BASIC program says MENU 1, "START" on line 100 and expects it up on line 900, several hundred frames later. So src/ui_akgl.c is retained on this side and immediate on that one: the record's entry points are setters that copy into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set once a frame from the host's pump. No BASIC string, which lives in the per-line value pool, is ever what clay is handed. The shapes are borrowed rather than invented. MENU retires the way SOLID does -- no entries retires one, no arguments retire them all. GETMENU holds the step loop the way GETKEY does, so parking is not blocking: the step still returns, the host keeps its frame rate, and the sprite, audio and collision services keep running underneath because they run before the blocking checks. RMENU(n,1) reads and clears the way BUMP() does. Withdrawing the device or retiring the menu releases a holding GETMENU with 0 rather than wedging the script, which is akbasic_input_service()'s rule for a withdrawn keyboard. One thing a program has to know, and docs/19-user-interface.md says it twice: a menu that is up owns the cursor keys and Return. It has to, and retiring it gives them back -- forget the MENU n before an INPUT and the INPUT never sees the Return that ends it. akbasic_runtime_set_ui() is its own function rather than a fifth argument to akbasic_runtime_set_devices(), whose signature has twenty-eight call sites in tests and documentation that are about something else. deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead centre, so HUD offers exactly those five; TODO.md records what a top-centre and bottom-centre would cost upstream, along with the three other things this deliberately leaves out. No new error code either -- DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free. tools/screenshot.c had to learn that "needs a font" and "draws the text grid" are two questions. They were one, and a UI figure came out black: the text layer owns every pixel of the rows it covers and painted over the widgets. The new ui=1 fence attribute asks for the first without the second; MAINTENANCE.md documents it. 112/112 in both configurations, 112/112 under ASan and UBSan, coverage 94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and 100% of functions, doxygen clean, and the four new figures byte-identical on a re-render. TODO.md section 8's gate table was stale on several counts besides these and is refreshed with measured numbers. Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 18:37:10 -04:00
Tachikoma	5061419768	Take libakgl 0.9.0, and shadow set_property(TEST) so it configures ... 0.9.0 is the akgl_ui subsystem: a vendored clay, an arena, menus, HUDs and dialogs, reached through a new akgl/ui.h this project does not include. Every header the akbasic_akgl target actually compiles against is byte-identical to 0.8.0, so unlike the 0.8.0 bump there is no sizeof to get wrong. The floor in include/akbasic/akgl.h moves to 0.9.0 anyway, on the standing rule that the soname carries MAJOR.MINOR while the major is 0. It does not configure as it stands. 0.9.0 moved eight test property calls off set_tests_properties -- correctly, because that command splits a semicolon-separated value and had been silently reducing its LD_LIBRARY_PATH prepend list to one directory -- onto set_property(TEST ...). This repository suppresses add_test() while it pulls its dependencies in, so those test names do not exist, and set_property errors on an unknown test name where set_tests_properties was silent: eight hard configure failures. Shadow set_property in its TEST form only; every other form has to pass through, since the dependencies set target and directory properties their own builds need. libakgl's status band grew to seven codes with AKGL_ERR_UI and it now owns 256 to 262, so the coordinated range map, docs/15-error-codes.md and both header comments follow. TODO.md section 5's persistent-drawing-layer item still stands: 0.9.0's arena draws inside the frame like everything else, and there is still no render-to-texture layer. Both configurations build and both suites pass -- 110/110 without libakgl, 111/111 with it, akgl_typing included. Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 16:56:52 -04:00
Tachikoma	fc122e5503	Let C call a BASIC function with values it already has ... `akbasic_runtime_call_function(obj, name, args, nargs, dest)`. The argument binding is split out of the call-site handling, so `akbasic_runtime_user_function()` becomes evaluate-the-leaves and then call the same code -- and a verb that wants to hand a BASIC function four numbers has somewhere to start, which it did not before. The only entry point took a parsed AST call site, so calling a function required having been parsed as an expression. Behaviour-preserving: both suites pass unmodified. The one deliberate difference is that the AST path now evaluates *all* the arguments before binding any of them, where it used to interleave. That is the safer order and it is what by-value passing means everywhere else -- interleaved, a later argument could see an earlier one already in the callee's scope. **Finding, filed as section 6 item 41: a multi-line `DEF` called outside a running program does not run its body, and says nothing about it.** DEF TRIPLE(N#) T# = N# * 3 RETURN T# PRINT TRIPLE(14) At the REPL that prints "(UNDEFINED STRING REPRESENTATION FOR 0)". From a file the same function answers 42. The multi-line body runs by spinning a line loop guarded on `mode == AKBASIC_MODE_RUN`, which is true only of a program running from a file; in REPL mode the loop is skipped and the result is the caller's zeroed return slot. The single-expression form has no such loop, and every case in tests/user_functions.c goes through run_program and is therefore in RUN mode, which is most of why nobody had seen it. **The obvious fix is wrong and I tried it.** Widening the guard to `mode != AKBASIC_MODE_QUIT` makes the interpreter *hang* instead of answering wrongly -- `akbasic_runtime_process_line_run()` does not advance a REPL-mode runtime the way the loop assumes, so the environment never comes back. Trading a silent wrong answer for a lock-up is worse, so it is reverted, the reasoning is in a comment where the next person will try the same thing, and the fix is filed rather than guessed at. That bounds this entry point rather than blocking it: it reaches a multi-line body while a program is running, which is exactly the case a verb calling a callback is in. The new test asserts the single-expression form from C and says in a comment why the multi-line one is not asserted, so the omission is a statement rather than a gap. What is still not done is the language half -- no verb takes a function, and nothing resolves a bare word to a function rather than a label. Item 40 now says so, and says it wants a verb that needs it rather than speculation. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 11:06:45 -04:00
Tachikoma	a9059423e9	Say what was hit, which way is out, and how far ... The narrowphase has been producing a contact since it went in, and the interpreter was throwing it away. `RCOLLISION(n, f)` reports it: what was hit (a sprite or a `SOLID` rectangle), which one, the contact normal, the penetration depth, the contact point, and which axis to reverse. **The normal points out of the other thing and toward this one**, so a program moves along it by the depth and is exactly clear. That sign is the one assertion in the new test that could not be caught any other way -- both parties of a sprite-against-sprite hit get their own record, each pointing the way *that* sprite has to move, and sharing one would tell both to go the same direction, which is how two things end up stuck inside each other. **Field 7 is the one that deletes the most BASIC.** It is the minimum translation axis, computed from the normal in C, and it is there because doing it in BASIC means comparing two floats -- which is exactly where this dialect's left-operand rule catches people. `BALLBRICKS`/`TESTCELL` in the artwork breakout spend six lines computing an overlap rectangle and comparing its width to its height to get this number. The record is **sticky and deepest-wins**: replaced whenever that sprite is in a contact and otherwise left alone, so `BUMP` stays the event and this stays the detail of it. Making it clear itself when nothing touches would break the pairing, because `BUMP` accumulates across steps and a once-a-frame poll would find the detail already gone. Reading `BUMP` clears both, so they cannot disagree. Deliberately narrower than `akgl_Contact`: no actor pointers, because BASIC has no actor; no tile fields, because there is no tilemap; no z, because every test is planar; and **no `dt` and no `sensor`**, which libakgl documents as filled in by the resolver. This interpreter never resolves anything, so those two come back zero and mean nothing, and an always-zero field in a reference table is a lie. Documented with the two caveats that matter: fields 2, 3 and 4 are floats and want a `%` variable, and the contact *point* is exact only for two boxes -- libakgl's solver returns a point on the portal it converged to, while the normal and depth are exact for every pair. Chapter 8's collision section stops claiming only type 1 exists, which has been false since the previous commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 10:53:26 -04:00
Tachikoma	d3b69ff867	Keep what a program draws, instead of making it a sprite ... A drawing lasted exactly one frame. The verbs are immediate, they went to the back buffer, SDL double-buffers and the frontend never clears -- so the only way to keep a picture was to capture it with `SSHAPE` and install it as a sprite, which is what `examples/breakout/sprites/breakout.bas` spends two of its eight sprites doing. That was TODO.md section 9 item 9. The drawing verbs now render into a layer texture the frame composites under the text and the sprites. Draw once; it is there on every frame after. **Bracketed around the step phase, not around each verb.** One pair of `SDL_SetRenderTarget` calls a frame instead of one per `DRAW`, and it is also what makes `SSHAPE` read back what the program has just drawn rather than whatever the last frame left. **The layer is transparent where nothing was drawn.** It covers the whole window and composites underneath, so an opaque one would black out the frame the moment a program issued a single `DRAW`. And a fresh SDL target texture's contents are undefined, so it is cleared on creation -- skipping that puts uninitialised memory under the first frame's text and looks like a driver bug rather than a missing memset. **The line editor forced a wrinkle worth naming.** `akbasic_frontend_akgl_pump()` is called from two places with different answers to "is a render target current": the frame loop calls it between steps, and the sink's editor calls it from *inside* a step, borrowing a frame while it waits for a typed line. SDL refuses to present while a target is current, so the pump ends the layer, presents, and puts it back only if it was the one that ended it. `akgl_frontend` caught this -- it drives a REPL session, and it failed with "You can't present on a render target" the first time the brackets went in. This does not make a drawing *visible* on its own. The text layer still repaints every row it owns, opaque, every frame, and by default it owns the whole window; `WINDOW` shrinks it and that half was already fixed. The two together are what a picture needed, and the tests assert both -- a pixel still there a frame later with nothing redrawn, and a pixel below a shrunk text area surviving the text repaint. The second assertion wipes to a non-black colour first, because against black it could not tell a transparent layer from an opaque one. The tests found two of their own bugs on the way: `stop_runtime()` was not tearing the graphics backend down, so re-initialising it dropped a live texture on the floor; and a first draft called `begin()` before `start_runtime()`, which re-inits the backend, so the assertion read back off an orphaned render target and passed while proving nothing. Chapters 6 and 13 stop saying a drawing has to be redrawn every frame, because it does not. The batch-boundary tear stays documented -- it bites an `SSHAPE` capture, which matters much less now that capturing is not the only way to keep a picture. Both games still run clean. 111 with akgl, 110 without. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 10:46:10 -04:00
Tachikoma	66d8670690	Collide sprites with rectangles that are not sprites ... `SOLID id, x1, y1, x2, y2` registers static collision geometry; `SOLID id` retires one and a bare `SOLID` retires them all, the way `TRAP`, `COLLISION` and `DCLOSE` all read absence. `COLLISION 2` and `BUMP(2)` stop being refused and mean *sprite met static geometry*. **This is the thing eight sprite slots made impossible.** A wall of bricks wants sixty, so until now a program could only collide with one by doing the arithmetic itself against its own array -- which is exactly what both breakout listings do, at about two hundred lines between them. A rectangle costs no sprite slot. The id is the **program's own number**, 1 to 64, not a minted handle. That is the whole trick for "which brick did I hit": the id comes back out again, so a wall built as `SOLID I#, ...` maps onto `B#(I#)` with no lookup, and retiring a broken brick is `SOLID I#`. `COLLISION 2` was refused with "sprite-to-background collision needs the screen read back every frame", which was true of the question a C128 asks -- a sprite against the bitmap's set pixels. `SOLID` gives this interpreter a background made of rectangles instead, which is the same question in a form it can answer. Same move `SPRSAV` made when it learned to take an image path. `AKBASIC_INTERRUPT_BACKGROUND` has been sitting in the interrupt table commented "COLLISION 2 -- sprite met background; refused" the whole time. Its accumulator is separate, so a sprite hitting a wall never sets a bit in `BUMP(1)`. **There is no `akgl_CollisionWorld` here, and that is deliberate.** libakgl's uniform grid keeps its cell heads, cell size and origin in file-scope statics, so it is one index per process -- and `akgl_collision_world_init()` ends in a `reset()` that memsets those heads *and* calls `akgl_heap_init_collision_cells()`. An interpreter embedded in a game with its own collision world would have destroyed every registration that game had made, on the first `SOLID` a script ran. So the geometry is indexed by an ordinary array here and pairs go straight to `akgl_collision_test()`, which needs no world. At sixty-four rectangles that is the right answer anyway; libakgl's own numbers put a naive sweep at 0.7% of a frame at sixty-four objects. **The scan now short-circuits when nothing has moved**, and that is what makes any of it affordable. Its inputs are the sprites' boxes, which slots are collidable, and the static geometry; if none changed the answer cannot have. A frame runs one full scan and 255 cached ones. Eight sprites against sixty-four rectangles is five hundred and twelve tests -- fine once a frame, ruinous 256 times. The benchmark was rewritten to say which path it is timing, because with the cache in place a loop that only calls the scan measures the short circuit and nothing else. Breakout now costs 590.6 ns for its one full scan plus 255 cached at 40.0, which is 10.8 us against a 1.19 ms frame -- **0.91%, less than the 2.0% it cost before any of this work**, with static geometry and contacts added on top. `NEW` retires the rectangles, where it cannot undefine a sprite pattern: there *is* an entry point for this one, so leaving them would be a choice, and the wrong one -- a rectangle is invisible, so one left behind by a deleted program is an unexplainable collision in the next. `CLR` leaves them alone. `tests/sprite_verbs.c` gains the whole second path against the mock and its `COLLISION 2` case is rewritten: it pinned the refusal, and now pins that type 2 arms its own handler without disturbing type 1's. `tests/akgl_backends.c` gains the end-to-end version, including a full sixty-four-rectangle wall so the proxy budget is exercised at its ceiling and the pool has to come back intact, and the sixty-fifth refused by name. A bare `SOLID` needed `akbasic_parse_optional_arglist` rather than `akbasic_parse_arglist`, which `DCLOSE` already uses for the same shape. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 10:25:35 -04:00
Tachikoma	f637292eb7	Let a program say what part of a sprite collides ... `SPRHIT n, kind [,x1, y1, x2, y2]` gives a sprite a collision shape: a box, a circle inscribed in it, or a capsule. `RSPHIT(n, f)` reads it back in SPRHIT's own argument order, the way RSPRITE and RSPPOS already do, and needs no device because it answers from interpreter state. The rectangle is two corners measured from the sprite's top-left, in device pixels -- the same `x1, y1, x2, y2` that `BOX` and `SSHAPE` take. A dialect with two spellings for a rectangle is one nobody can write from memory. Omit it and the shape fits whatever the picture turned out to be, which is what a sprite loaded from a file needs: `SPRSAV "ship.png", 1` takes the image's own size and the program never learns what that was. **A sprite nobody has shaped collides with its whole frame, expansion bits included, exactly as before.** That is a promise rather than a convenience, and it has its own test: the same two sprites in the same two places, once with no SPRHIT and once with a four-pixel box, reporting a collision and then not. Named SPRHIT rather than SPRSHAPE because "shape" already means "a region SSHAPE saved" in this dialect, in this very chapter -- `SPRSAV A$, 1` takes one -- and a reader who typed `SPRSHAPE A$, 1` would have had every reason to. Both names, and RSPHIT, were grepped against every label in docs/, examples/ and both corpora first: a bare word is a label here, so a verb and a label share one namespace and taking a name a checked-in listing already uses would break it silently. `SPRHIT n, 0` takes a sprite out of collision while leaving it on the screen -- the ghost, the flashing invulnerable player, the pickup already taken. Hiding it with `SPRITE n, 0` stops it colliding too, and is what you want when it should not be seen either. The circle answers the complaint chapter 8 already ships a figure of. That figure shows two discs whose *boxes* touch at a corner while the artwork is nowhere near, and `BUMP(1)` reporting a collision; two `SPRHIT n, 2` and it stops. The test asserts both halves so the figure's caption stays true. `tests/verbs_table.c` caught RSPHIT filed after RSPPOS rather than before it, which is the sorted-table test doing exactly the job it exists for. Docs: a new section in chapter 8, rows in the verb and function references in alphabetical order, and chapter 13's "collision is by bounding box" becomes "collision is by shape" with the addition named. 111 with akgl, 110 without, and the artwork breakout still runs clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 10:01:33 -04:00
Tachikoma	c18ec17e8f	Answer sprite collision through libakgl's narrowphase ... `spr_collisions()` computed axis-aligned overlaps itself, because at libakgl 0.7.0 there was nothing to delegate to: `akgl_collide_rectangles()` has a documented corner-containment defect and the physics backend's `collide` slot raised "Not implemented". 0.8.0 brought a real narrowphase, and this moves onto it. The mask is bit-identical and every test from the previous commit passes **unmodified**, which was the gate this stage had to clear -- including the two that were written to be hard to satisfy. Edge-to-edge is still not a collision, so a tile-aligned program is unaffected. The cross-shaped overlap is still reported, which is the one that could have regressed: it is the case `akgl_collide_rectangles()` gets wrong and the reason the hand-written loop existed, and `akgl_collision_test()`'s box path gets it right. What it buys is the contact -- a normal, a penetration depth and a point -- which four comparisons cannot produce. Nothing consumes it yet; that is the next commit. It is here now because the mask and the contact come out of the same test, and computing them in two places would be two things to keep in step. **The first attempt was ten times slower and the benchmark caught it.** Syncing all eight proxies and running the narrowphase on all twenty-eight pairs measured 984 ns a scan against 96 ns for the loop it replaced -- 21% of a frame at 256 scans a frame -- to produce a mask that was bit-identical and a contact that was thrown away. Two changes fixed it, and both are what a broad phase *is* rather than workarounds for a slow library: - **Reject on the bounding boxes first.** The four comparisons that were always here now decide which pairs are worth an exact answer. The narrowphase still decides the bit -- the box test only says "maybe", which will matter the moment a shape is not the whole frame. - **Do not sync a proxy that has not moved.** The scan runs at the top of every interpreter step and a sprite moves at most once in that time, so almost every sync would rewrite a proxy with what it already holds. Compared against the last synced rectangle rather than flagged by the verbs, because a host game can move a BASIC sprite through the actor registry and a flag would miss that. Measured after: 54.9 ns at eight sprites spread out, which is *faster* than the 96.3 ns it replaced -- boxes are now built eight times a scan instead of fifty-six. The number that matters is the new benchmark row for the arrangement `examples/breakout/sprites/breakout.bas` actually has, which is 211.8 ns, or 4.5% of a frame. That game reaches it because two of its eight sprites are the screen -- a captured HUD strip and a captured play field -- so the field's box covers everything and those pairs can never be rejected. Roughly double the old cost, for contacts. Recorded in MAINTENANCE.md with the two synthetic extremes either side of it as a bracket. The eight proxies are claimed once at init and held, so exhaustion of the pool shared with an embedding host is an initialization failure that names the pool rather than a collision scan refusing halfway through somebody's game. The shape is built before the proxy is spawned from it and the acquire sits adjacent to the initialize, which are two traps libakgl hit itself and documents. `tests/akgl_backends.c` now tears the sprite backend down between cases. It never did, and got away with it while init claimed nothing; eight proxies apiece across twenty cases is a hundred and sixty against a pool of a hundred and twenty-eight. A host releases what it took, and so does the harness. Both games run forty seconds headless with no error line. 111 with akgl, 110 without. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 09:48:11 -04:00
Tachikoma	240e0dd141	Take libakgl 0.8.0, and correct the status range it grew ... The pin moves e4aa6a5 -> 149bee0, which is libakgl 0.8.0. Nothing in this repository changed to accommodate it: both suites pass unmodified, 110 without akgl and 111 with, and both breakout games run forty seconds headless with no error line. **0.8.0 is a whole collision subsystem** -- shapes, pooled proxies, a pluggable broad phase over a uniform grid, a narrowphase answering with a contact carrying a normal and a depth, world box queries, and static proxies for geometry that is not an actor. None of it is called from here yet. This commit is the pull and nothing else, so that if it has to come out it is one revert of one commit. **It adds two submodules of its own**, `deps/libccd` and `deps/tg`, so a tree that updates without `--recursive` configures and then fails compiling libccd. libakgl's own suite was built and run standalone at RelWithDebInfo before akbasic was pointed at it: 33/33. `libakstdlib` and `libakerror` did not move. MAINTENANCE.md requires checking, and the answer this time is that libakgl 0.8.0 pins exactly what this repository already pins -- 669b2b3 and 5eaa956 -- so the pairing rule is satisfied without a bump. Recorded because "we checked and it was already aligned" and "we forgot to check" look identical in a diff. **The version floor moves to 0.8.0** with its paragraph, following the convention in that header of saying what each minor release did and why the floor moved anyway. Worth knowing for whoever reads it next: `akgl_Actor` grew fields, so a translation unit compiled against a 0.7 `actor.h` and linked against 0.8 writes `renderfunc` and `actorData` at the wrong offsets -- and `src/sprite_akgl.c` writes exactly those two. That is the case the soname cannot catch and the guard exists for. **libakgl's reserved status band grew from five codes to six**, gaining `AKGL_ERR_COLLISION` at `AKGL_ERR_BASE + 5`, so it now owns 256-261 and the headroom below akbasic's band starts at 262. Four documents said otherwise: the coordinated range map in MAINTENANCE.md, the comment above the enum in `include/akbasic/error.h`, the file header of `include/akbasic/akgl.h`, and chapter 15. That map is the only coordination there is -- nothing enforces a band boundary at compile time, and the first anybody would know of an overlap is a status printing under the wrong owner's name in a stack trace. Also cleaned on the way past: `deps/libakgl/deps/libakstdlib` was showing dirty in `git status`. It had no local edits -- the checkout was simply one commit behind the gitlink libakgl records -- so `git submodule update` restored it and nothing was lost. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 09:35:22 -04:00
Tachikoma	64e2027099	Write down that the left operand decides integer or float arithmetic ... No behaviour change, by decision. `A# * 0.45` is 0 and `0.45 * A#` is 1.35, because every operator branches on `self->valuetype` and converts the right operand to match. It is inherited from the Go reference, a C128 promotes to float instead, and this interpreter is at least consistent about it -- so a dialect saying the left operand wins is a defensible position, and changing it to promotion would alter the result of every mixed expression in every existing program. **The defect was that nobody said so.** Chapter 3's "Numbers" did not mention it, Chapter 13 did not list it among the differences, and nothing fails when a program gets it wrong -- it computes something else and carries on. The game in examples/ lost its per-level speed increase to `5.6 + LEVEL# * 0.45` evaluating to a flat 5.6, and bled velocity out of every bounce through `0 - BLVX%(B#)` quantising to whole pixels. Both read correctly. Neither produced a diagnostic. Now said in three places: a section in Chapter 3 with the demonstration and the two rules that keep a program out of it (put the float on the left, put the answer somewhere with a `%` on it), a row in Chapter 13 naming it as the difference from 7.0 most likely to turn a working listing into a quietly wrong one, and the reasoning on value.h where the operators are declared. tests/value_arithmetic.c pins it in both directions across multiply and subtract, with a comment saying it is the documented contract rather than an accident -- so promotion becomes a decision somebody takes deliberately rather than a change that could slip in under a passing suite. TODO.md section 9 item 4, struck as a documentation outcome. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 00:23:20 -04:00
Tachikoma	748fb5f91c	Honour a subscript in SSHAPE and GSHAPE ... `shape_variable()` took the identifier off the leaf and looked the variable up without ever evaluating the subscript, and both verbs then addressed element zero with a literal. So `SSHAPE SH$(2), ...` wrote the handle into `SH$(0)` and `GSHAPE SH$(2)` stamped whatever was in `SH$(0)`. Ordinary assignment and `PRINT` honour the subscript, which is what made this expensive: a program keeping several saved shapes in an array got every one of them resolving to the same element, silently, and the only symptom was that every stamp came out as the last shape captured. The Breakout in examples/ keeps its six brick stamps in six separate scalars for exactly this reason. `SPRSAV` was the counter-example and is the model -- it evaluates its argument and handles an array element correctly. The subscript resolution itself is now shared: `collect_subscripts()` comes out of src/environment.c as `akbasic_environment_collect_subscripts()`, so a verb taking a variable by name resolves a subscript the same way assignment does rather than each verb deciding for itself. tests/graphics_verbs.c covers TODO.md's reduction -- which used to print "[SHAPE:0] []" and now prints "[] [SHAPE:0]" -- and the case a program actually wants: two shapes captured into two elements, each stamped back through its own, asserted against the device log so a fix that merely made the strings look right would not pass. Chapter 18's trap 4 becomes history, and Chapter 6 says an array works. TODO.md section 9 item 6, struck. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 00:10:24 -04:00
Tachikoma	f626d7985f	Let a program ask how big the text grid is ... `RGR(1)` and `RGR(2)` gave the window in pixels and nothing gave columns, rows or the cell size -- so anything placing a character *and* a sprite at the same spot had to hardcode a number measured by hand against whatever font the host loaded. The Breakout in examples/ does exactly that, `CW# = 16`, and it is the one thing in that listing that breaks on a different font or window. **`RWINDOW` is BASIC 7.0's own answer and had never been implemented here.** `RWINDOW(0)` is the current text window's rows and `RWINDOW(1)` its columns. `RWINDOW(2)` reports a C128's 40 or 80 column screen mode, and this interpreter has neither -- refused by name, because answering 0 would be a plausible lie, which is worse than a refusal that says why. The cell size in pixels is `RGR(3)` and `RGR(4)`, beside the surface's own dimensions rather than on `RWINDOW`. Two reasons: a cell size is a fact about the surface, and `RWINDOW` reports the *window*, so dividing `RGR(1)` by a column count stops being right the moment a program calls `WINDOW`. Both read a new optional `grid` entry point on `akbasic_TextSink` -- columns, rows, cell width, cell height -- implemented by the akgl sink and forwarded by the tee, in the shape `moveto` and `window` already had. NULL everywhere else, so both verbs refuse by name against a sink with no grid. `akbasic_sink_init_ stdio()` clears it for the same reason it now clears the other two. Measured on the standalone build: `RGR(3)` answers 16 and `RWINDOW` answers 50 columns by 37 rows -- the three numbers the Breakout listing had written out as constants -- and `RWINDOW` follows a `WINDOW` call while `RGR(3)` does not. tests/console_verbs.c drives the answers through a stand-in sink with a grid, since the harness sink is stdio and has none; tests/graphics_verbs.c covers the new `RGR` fields, their refusal, and the moved range bound. The `c excerpt=` block in docs/10-embedding.md moves with the header, which is `docs_examples` doing its job. TODO.md section 6 item 31's second half, struck. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-02 00:05:17 -04:00
Tachikoma	95b76a8851	Enter a TRAP handler when the variable table is full ... Two separable faults, both on the path a program takes when it is already in trouble. `akbasic_trap_set_error_variables()` reached `ER#` and `EL#` through `akbasic_runtime_global()`, which *creates* a name the program never used -- and creating one takes a variable slot. So a program that had filled the 128-slot table could not have its handler entered at all, and because the failure happened inside the error path rather than raising, nothing was reported and the program carried on with the failing statement's effect quietly missing. A wrong answer delivered as a right one, which is worse than an abort. `akbasic_runtime_reserve_globals()` now creates both at runtime init, where there is always room, and `clear_variables()` puts them back after `CLR` and `NEW` empty the table. Second: `report_and_reraise()` used a plain `PASS` around the report, so a failure while reporting *replaced* the error the program had actually made -- "Maximum runtime variables reached" in place of the subscript that was out of range. The secondary failure is now logged and the original is re-raised, which is what a user needs to hear. **The reduction in TODO.md no longer reproduces, and not because of this.** The value-pool fix in the previous commit made a scalar free, so the pool can no longer be emptied by creating names. The defect was still live through the variable table: 124 names and a TRAP armed, and the handler was silently skipped. That is what the new test in tests/trap_verbs.c pins, together with the invariant -- both globals present before a program runs. Verified by reverting the fix against the new tests: both fail, and the second prints the log line the swallow used to eat, "could not report a BASIC error 515 (Out Of Bounds): Maximum runtime variables reached". TODO.md section 6 item 33, struck. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 23:48:56 -04:00
Tachikoma	8b9c788ad7	Stop a scalar created inside a scope costing value-pool slots ... A scalar now lives in the variable record (`akbasic_Variable::inlinevalue`) rather than drawing from the value pool, so a `GOSUB` local, a `FOR` counter and a `DEF` parameter cost nothing at all. The pool is a bump allocator with no free, and its comment justified that with "nothing in BASIC destroys a variable". Scope exit does: it marks the variable slot unused, `new_variable()` memsets the slot it hands back -- clearing `values` -- and `variable_init()` therefore took *fresh* slots for a variable whose old ones were still counted. Every scope that created a local leaked, with no diagnostic until the pool ran dry on whichever line happened to be unlucky. Six thousand `GOSUB`s creating one local used to die on the 4091st at `LOC# = 1` with "Array of 1 elements does not fit in the 0 remaining value slots". They now run. A `DEF` called eight thousand times used to die between the four and five thousandth -- the leaking slot was the call scope's parameter, which is a scalar -- and both forms now run. A game creating one name per tick was dead in half a minute; the Breakout in examples/ was, after twenty-five seconds. **A `@` name is the one exclusion, and it is the whole of it.** A structure or a pointer to one keeps pool storage, because a pointer into a record outlives the scope that DIMmed it -- docs/16-structures.md says nothing is reclaimed and `prev_environment()` relies on it. The name suffix is the right test rather than `structtype`, which the DIM path sets *after* calling `variable_init()`. A local array therefore still leaks, deliberately, and is now the narrow rule the tutorial teaches. `SWAP` needed the other half: it copies whole variable records, so the `values` pointer that came over named the other variable's inline slot -- which by then held this variable's own old value -- and SWAP silently did nothing. Caught by tests/language/housekeeping/verbs.bas, which is the golden corpus earning its keep. tests/value_pool.c is the new coverage. It asserts the mechanism as well as the consequence: a later change that moved arrays inline too would pass every behavioural case and quietly break the pointer guarantee. The sharpest case takes the pool's whole 4096 slots in four arrays after two hundred scope entries, so one leaked slot has nowhere to go. Chapter 17 Step 3 taught "declare every name at the top" and no longer needs to. It now teaches what is still true -- a name first seen inside a subroutine dies at RETURN, so a routine cannot answer its caller through one -- and its demonstration is the array case, which still fails. TODO.md section 6 item 30 and section 9 item 1, both struck. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 23:47:49 -04:00
Tachikoma	eab5e2e1fc	Refuse a branch to a line the program did not number ... GOTO 100 in a script written without line numbers finds the hundredth line and branches there. Silent, plausible and wrong: the test for it loops forever printing the second line when the check is removed. akbasic_runtime_check_targets() is a fourth prescan beside the label, DATA and TYPE ones, run on every entry into MODE_RUN -- the earliest the check can be made and the only place all four ways a program arrives pass through. A target naming an empty line is still allowed, for the same reason RENUMBER leaves one alone, and a fully numbered program is unaffected, which is every program that existed before this. It shares RENUMBER's walk rather than repeating it. renumber.c grows an akbasic_TargetWalk -- a self pointer and a visit function -- and rewrite_line() takes one. RENUMBER's visitor substitutes the number a line moved to; the check's substitutes the number unchanged and raises. One walk, so the two cannot disagree about what a branch target is. The check points environment->lineno at the line being walked so the "? N :" prefix names the offending line. The other three prescans do not and report whichever line the loader stopped on; TODO.md section 5 item 64 records it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 16:38:54 -04:00
Tachikoma	60698a5fcc	Give a loaded line a number when it arrives without one ... A script written against LABEL and GOTO NAME never names a line number, so the numbers it had to carry were decoration. akbasic_runtime_load(), RUNSTREAM and DLOAD now file an unnumbered line one slot after the last one filed; a numbered line is filed under its number and moves the cursor, so the two mix. akbasic_runtime_file_line() is the one implementation of that rule, so the three paths cannot drift. The prompt is untouched. A line typed without a number is still direct mode and still runs now -- that is the only thing separating program text from a statement at a REPL, and it is why this is a loading feature. What this replaces was silent data loss: an unnumbered line was filed under the cursor unchanged, on top of the line before it. A blank line therefore erased whatever preceded it, and RUNSTREAM did not skip blank lines the way the other two paths did. That moves one golden file, and the reference had the same defect. language/arithmetic/integer.bas has four PRINT statements, an expectation with three values, and a trailing blank line that erased 40 PRINT 4 - 2 before the program ran. The expectation is now 4 4 2 2. tests/reference/README.md records the divergence and TODO.md section 5 item 63 says why. akbasic_SourceLine grows a `numbered` flag so an assigned number can be told from a written one. RENUMBER sets it on every line it touches; NEW, DELETE and DLOAD clear it. hadlinenumber moves to akbasic_scanner_scan(), so it always describes the line just scanned rather than only the REPL's. Two lines carrying the same written number still keep the last, as they always have. That is a separate decision. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 16:33:27 -04:00
Tachikoma	9ed41f429f	Take libakgl 0.7.0, and refuse an over-long type or field name ... 0.6.0 and 0.7.0 break nothing here: 0.6.0 is three arcade-physics fixes and a physics.max_timestep property this port does not use, and 0.7.0 reports failures libakstdlib's wrappers were already catching and takes libakerror 2.0.1 so it can drop the exit-status trap its own suites needed. That is the same defect include/akbasic/error.h guards for this band, now fixed at the source rather than worked around in two places. The floor moves to 0.7.0 anyway. The soname carries MAJOR.MINOR while the major is 0, so deciding for ourselves which of libakgl's minor releases were really compatible is exactly the judgement it exists to take away. 0.7.0 is largely about a defect class worth checking for here rather than assuming past: ten unterminated strncpy calls into fixed-width name fields. Ours are clean -- every one is bounded to size - 1 and every buffer is either explicitly terminated afterwards or memset first, checked site by site. But two of them, both written last week in src/structtype.c, truncated an over-long name silently, and truncation is an error everywhere else in this interpreter. It matters more for a name than for a value: two long type names trimmed to the same 31 characters collide, and the second is then reported as redeclaring a type the program never wrote. Both are refused now, showing the name as written. The check was unreachable as first drafted, because the prescan read words into a buffer the size of the limit and so trimmed them before anything could look -- the scratch is twice the limit now, which is what makes the two cases distinguishable at all. tests/struct_types.c pins that it stays reachable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 13:30:35 -04:00
Tachikoma	c4ac0e3a5f	Give each DEF call its own environment, so recursion returns ... The function's environment was owned by the funcdef and re-initialised on every call, which made a function not re-entrant and cost two silent defects: DEF DBL(N#) = N# * 2 PRINT DBL(10) + DBL(1) was 4, should be 22 The result was a pointer into the funcdef's own environment, so the second call overwrote the first before the operator saw it -- both operands became the last call's answer. Two *different* functions in one expression were fine, which is most of why it was invisible. DEF FACT(N#) IF N# <= 1 THEN RETURN 1 RETURN N# * FACT(N# - 1) PRINT FACT(5) never returned The recursive call re-initialised the environment the outer call was still using, so the loop waiting for control to come back could not see it. No error, no bound, no diagnostic -- the one place in this interpreter that looped forever rather than raising. A call takes an environment from the pool now, exactly as GOSUB does. The result is copied into a caller-scope scratch before that environment goes back, because handing back a pointer into the callee is what made two calls collide and would now be a pointer into a released slot as well. RETURN parks its result on the *parent* rather than on the environment it is about to release, so nothing reads a freed slot to find it. Recursion depth answers to AKBASIC_MAX_ENVIRONMENTS like every other nesting, so too deep is "Environment pool exhausted" -- a diagnosis where there was none. akbasic_FunctionDef.environment goes with it, as dead state. One thing this exposed but did not cause, measured against a stashed build and recorded rather than fixed: a statement containing a failed multi-line DEF call still completes and prints a junk value. It is visible more often now only because runaway recursion reaches it where it used to hang. tests/language/functions/recursion.bas deliberately does not pin that answer. Chapter 16 loses its "walk a list with a loop, not a recursive DEF" caveat and gains the one that is still true: a function cannot take a structure parameter yet, so it reaches a record by name. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 12:29:35 -04:00
Tachikoma	cd038a55a2	Share a host program's own C structures with a script ... A BASIC TYPE and a host C struct are the same thing seen from two sides, so both go in one type table and everything the language already does with a structure works across the boundary with no second set of rules. The host describes its struct once as a table of field descriptors and binds an instance: akbasic_host_bind(&SCRIPT, "FOE@", "ENEMY", &GOBLIN); after which `FOE@.HP# = FOE@.HP# - 10` decrements GOBLIN.hp in place, with no marshalling step the host has to remember to run. The sharing is done with shadow slots: a binding takes a run from the same value pool a DIMmed record uses, a field read refreshes its slot from host memory first, and a write converts back and stores. So the script always sees current values and its writes always land, while the rest of the interpreter goes on seeing one storage model instead of two. AKBASIC_HOST_FIELD takes the offset and the width from the same member, which is the only reason it is a macro: writing offsetof and sizeof out by hand is two chances to name the wrong member and no way to notice. A field name's suffix must agree with the C type it describes, refused at registration -- a host writing "HP%" over an int32_t has said two different things about one field and the script would believe the suffix. Conversion refuses rather than truncates. 200 into an int8_t, 70000 into an int16_t, -1 into a uint8_t and thirteen characters into a char[8] are each an error naming the field, because a silent wrap is found three frames later in code that did nothing wrong. Each width is tested separately, since a range check is exactly the thing that is right for int32_t and wrong for int8_t when only one of them is covered. The language's own distinction turns out to be the one a host needs, so there is one API rather than two: assignment copies and gives a script a private snapshot, POINT shares and lets it change the game, and which one happened is visible in the listing. Two things the work required. The prescan runs again on every RUN and used to wipe the whole type table, unregistering the host's types the first time a script ran; it now keeps what the host registered and drops only what the script declared. And akbasic_runtime_start() did not rewind, which cost nothing while a host started a script once and cost everything to a host running one per enemy -- the second start began past the end and silently did nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 11:56:04 -04:00
Tachikoma	c83ffa9a3b	Add strict pointers: AS PTR TO, POINT ... AT, and the -> operator ... A pointer is a distinct declared kind rather than a mode a structure can be in, which is what "strict" means here: `.` requires a structure on its left and `->` requires a pointer, neither stands in for the other, and both refusals name the operator the program should have used. So a reader always knows from the spelling whether the thing on the left is their own copy or somebody else's data. Assignment still copies. POINT is the only way to share, so a program that never writes it can never be surprised by aliasing -- and `P@ = A@` is refused with a message saying to POINT it instead, rather than quietly becoming the one assignment in the language that does not copy. PTR TO is also the only way a TYPE may refer to itself, since by value it would have no finite size. That is what makes a linked list possible, and tests/language/structures/pointers.bas builds one, walks it and renders it. Rendering follows pointers, so it needs a depth bound where copying does not: copy stops at a pointer by construction, but two nodes pointing at each other is easy to write and PRINT would not come back. Four levels, chosen so the bound bites before the 256-byte render buffer does -- otherwise a cycle would stop because it ran out of room rather than because it was told to. Three things the work turned up, all now pinned by tests: A freshly DIMmed record printed `(UNDEFINED STRING REPRESENTATION FOR 0)` for every field. Slots now take the type their field declared, so it reads as zeros. Adding POINT as a verb makes POINT unusable as a type name, and the parser reported that as "Expected expression or literal" pointing at the line rather than the problem. The prescan now refuses a reserved word as a type name and says so. Field names follow the same reserved-word rule as variable names, enforced by the loader's own scan -- `TO@` is a bad field name for exactly the reason `TO#` is a bad variable name. Recorded rather than worked around. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 11:48:09 -04:00
Tachikoma	4f86a9ca44	Add records: TYPE, DIM ... AS, field access, copy on assign ... BASIC 7.0 has no records at all, so none of this is a port. The `@` suffix was not invented either: the Go reference reserved IDENTIFIER_STRUCT and never used it, and src/grammar.c rendered such a leaf as "NOT IMPLEMENTED" until now. Declaring the type is what buys the storage model. A TYPE states its fields, so an instance has a known slot count and is laid out exactly as an array is -- one contiguous run from the same value pool DIM already draws from, with field access as offset arithmetic. No new pool holds data; the only new table holds descriptors. A nested value flattens into its container's run, which is why LINE with two POINTs and a string is five slots rather than three. Each field takes its type from its own suffix, the same rule every other name here follows, so a field list needs no type column. An `@` field is the exception and has to name its type, because three primitive types fit in three suffix characters and N declared types do not fit in one. The declaration is prescanned before the program runs, like labels and DATA and for the same reason: it has to be in effect wherever control goes. Three passes, each for a case the one before cannot do -- names first so a field can refer to a type declared later, then field lists, then sizes by repeated resolution. What never resolves is a cycle of by-value containment, so "a TYPE cannot contain itself by value" is a diagnosis rather than an assumption, and the message says to use PTR TO instead. Assignment copies. That interception is the whole feature and it cannot live in akbasic_value_clone(), which copies one slot -- and one slot holds a *reference* to an instance rather than the instance, so going through it would alias. A structure is intercepted before that path and its slots are copied one at a time, walking the descriptor rather than memcpy-ing the run, because a pointer field must copy its reference where a value field must copy its slots. Two smaller things the work required. All three prescans now sit inside one ATTEMPT: a malformed declaration is the program's mistake, and it was printing a stack trace and taking the driver with it, which is the boundary goal 3 exists to draw. And a fresh variable's structtype is -1 rather than the 0 a memset leaves, because 0 is a valid type index and every new variable was claiming to be the first type declared. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 11:39:47 -04:00
Tachikoma	4f809b81d8	Take libakgl 0.5.0 and rename every symbol it namespaced ... 0.5.0 gives every exported symbol the akgl_ prefix, which is the first libakgl release to break this project's source rather than only its ABI. The soname goes to libakgl.so.0.5 and include/akbasic/akgl.h asserts the floor. What moved here: akgl_render_bind2d is akgl_render_2d_bind, akgl_sprite_sheet_coords_for_frame is akgl_spritesheet_coords_for_frame, the renderer, camera and window globals carry the prefix, and _akgl_renderer and _akgl_camera are akgl_default_renderer and akgl_default_camera. The renames were applied by site rather than by pattern, because renderer is also a parameter name in src/sprite_akgl.c and a struct member throughout src/frontend_akgl.c -- a substitution would have rewritten both without a word. That is the same trap upstream describes hitting, and it is worth knowing that the defect behind the rename was not cosmetic: an exported global called renderer collided with a test's own variable, the executable's definition preempted the library's, and every texture load in that suite failed while the suite passed. 0.5.0 also fixes libakgl defect 26, which was one of the two reasons src/sprite_akgl.c installs its own renderfunc: akgl_actor_render took its destination height from the sprite's width, drawing a 24x21 Commodore sprite as a 24x24 square. The renderfunc stays, because the other reason has not moved -- an actor carries one scalar scale and SPRITE has separate x- and y-expand bits -- but the comments and TODO.md deviation 40 no longer claim a defect that is fixed. Every documentation figure re-renders byte-identical under the new library, which is what says the sprite and drawing paths did not move underneath them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 08:01:43 -04:00
Tachikoma	a583fb4b77	Take libakerror 2.0.1, and guard the exit status it fixes ... 2.0.0 makes the error pool and the status registry thread safe, and it is an ABI break carrying the soname to libakerror.so.2. The break is a quiet one: __akerr_last_ignored became thread-local and akerr_next_error() now returns a context that already holds a reference, so objects compiled against a 1.x header and linked against 2.x count every reference twice and never give a slot back. Nothing about that fails to link, which is exactly what a guard is for -- include/akbasic/error.h feature-tests AKERR_THREAD_SAFE instead of AKERR_FIRST_CONSUMER_STATUS, which 2.0.0 also still defines and which therefore no longer distinguishes anything. 2.0.1 is the release this band needed most. The default unhandled-error handler ended in exit(errctx->status), and a process exit status is one byte: AKBASIC_ERR_BASE is 512, and 512 truncates to 0, so an unhandled AKBASIC_ERR_SYNTAX reported success to anything watching $?. Every other code in the band came out as some unrelated error's number. akerr_exit() substitutes 125 for anything a byte cannot carry, and a probe raising AKBASIC_ERR_DEVICE through FINISH_NORETURN now exits 125 rather than 7. It was latent here rather than live -- src/main.c handles the context and returns EXIT_FAILURE, and every test with a top-level ATTEMPT carries a HANDLE_DEFAULT -- but "no caller relies on it today" is not a property a header can keep true. tests/version_check.c asserts the mapping and fails if AKBASIC_ERR_BASE ever stops truncating to zero, because that is the day this stops being about our base. Chapter 10 gains a threading section: libakerror is safe from any thread now, and this interpreter is not and has no lock anywhere in it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 08:00:24 -04:00
Tachikoma	4affb02c20	Draw into the whole window, not its top-left 320x200 ... The graphics verbs documented a coordinate transform that did not exist. With SCALE off a coordinate went straight to akgl_draw_* as a pixel address, so an 800x600 window drew a C128 listing into its corner and left the rest unused -- while the chapter said coordinates were 320x200 and stretching to fit was the host's business. akbasic_GraphicsBackend gains a size entry point, require_graphics() asks it before every verb that draws so a resized window is honoured between two statements, and 320x200 becomes the fallback for a backend that leaves it NULL. It is the record's one optional member, so a host written against the old header keeps the behaviour it had. SCALE now maps onto the device, and RGR(1)/RGR(2) report the drawing surface so a program can use a window whose size it did not choose. RGR(0) is BASIC 7.0's own field, the GRAPHIC mode. SCALE also mapped xmax onto the width rather than onto the last pixel, so SCALE 1, 319, 199 followed by DRAW 1, 319, 199 drew nothing at all -- one pixel past the surface. Fixed in the same line, because it is what makes "SCALE gives a C128 listing the whole window" true rather than nearly true. The akgl test renders against a 128x128 target, deliberately smaller than the old constants: a SCALE still dividing by them misses it entirely rather than landing somewhere plausible. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-08-01 07:35:20 -04:00
Tachikoma	7c8c98fc8c	Split the documentation by who reads it ... README.md was 577 lines and answered four different questions at once: what the project is, how to build it, every verb and function in the language, and how to maintain the test harness. The verb and function lists had already been written a second time in docs/11 and docs/12, which is how a list of that size goes stale -- there is no way to notice the two have drifted apart. README.md is now 150 lines and holds only what somebody evaluating the project needs: what it is, the quickstart, why it was rewritten in C, the five rules embedding imposes on the design, the two ways to use it, and where everything else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md. The akbasic_TextSink struct moved to docs/10-embedding.md rather than being deleted. It was the corpus's only `c excerpt=` block -- the check that caught the stale struct two commits ago -- so dropping it with the README would have quietly retired a test. docs/10 also stopped claiming README.md carries the full API surface and the pool limits, which the trim made false. CLAUDE.md went from 458 lines to 62, because almost none of it was agent-specific. The project goals, the Go reference and its architecture, the dependency version and ABI rules, the four ways an embedded build collides, the libakerror convention, the error-code range map and the style rules are all things a maintainer needs, and they are now in MAINTENANCE.md with one copy to keep true. CLAUDE.md points there and keeps only the rules no test enforces: tests in the same commit asserting the correct contract, file a missing dependency capability upstream, do not edit generated output or tests/reference/, co-author your commits. Four claims did not survive the move, having gone stale where nothing could notice: - "The repository is currently empty apart from its submodules -- no commits, no source tree, no build files." There are 43 commits. - libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE) at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is gone; only a historical mention in a comment remains. - "akbasic_init() claims 512-767." There is no akbasic_init. It is akbasic_error_register(), called from akbasic_runtime_init(). - Time-relative phrasing ("libakgl hit two of them in the last week"). Five places pointed at CLAUDE.md for the range map or the file-it-upstream rule and now point at MAINTENANCE.md: include/akbasic/error.h, src/runtime_disk.c and three entries in TODO.md. Both source changes are comments. deps/libakgl/TODO.md cites it too and is left alone; it is a submodule, and the rule it quotes is still reachable from CLAUDE.md. ctest is green at 95 of 95, docs_examples included: 36 programs, 9 transcripts, 44 output comparisons, 3 C snippets, 1 excerpt. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 22:59:43 -04:00
Tachikoma	4e7d2cff6c	Finish the language: every remaining verb group, and the defects that blocked them ... Closes groups A, C, D, E, F, H and J of TODO.md section 4, plus RESTORE and RENUMBER, and closes section 6 -- all seventeen reference defects. Seven of those turned out to have been fixed or never ported and nobody had written it down; the audit records the evidence for each. Two of the seventeen were real. math_plus mutated its left operand when the operand was mutable, so A# + 1 could modify A#; it was gated on FOR/NEXT coverage because NEXT relied on the mutation, so tests/for_next.c came first and NEXT now writes the counter back itself. And the binary operators summed both numeric fields of their right operand, which no BASIC program can reach -- that one needed a test written against the value API. Writing the tests turned up eight defects nobody had listed. Seven are fixed: IF A = 2 THEN was a parse error; only == worked IF ... AND ... was a parse error, because a condition parsed as one relation IF A = 1 OR B = 2 THEN was silently always false, and so was IF A THEN EXIT before any NEXT restarted the program and exhausted the variable pool READ never found a DATA line above it, and swallowed the lines between PRINT 2 + 2 at the prompt was filed as program text instead of answering a short read discarded its bytes, so COPY produced empty files every verb taking an argument list said "peek() returned nil token!" on none The eighth is not fixed and cannot be quietly: a FOR whose step overshoots runs its body one extra time, and FOR I = 1 TO 1 runs it zero times. The two errors cancel for a step of 1, which is why neither was noticed. Correcting them changes the expected output of a checked-in acceptance file, and tests/reference/README.md forbids editing one to suit this interpreter. It is tests/for_semantics.c in AKBASIC_KNOWN_FAILING_TESTS, asserting the correct contract, and TODO.md items 19 and 20. Sprites are real libakgl actors with a renderfunc of their own, because akgl_actor_render draws every sprite square and an actor has no per-axis scale. Both are filed upstream. SPRSAV takes an image file, an SSHAPE handle or a 63-element integer array -- a string here cannot hold a zero byte. Verbs that need hardware that does not exist are refused by name with the reason rather than faked: SYS, HEADER, COLLECT, BACKUP, BOOT, FILTER, and DIRECTORY, which is refused for a missing libakstdlib wrapper filed upstream. 94 tests in the default build, 93 with SDL, 94 under ASan and UBSan, doxygen clean. The Go acceptance corpus stayed green throughout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 21:50:37 -04:00
Tachikoma	dff7f57e95	Own every pixel each frame, and bring the cursor back as a blinking block ... The blinking backspace was not the backspace. The sink skipped rows it believed were already clear, tracked in a drawn[] array, which assumes a frame inherits the frame before it. SDL_RenderPresent swaps buffers, so a frame inherits the one two back: a row erased once is clean in one buffer and dirty in the other, and presenting alternates between them. The first character of a backspaced wrap flickered forever. It reproduces on X11 and never under the dummy driver or a software renderer, which is why the suite stayed green through two rounds of fixing it. The sink now repaints every row it owns every frame -- a frame either owns every pixel it presents or inherits pixels it cannot reason about. Confirmed on real hardware with the reported input: the wrapped tail's row reads zero across five successive captures. The cursor returns as a blinking block, half a second per cycle, off SDL's clock. It sits in the cell after the text rather than under it, which is what made the underscore unreadable, and it wraps to the next row when a line exactly fills one -- where the next character actually lands. The new regression test paints stale pixels by hand, which is what a swapped-in buffer hands back, so the case is covered without real hardware. Every new assertion was checked by reverting the fix and watching it fail. Recorded honestly in TODO.md section 5: the same buffer swap means the graphics verbs were never reliable across frames either. A one-shot DRAW lands in one buffer and the next present shows the other. Making that work needs a persistent surface, which is its own commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 15:23:41 -04:00
Tachikoma	a69d28cbf7	Erase what the text layer drew: three GUI bugs, one cause ... The sink painted glyphs on top of whatever was already on the renderer and never erased anything, and the host deliberately does not clear the frame so a DRAW survives. The grid was always correct; the screen kept the previous frame. That surfaced as three separate-looking faults: - a backspaced character stayed on screen, including across a line wrap - a scroll left the old rows behind, "papered over with garbage" - the editing cursor smeared an underscore along every column it passed through, which read as an underline under the text being typed render() now fills each row it is about to draw, and each row that has emptied since it last drew, with the background first. Row by row rather than one clear over the whole area: the text layer is authoritative over the rows it occupies and leaves every other pixel alone, so a picture behind the text loses only the strips the text uses instead of all of it. echo_line() also truncates rows that hold nothing but the spaces its own erase pass wrote, which is what backspacing back across a wrap leaves behind. A row of spaces is text as far as render() is concerned, so it would have been repainted forever and kept erasing whatever was under it. The cursor glyph is removed outright, as asked. The smearing was the erase bug rather than the cursor, so one could come back and behave -- a block would read better than an underscore. Four pixel-level tests, because grid assertions could never have caught any of this. Each was checked by reverting the fix and watching it fail; two of them were vacuous when first written and are noted as such where they are fixed. The real-keyboard test also now rubs out a character and scrolls forty lines. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 15:03:37 -04:00
Tachikoma	b751c1b600	Consume libakgl 0.3.0: every workaround deleted, two capabilities gained ... 0.3.0 closed all ten API gaps this port had filed. The four workarounds go with them: the CMake block that declared libakgl's vendored dependencies by hand, the akgl/actor.h include in three files, and the six vtable pointers assigned by hand in two more, now akgl_render_bind2d(). Two gaps were capabilities rather than inconveniences, and both are now real: The line editor takes the composed UTF-8 text the ring carries in preference to the keycode, so shifted characters, keyboard layouts, compose keys and dead keys all work. A double quote can be typed, which means a BASIC string literal can be typed -- the sharp end of the old limitation. Letters are no longer folded to upper case. SOUND's dir/min/step reach akgl_audio_sweep instead of being refused. dir 3 sweeps once rather than oscillating and TODO.md section 5 says so. A backend with no sweep still refuses the swept note and plays the held one. The adaptors now carry an AKGL_VERSION_AT_LEAST(0, 3, 0) floor, verified by temporarily demanding 0.4.0 and watching it fire. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 13:25:14 -04:00
Tachikoma	7c7c15b80b	Implement the housekeeping verbs, and stop the REPL spinning after an error ... NEW, CLR, CONT, SWAP, TRON, TROFF and HELP. None is in the Go reference, so what each means here is recorded beside it. Testing CONT turned up a hang that predates this: the runtime's error class is deliberately sticky, and with run_finished_mode REPL every later step re-entered REPL and printed READY -- overwriting the QUIT that end of input had just set. An interactive session that hit one runtime error printed READY forever instead of exiting. RESTORE and RENUMBER are deferred with reasons; RESTORE turns out to need a DATA pointer this port does not have, which is a defect in its own right. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 12:07:50 -04:00
Tachikoma	4e98dba423	Give argument lists their own link, not each argument's .right ... An identifier's subscript list, a unary's operand and a binary's right-hand side all lived in the same field the argument chain used, so ABS(-9), MOD(A#, B# + 12) and any array reference in a parameter list were counted as extra arguments and refused. Subscript lists move to .expr and arguments now chain through a dedicated .next. This is the third time the same collision was fixed; the first two moved it along rather than removing it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 11:58:15 -04:00
Tachikoma	e7ef48f1ca	Add akbasic_runtime_global: a host variable lands in the script's root scope ... A host creating a variable while a script was suspended got it in whatever scope was active -- usually a FOR or GOSUB body -- and it died when the body popped, silently. Reaching for the root by hand returned NULL without raising, because environment_get only auto-creates in the active environment. Both are still true of environment_get, which is correct for what the interpreter uses it for. The README and the example now point somewhere else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 11:53:05 -04:00
Tachikoma	3edbf75547	Consume the COLON token: a line can hold several statements ... The token has existed since the scanner was written and nothing read it, so 10 PRINT A$ : REM ... was a parse error. Leading separators are consumed before each statement and an empty statement yields a NULL leaf rather than an error, so a trailing colon and a run of them are both legal. BASIC 7.0 scopes everything after THEN to the condition, which the reference had no opinion about because it never got here. The rule is not "skip when false": the rest of the line belongs to whichever arm was written last. A whole FOR/NEXT on one line still does not loop -- block skipping works by source line. Recorded in TODO.md as what group A has to fix first. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 11:46:10 -04:00
Tachikoma	2668e9f32b	Fix five defects the port uncovered in the reference parser and scanner ... Chained subtraction and exponentiation fold left instead of abandoning the rest of the line -- `1 - 2 - 3` gave -1 and dropped the `- 3`. A unary leaf's operand moves to .left, so a negative literal is one argument again and a second argument no longer overwrites it. An operator in a line's final column survives. Hex literals reach the parser whole. A leading zero is padding, not a radix. Item 16 stays pinned: the fix works and costs an upstream golden case, which is a decision rather than a defect. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 11:35:14 -04:00
Tachikoma	23dda12e24	Port the standalone SDL frontend, and give the sink a line editor ... An AKGL build of `basic` was a terminal program with unused SDL linked into it. It now opens the reference's 800x600 window, draws BASIC output in the Commodore font, pumps events, lets you type at it, and still mirrors every byte to stdout. The stdout mirror is a composing sink rather than a second write inside the interpreter, and lives in the core library where it needs no SDL. The line editor waits for a typed line by borrowing one frame at a time from the host, so nothing blocks and nothing owns an event loop it should not. The whole golden corpus now runs through the SDL binary as well as the stdio one, byte for byte. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>	2026-07-31 11:21:39 -04:00