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>

docs/06-graphics.md

@@ -180,10 +180,29 @@ it off and coordinates go back to being window pixels.
 
 `RGR(0)` is the current `GRAPHIC` mode. `RGR(1)` and `RGR(2)` are the drawing
 surface's width and height in pixels — those two are ours rather than 7.0's, and they
-are what a program needs to use a window whose size it did not choose. All three
-refuse when there is no graphics device, except `RGR(0)`, which is a mode this
+are what a program needs to use a window whose size it did not choose. They
+refuse when there is no graphics device, unlike `RGR(0)`, which is a mode this
 interpreter recorded rather than a screen it has to go and measure.
 
+**`RGR(3)` and `RGR(4)` are a character cell's width and height**, also ours. They come
+from the *text* device rather than the graphics one — a character grid belongs to the
+sink — so they refuse by naming that instead. Between them and
+[`RWINDOW`](12-function-reference.md), which gives the current text window in columns
+and rows, a program can place a character and a sprite at the same spot without
+hardcoding a number measured against whatever font the host loaded:
+
+```basic requires=akgl
+10 CW# = RGR(3)
+20 CH# = RGR(4)
+30 COL# = 12
+40 ROW# = 3
+50 CHAR 1, COL#, ROW#, "X"
+60 MOVSPR 1, COL# * CW#, ROW# * CH#
+```
+
+`RWINDOW` follows a `WINDOW` call, because it reports the window. `RGR(3)` and `RGR(4)`
+do not, because windowing does not change how big a character is.
+
 ### WIDTH
 
 `WIDTH 1` or `WIDTH 2` sets how thick a drawn line is. A thick line is drawn as

docs/10-embedding.md

@@ -115,6 +115,7 @@ typedef struct akbasic_TextSink
     akerr_ErrorContext AKERR_NOIGNORE *(*clear)(struct akbasic_TextSink *self);
     akerr_ErrorContext AKERR_NOIGNORE *(*moveto)(struct akbasic_TextSink *self, int col, int row);
     akerr_ErrorContext AKERR_NOIGNORE *(*window)(struct akbasic_TextSink *self, int left, int top, int right, int bottom);
+    akerr_ErrorContext AKERR_NOIGNORE *(*grid)(struct akbasic_TextSink *self, int *columns, int *rows, int *cellw, int *cellh);
 } akbasic_TextSink;
 ```
 
@@ -122,6 +123,12 @@ typedef struct akbasic_TextSink
 supplies its own and draws into a text layer. `readline` is expected to set `*eof` rather
 than block — that is how `INPUT` behaves sanely inside a frame.
 
+**The last three are optional and may be NULL**, which is how `CHAR`, `WINDOW` and
+`RWINDOW` know to refuse by name rather than pretending. Supply `grid` if your text layer
+has a character cell: it is the only way a script can find out how big one is, and
+without it anything placing a character and a sprite at the same spot has to hardcode a
+number measured against your font.
+
 `akbasic_sink_init_tee()` also ships, and composes two sinks into one: writes go to both,
 and `readline` comes from whichever of the two you name as the reader. That is how the SDL
 build puts `PRINT` in a window *and* on stdout. It needs no SDL, so you can use it to log a

docs/12-function-reference.md

@@ -25,8 +25,9 @@ so a call with the wrong number is a syntax error rather than a surprise.
 | `POINTER` | 1 | `POINTER(V)` | The address of a variable's value. |
 | `POINTERVAR` | 1 | `POINTERVAR(V)` | The address of the variable structure itself, metadata included. |
 | `RAD` | 1 | `RAD(n)` | Degrees converted to radians. |
-| `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), or the drawing surface's width (1) or height (2) in pixels. |
+| `RGR` | 1 | `RGR(f)` | The `GRAPHIC` mode (0), the drawing surface's width (1) or height (2) in pixels, or a character cell's width (3) or height (4). |
 | `RIGHT` | 2 | `RIGHT(A$, n)` | The rightmost `n` characters. Clamped. |
+| `RWINDOW` | 1 | `RWINDOW(f)` | The current text window's rows (0) or columns (1). Field 2 is a C128 screen mode and is refused. |
 | `RSPCOLOR` | 1 | `RSPCOLOR(n)` | One of `SPRCOLOR`'s two shared registers, 1 or 2. |
 | `RSPPOS` | 2 | `RSPPOS(n, f)` | A sprite's x (0), y (1) or speed (2). |
 | `RSPRITE` | 2 | `RSPRITE(n, f)` | One of a sprite's `SPRITE` settings, in `SPRITE`'s argument order. |

docs/17-tutorial-breakout.md

@@ -53,24 +53,24 @@ with it. That is Chapter 18.
 ## Step 2: Measure the screen once, at the top
 
 ```basic norun
-CW# = 16
-CH# = 16
+CW# = RGR(3)
+CH# = RGR(4)
 SCW# = RGR(1)
 SCH# = RGR(2)
-COLS# = SCW# / CW#
-ROWS# = SCH# / CH#
+COLS# = RWINDOW(1)
+ROWS# = RWINDOW(0)
 ```
 
-`RGR(1)` and `RGR(2)` are the window in pixels — see
-[Chapter 6](06-graphics.md#rgr) — and the game asks for them rather than assuming 800 by
-600, so it survives a host that opens a different window.
+Six numbers, none of them assumed. `RGR(1)` and `RGR(2)` are the window in pixels,
+`RGR(3)` and `RGR(4)` are one character cell, and `RWINDOW` gives the text grid in
+columns and rows — see [Chapter 6](06-graphics.md#rgr). Everything below is derived from
+these, including the ball's speed relative to the wall, so the game fits whatever window
+the host opened and whatever font it loaded.
 
-**The cell size is a constant and has to be**, which is the one thing here you cannot
-derive. `WINDOW` knows the grid, but the standalone frontend's tee sink never offers it
-(`TODO.md` §9 item 3 again), so a program has no way to ask. 16 by 16 is the bundled
-C64_Pro_Mono at 16 points. Change the font or the point size and change these two with
-it; everything below is derived from them, including the ball's speed relative to the
-wall.
+**The listing in `examples/` still has `CW# = 16` written out**, measured by hand against
+the bundled C64_Pro_Mono at 16 points, because when it was written a program had no way
+to ask — and it was the one thing in it that would break on a different font. That is
+what `RGR(3)` and `RWINDOW` are for; `TODO.md` §6 item 31 is the history.
 
 Lay the rest of the geometry out in the same block — the wall in cells, the play area in
 pixels: