kokkoja-rel/docs/guest.md

# 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.