Give the screen back: osTakeScreen, and the RAM disk earns its keep

A program that takes the whole screen leaves the shell a blank one, and
whatever was on it is gone. There was nowhere to put 48K of video memory on
a machine with 64K of Data Memory that CosmOS already lives in.

A DRIVE MADE OF MEMORY IS SOMEWHERE. The screen goes to a file on the
scratch drive - the first volatile drive found at boot - like any other
file, and comes back from handleExit alongside the vectors and console mode
already put back there. The filesystem does the allocating, so this
invented nothing: it is 196 pages of tiles, map and palette, with a block
on the front holding the cursor, the four scroll registers and the mode.

NOT AUTOMATIC, and that is the whole design. Saving on every program start
would be cheap enough; restoring on every exit would be wrong, because dir
and Files and Say print and stop and their output is the reason you ran
them. A program says it took the screen, and one that says nothing behaves
exactly as every program did before this existed.

It deleted thirty lines of Grid, and they were all wrong anyway: four
scroll registers put back by hand, the map filled with spaces, the cursor
sent home, palette bank 0 written out - and the other fifteen banks kept
Grid's colours, because there was nowhere to have kept the real ones. Grid
is 64 bytes smaller and gives back what was actually there.

The check compares the screen before against the screen after, CELL BY
CELL, and allows only the rows around the cursor to differ - found from
where the text ends rather than guessed at, because the first version
assumed the cursor was near the bottom of the screen and let three real
differences through.

Two things cost time and neither was the feature:

  - An edit adding "SWI osTakeScreen" to Grid was in the same script as a
    failing s.index, so the file was never written - and the COMMENT
    describing the call did land, from a later edit. Grid documented a call
    it did not make, and read as though it should have worked.
  - docs.sh caught osTakeScreen having no row in the services table, which
    is the check the service layer added for exactly this and the second
    time it has earned itself.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW

Programs/CosmOS/README.md

@@ -870,6 +870,36 @@ too, and that is no use on a disk which has not got one. The directory is sixtee
 names, chosen rather than worked out: a scratch disk runs out of names long before it runs out
 of room, and this machine cannot divide.
 
+### Giving The Screen Back:
+
+A program that takes the whole screen leaves the shell a blank one, and whatever was on it -
+the listing you were reading, the error you were about to act on - is gone. There is nowhere
+to put 48K of video memory on a machine with 64K of Data Memory that CosmOS is already living
+in.
+
+**A drive made of memory is somewhere.** `SWI osTakeScreen` says *"I am about to use the whole
+screen, and would like what is on it now put back when I exit."* The system writes video
+memory to a file on the scratch drive and restores it from `handleExit`, alongside the vectors
+and console mode it already puts back. Q is zero if that was arranged; a machine with no
+volatile drive says no, and **a program told no should carry on regardless**, because it was
+going to before this existed.
+
+**It is not automatic, and that is the point.** Saving on every program start would be cheap
+enough, but restoring on every exit would be wrong: `dir`, `Files` and `Say` print and stop,
+and their output is the reason you ran them. A program that says nothing behaves exactly as
+every program did before this existed.
+
+**Tiles, map and palette all go** - 196 pages, and a block on the front holding the cursor,
+the four scroll registers and the mode. The map's off-screen rows are the console's
+scrollback; the tiles are the font, which a program that redefines one has overwritten; and
+the palette is where the console's own colours live. `Grid` used to give back the map and not
+the colours, and handed the shell green text on a blue ground.
+
+It also replaced thirty lines of `Grid`: four scroll registers put back by hand, the map
+filled with spaces, the cursor sent home, and palette bank 0 written out - all of which was
+*still* wrong, because the other fifteen banks kept `Grid`'s colours and there was nowhere to
+have kept the real ones.
+
 ### Where A Program Is Looked For:
 
 Three places, tried in order:
@@ -939,6 +969,7 @@ Those numbers are written down once, in `Programs/CosmOS/Source/services.asm`, w
 | osPrintNumber | A and B together are a number. Prints it in decimal, without leading zeroes. |
 | osBreak | Stops the program, shows every register as it had them, waits for a key, and carries on. |
 | osLastStatus | Q answers what the last program exited with: 0 it did what it was asked, 1 it did not, 2 it was asked wrongly. A program may give its own meanings if it says so. |
+| osTakeScreen | Says this program is about to use the whole screen and would like what is on it put back when it exits. Q is zero if that was arranged; anything else means it was not, which is the ordinary answer on a machine with no volatile drive. See Giving The Screen Back. |
 | osBootState | Q answers how the last start went: 0 settled, 1 trying, 2 fell back. A machine with no disk answers settled, because there is nothing there to be unsettled about. |
 | osBootSettle | Puts it back to settled, which is how a machine that fell back is told the situation has changed. Q is zero if the disk took it. **Settling is the only write a program gets** - marking a start as trying or fallen back is the loader's business, and a service that let a program claim either would let it lie about something the loader cannot check. |