"Drawing does not persist across frames; redraw it every frame" was the advice,
and it is not sufficient on its own. The host runs a fixed number of source
lines and then presents, and presenting discards the drawing buffer -- so a run
of drawing verbs longer than one budget is **torn**, not merely transient, and
an `SSHAPE` at the end of it captures only what was issued since the present,
over whatever the frame before left behind.
Measured against the standalone frontend's 256: after synchronising to a jiffy
edge, 220 lines of drawing survive a capture and 250 do not.
There is no fix available that does not change what a host owns -- the budget is
the host's and so is the present -- so this is documentation, in the three
places it belongs. Chapter 13 beside the note it qualifies, with the numbers.
Chapter 6 where `SSHAPE` is introduced, which is where a program meets it.
Chapter 14 from the step loop's side, naming `AKBASIC_FRONTEND_STEPS_PER_FRAME`
and explaining the one thing a script can do about it: `settime()` is called once
a frame, so `TI#` changes on the first step of a batch and nowhere else, and
spinning until it changes is the only frame synchronisation this dialect has.
**Untested, deliberately.** Reproducing it needs the real frontend, a clock and
a timing window, and a test that reproduced it would be reproducing a race.
Recorded in TODO.md rather than left looking like an oversight.
TODO.md section 9 item 5, struck as a documentation outcome.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Chapter 2 gets the rule and the refusal, chapter 4 gets the payoff for
LABEL, chapter 9 says DSAVE writes the numbers it handed out and to
RENUMBER first if you want gaps, chapter 10 shows a host loading numberless
source, chapter 13 gets the QuickBASIC-shaped divergence, and chapter 14's
source[] passage gets its second half.
Chapter 14 said "two prescans" and listed two; there were three before this
and there are four now, so it lists all four and says which of them reports
against the right line.
TODO.md section 6 records four things found on the way and deliberately not
fixed: set_label() filing into the active scope rather than the root, three
prescans reporting the wrong line number, duplicate written line numbers
still replacing silently, and renumber.c's file-scope scratch arrays.
examples/embed.c runs the same program twice, numbered and not, so the
example compiles the feature rather than describing it. Its header pointed
at ./build/examples/embed, which is not where the binary lands.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs/16-structures.md is the feature: records, nesting, copy-on-assign, strict
pointers, lists, what is checked and what is not, and how a host shares its own
C structs. Every example in it is executed by docs_examples and byte-compared,
including the refusals -- so a message that changes fails the suite rather than
quietly making the chapter wrong.
The chapter makes one contrast explicitly, because it is the question a reader
will actually have: a misspelled *field* is refused and a misspelled *variable*
still prints zero. The rule underneath is that what the program declared gets
checked and what it did not gets shrugged at -- a variable's name is never
declared, a TYPE's field list is. Structures end up the strictest thing in the
language, not from a higher standard but because they are the only named thing
whose valid spellings are written down.
Chapter 14 gains the layout: an instance is a contiguous run of value slots with
a diagram of where the fields sit, the three-pass prescan and why each pass
exists, why the copy cannot live in akbasic_value_clone(), and why the render
depth bound is four rather than eight. Chapter 3 gains the @ suffix, chapter 13
records that all of this is an addition BASIC 7.0 has nothing like, and the verb
reference gains TYPE, POINT and DIM ... AS.
MAINTENANCE.md gains the two rules that are on a maintainer rather than on a
test: a structure copy must not go through clone, and a field chain gets its own
leaf field. TODO.md section 5 records what was invented and the three limits
that are ours, and section 8 records the two defects the work exposed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Chapters 1 through 13 describe the language. Nothing described the machine
that runs it, and the answers were spread across header comments, TODO.md
sections written for a different purpose, and the source itself. Somebody
embedding the interpreter, debugging something it did, or adding a verb had
to reconstruct the shape from all three.
docs/14-architecture.md is that shape, and only that: the three targets and
the driver, the single akbasic_Runtime and why nothing is file-scope,
akbasic_runtime_step() unrolled with the reason each stage sits where it
does, the four modes and what set_mode() does beyond assigning, a line's
journey from text through tokens and leaves to a verb handler, the dispatch
table, the pool map with what each exhaustion actually says, environments
doubling as block state, the two kinds of error, devices, and interrupts.
It defers rather than restates. The headers are the authority on every
function's contract and the chapter says so up front; where a rule is subtle
the header comment already states it at more length than a chapter should.
MAINTENANCE.md keeps the conventions and now points here for the mechanism,
so there is still one copy of each.
Two sections are the reason it exists at all. Debugging: reading a TRON trace
as evidence about the loop rather than the lines, reading an akerror stack
trace and what it is not, four breakpoints and the expressions worth printing
at them, narrowing with ctest -R and the mock devices, and a symptom-to-cause
table. Changing it: the verb recipe end to end including the private
src/verbs.h prototype that is easy to miss, the rule that a missing
dependency capability gets filed upstream rather than worked around, and the
five constraints goal 3 puts on any change.
A `text` fence tag comes with it. Every fenced block in docs/ is executed and
an untagged one is a hard error, so six block diagrams had nowhere to live.
The tag means never executed, it is counted in the skip line like `cmake`,
and MAINTENANCE.md documents it -- the alternative was an indented block the
extractor never sees, and a picture nobody decided about is indistinguishable
from a test nobody ran.
tests/docs_examples.sh now makes --root and --basic absolute before it
starts. Both are used from inside a sandbox directory it cd's into, so the
invocation MAINTENANCE.md itself documents -- --root . --basic ./build/basic
-- failed every example with "exited 127" and every setup= with "setup
failed". CTest passes absolute paths and never saw it; running one document
by hand hits it immediately.
Writing the error section turned up a defect and TODO.md section 8 records
it. The ATTEMPT blocks that turn a script's mistake into an error line wrap
parsing and interpretation but not scanning, so a line with more than 32
tokens escapes as an interpreter error: stack trace, exit 1, and at a prompt
the REPL is gone. That is the same shape as section 8 item 2, on a path that
fix did not cover. Not fixed here -- it is a behaviour change and wants its
own tests -- but written down with the three call sites and what would cover
them.
Both configurations stay green: 95/95 and 94/94. docs_examples now runs 37
programs, 9 transcripts, 45 output comparisons, 3 C snippets, 2 excerpts and
2 shell blocks, and skips 9 text blocks.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
