Kokkoja: first public assembly

Assembled from the development repository by tools/make_release.sh.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs/guest.md

@@ -0,0 +1,244 @@
+# A guest's Kokkoja
+
+This part describes Kokkoja as a guest sees it: someone invited to a
+session by its host.  In a lesson, the guest is the student.  The host's
+screen is the same with a few more buttons, described in
+[A host's Kokkoja](host.md).
+
+## The invitation
+
+The host sends you an invitation by whatever means you both use: email, a
+chat message, a text message.  It is a link of this shape:
+
+    https://kokkoja.andykopra.com/#join=wss://kokkoja.andykopra.com/relay%23uQ5c__CGB4FvN64Qiv3jGA.aS_1O51Umk1YHXwgqBZANw
+
+The part after `join=` is the invitation itself, which the host's Kokkoja
+may also give you on its own, without the link around it.  Both forms
+work wherever an invitation is asked for.  The invitation carries the key
+that protects the session, so pass it on only to people who belong in the
+session, and treat it as you would a meeting link.  An invitation is good
+for one session: the host's next session has a new one.
+
+## Joining
+
+Open the link in a web browser.  Firefox, Brave and Chrome are known to
+work; other browsers built on the same engines very probably do.  You see
+Kokkoja's start screen with the invitation already filled in.  Enter the
+name the others should see and press **Join**.  That is all: nothing is
+installed, and there is no account to make.
+
+Your name is remembered by the browser for next time.  So is a second
+field, **Notebook for the pages of this session**, which you can leave as
+it is for now; what it does is explained under "Your notebook" below.
+
+If you have the Kokkoja program installed on your computer (see
+[A host's Kokkoja](host.md) for what that is and why you might want it),
+the start screen also offers to open the invitation in it instead.  If
+you have not, ignore that line.
+
+If the host has not started yet, or has left, you are still in the
+session.  The page is shared among whoever is present, and the host's
+place in it waits for the host to return.
+
+## The screen
+
+Across the top is the toolbar.  On the left are the tools and their
+settings; on the right, the zoom and, for the host, the buttons that
+start pages.  Below it, the page fills most of the window, with a panel on
+the right.  Every button explains itself: rest the pointer on it for a
+second and its explanation appears beneath it.
+
+### The page
+
+The page is an A4 sheet, shown so that it fits the window.  Write
+anywhere on it.  When your writing comes near an edge, the sheet grows in
+that direction, in small steps, so there is always room, and the view
+keeps its scale and extends beyond the window; scroll to reach the rest.
+An image the host puts on the page lies at the top, or below the images
+already there.
+
+The page as a whole is shared: everyone sees the same marks in the same
+places.  Your view of it is your own: how far it is zoomed and where it
+is scrolled to concern nobody else.
+
+### Pen
+
+**Pen** is chosen when you arrive.  Draw with a pen on a tablet, a mouse,
+or a finger on a touch screen.  With a pen, pressing harder makes the
+line wider.  The colours are to the right of the tools: black, blue, red
+and green, and **+** opens a palette of more.  A colour chosen from the
+palette joins the row of colours and stays there in this browser.  The
+three lines to the right of the colours are the line widths: 0.4, 0.7
+and 1.2 mm at ordinary pressure.
+
+If a pen is in use, a hand resting on a touch screen is ignored.
+
+### Text
+
+**Text** types on the page.  Tap where the text should begin and type; a
+text field appears there and the text is laid out on the page as you
+type.  Enter begins a new line.  Press Escape, or tap somewhere else, to
+finish; a block with nothing in it disappears.
+
+A block made by a tap does not wrap: its lines are as long as you type
+them, and the page grows to hold them.  To make the text wrap at a chosen
+width, drag along where its top edge should run instead of tapping: the
+block begins at the left end of the drag and wraps at the right end.
+
+Tap your own text to change it.  While a block of yours is being edited
+it is drawn grey, and three handles appear: the one at its top-left
+corner and the line along its top edge move it, the one at the right end
+of that line changes its width.  You cannot change anyone else's text.
+
+With the Text tool, the row of colours stays and the line widths give way
+to the font, one of **Sans**, **Serif** and **Mono**, and the size in
+points, 14 unless you change it.  Both apply to the block you are typing
+and to the next ones.
+
+### Eraser
+
+**Eraser** removes your own writing.  Move it across a stroke and the
+whole stroke goes; across a text block and the block goes.  It removes
+nothing of anyone else's, and nobody else's eraser can touch yours.  An
+erased stroke is gone from the page for everyone.
+
+### Zoom
+
+**Fit** shows the whole page in the window, and keeps doing so as the
+page grows by writing, except while you are in the middle of a stroke of
+your own.  **+** and **−** zoom in and out by a tenth.  Holding Ctrl and
+turning the scroll wheel zooms about the pointer.  When the page is
+larger than the window, scroll it as you would any page.  When the host
+adds an image, the view keeps its scale rather than shrinking to fit; a
+new image at the bottom of a long page is reached by scrolling.
+
+If you reload the browser tab, it comes back to the page as you last saw
+it: same zoom, same place.
+
+### The panel
+
+**Participants** lists everyone in the session, with *you* and *host*
+marked, and *away* beside anyone who has left or lost their connection;
+an absent participant's writing stays on the page.  The box in front of
+each name shows or hides that participant's writing on your screen alone.
+Hiding your teacher's corrections to try an exercise again, or hiding
+your own answers to see the exercise as it was, changes nothing for
+anyone else.
+
+**Invitation** shows the invitation of this session, with a button to
+copy it, in case someone else should be invited.
+
+**Current notebook**, **Keep page** and **Export** concern your notebook,
+below.  Under them, a line reports what was last saved, and whether
+anything went wrong.
+
+The last line of the panel reports what your pen or mouse is delivering:
+the kind of device, the pressure, and how many positions per second it
+sends.  It is there for curiosity and for finding faults.
+
+### Status
+
+At the right end of the toolbar, **Page 3** is the number of the page you
+are on, counted from the start of the session, and beside it *Connected*,
+*Connecting…* or *Disconnected* says how you stand with the relay.  If
+the connection drops, Kokkoja reconnects by itself; what you wrote while
+disconnected is sent when it returns.  Until the host has started a
+page, the toolbar says *Waiting for the host's page*.
+
+## Your notebook
+
+Every page of the session is saved for you, as it changes, without your
+doing anything.  Where it is saved depends on how you joined.
+
+### In the browser
+
+When you joined by opening the link, your notebook is kept inside the
+browser, on the computer you are using.  It stays there between sessions,
+but it belongs to that browser: another browser, or another computer,
+has its own.  The page you are on is saved there continuously.  When the
+session moves to another page, the page you are leaving is kept under a
+dated name, such as `2026_10_06_01.svg`, the date being the day it was
+last changed and the number counting the pages kept that day.
+
+Two buttons bring pages out of the browser:
+
+* **Keep page** keeps a dated copy of the page as it is now, and
+  downloads it, so you find it among your browser's downloads.  Pressing
+  it again before anything has changed makes no second copy.
+* **Export** downloads a picture of the page as you see it, as a PNG
+  file; writing you have hidden is left out.  Its name is the date and
+  the page number.
+
+A page file is an SVG file.  Any web browser displays it, and vector
+drawing programs such as Inkscape open it.  Kokkoja itself can load one
+again, writing and all, when someone with the right to start pages
+chooses it (see "When the host gives you more" below, and the host's
+part).
+
+The notebook field on the start screen names the notebook within the
+browser's storage.  Giving each course or each colleague a notebook of
+their own keeps their pages apart; the name proposed is simply
+*Notebook*.  **Current notebook** in the panel shows the notebook in use
+and lets you change it during the session.
+
+### On your computer
+
+If you would rather have your pages as files in a directory on your own
+computer, where you can open, copy and back them up as you do any file,
+install the Kokkoja program.  It is small and needs only Python, which
+Linux and macOS have or can quickly get; [A host's Kokkoja](host.md)
+tells how, since every host needs it.  Then join from the program's own
+start screen, pasting the invitation, or follow the start screen's offer
+to open the invitation in the installed program.
+
+With the program, a notebook is a directory in `Kokkoja` in your
+Documents directory.  The page you are on is `Current.svg` there, and
+kept pages lie beside it under their dated names.  **Keep page** makes
+the dated copy; **Export** opens Kokkoja's own file chooser, in which you
+pick a directory and a name for the PNG file.
+
+The program also keeps your identity, so that you are the same
+participant in every session and from any browser on that computer, and
+writing from an earlier lesson is still yours when its page is loaded
+again.  In the browser, your identity belongs to that browser.
+
+## Leaving and returning
+
+Close the tab and you have left.  Nothing needs saving.  If you come back
+to the same session by opening the invitation again, your writing is
+still on the page, from the others' copies and from your notebook, and
+it is still yours to erase or change.  A tab that was in a session and is
+reloaded goes straight back in.
+
+## When the host gives you more
+
+Normally only the host puts images on the page, starts new pages, or
+loads pages from a notebook.  The host can give you the same right, for
+instance in a discussion among colleagues where everyone brings
+material.  When that happens, three more buttons appear at the right of
+your toolbar:
+
+* **New** starts a new blank page for everyone.  The page being left is
+  kept in each person's notebook.
+* **Image** puts an image file on the page for everyone, below any
+  images already there.  Your browser's file chooser asks for the file
+  (with the Kokkoja program, Kokkoja's own chooser does, beginning where
+  the notebooks are, with a choice whether an image wider than the page
+  is shrunk to fit it).  A PNG or JPEG file keeps its exact pixels unless
+  it is very large; other formats and very large images are converted
+  and reduced before they are shared.  An image is placed at its natural
+  size, centred, 8 mm from the top or from the image above; one wider
+  than the sheet is scaled down to fit between the margins.  To put an
+  image on a page of its own, press **New** first.
+* **Notebook** starts a new page for everyone from a page kept in one of
+  your notebooks, with everything that was written on it.  A chooser
+  shows your notebooks and small pictures of their kept pages.  The kept
+  page itself is not changed: the session works on a copy.
+
+An image cannot be moved or removed once anyone has written on it or
+added anything after it, since the marks on it would make no sense
+without it.  The one exception is a mistake caught at once: the person
+who added an image can take it back with a tap of the eraser on it, as
+long as nothing else has happened on the page since.
+
+The right stays with you until the host withdraws it or the session ends.