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.  A host in the same room may
instead show you the link as a QR code on their screen: point your
phone's or tablet's camera at it and open the link it offers.  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 on a
computer, and Safari on an iPad or an iPhone, are known to work; other
browsers built on the same engines very probably do.  You see
Kokkoja's start screen, headed "Join a session", 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.  (Opened without an invitation, the same screen also offers to
start a session of your own; an invitation is a request to join one
session, so with one it offers joining alone.)

Your name is remembered by the browser for next time.  So is a second
choice, **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, one row holding everything in three
groups: on the left the tools, their settings and **Undo**; in the
middle the page and the view; on the right the host's page buttons,
your notebook, and **Session**, which opens a window with the
participants and the invitation.  Below it the page has the whole width of the window.  Every button
explains itself: rest the pointer on it for two seconds and its
explanation appears beneath it.

### The page

The page is an A4 sheet lying on its side, 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, red,
green, blue and white, and **+** opens a palette of more, in which the
colours already in the row leave their places empty.  A colour chosen
from the palette joins the row and stays there in this browser.  White
is for painting over.  The four lines to the right of the colours are
the line widths: 0.4, 0.7, 1.2 and 2.4 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.  You need not finish to
move a block: rest the pen on it while typing, and it follows the pen,
field and all; lift, and go on typing.

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; a red corner mark of 5 mm at its
top left shows where it begins.  To make a *text rectangle*
instead, drag it open where you want it: a red box, white inside, in
which the text wraps at the box's width, and which grows downward by
lines when you type more than it holds.  The box is part of the page,
seen by everyone, and where it lies over an image it covers the image
and nothing else; a teacher uses one to say "write your answer here".

Tap your own text to change it, anywhere in a box, and the cursor is at
the end of the text.  To move a block of yours, rest the pen
on it, without moving, for a little over half a second: a green outline
appears, and it follows the pen.  To resize a text rectangle, rest the
pen near one of its corners and drag the corner; the text wraps anew at
the new 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, until you undo the
erasure.

### Undo

**Undo**, the last button of the drawing tools, takes back your latest mark: a
stroke, what one movement of the eraser removed, a text block as you
last typed or moved it, a Hide rectangle made, moved or removed.  Press
it again for the mark before that, and so on back to the beginning of
the page.  Ctrl+Z (Command+Z on a Mac) does the same, and so do two
quick taps of the Eraser on empty paper, away from anything the eraser
would remove; a tap that erases something is never half of such a
double tap.  Undo acts only on your own marks, since nobody can change
anyone else's, and only on marks made on this page since you opened it:
after a reload of the tab, or on a page loaded from a notebook, there is
nothing to undo although the marks are there.  The button is grey when
there is nothing to undo.  An image cannot be undone; put it back with
**Image** if a tap of the eraser removed it by mistake.

### The view

A page is shown whole when you first see it.  Afterwards the view keeps
its scale: when the page grows, or the host adds an image, the page
extends beyond the window and you scroll to the rest.  Three buttons and
two gestures change the view, and none of them changes the page:

* **Fit** shows the whole page in the window.
* **A4** shows the page at the scale a new page has, one A4 sheet
  filling the window, so that a page shrunk to a small exercise is seen
  at its size on the sheet rather than enlarged to fill the window.
* When the host presses **Fit** or **A4**, every participant's view
  follows, each in their own window.  Your own Fit and A4 change only
  your screen.
* **Widen**, which only the host and co-hosts have, makes the page
  itself wider, for everyone, until it fills the
  window at the present zoom.  The sheet grows equally on both sides,
  so nothing on the page moves and nothing is rescaled; there is simply
  more room at either side.
* **Shrink**, also for the host and co-hosts, makes the page, for everyone, just large enough for what is on it,
  with the usual margin around.  Nothing on it moves either.
* **Extend** is a box, ticked to begin with.  Ticked, the sheet grows
  when your writing comes near an edge, so there is always room.
  Unticked, your writing stops short of the edge; a stroke that leaves
  the page resumes when the pen comes back.  Images always get the room
  they need.
* Hold **Ctrl** (Command on a Mac) and turn the scroll wheel to zoom in
  and out about the pointer.
* Hold **Ctrl** (Command on a Mac) and draw a stroke with the pen: up
  zooms in, down zooms out, by twice for every 100 pixels of movement,
  about the point where the pen touched down.  Nothing is drawn while
  the key is held.

If you reload the browser tab, it comes back to the page as you last saw
it: same zoom, same place.

### Session

**Session** in the toolbar opens a window with the people and the
invitation.  **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 and, below, as a QR code for a camera, in case someone else
should be invited.  **Log** is a record of what happened in this
session, pages and connection and every press and release of the pen,
with a button to copy it: if something goes wrong, copy it and send it
to whoever looks after Kokkoja.  Above it the window says which page
you are on, counted from the start of the session, how you stand with
the relay, and when the page was last saved; below it, where your
notebooks are kept.

### Notices

While all is well Kokkoja says nothing.  When there is something to
know, a line appears between the toolbar and the page: in red while
a problem lasts, in grey for a few seconds after something was done.
*Not connected. Reconnecting…* means the relay cannot be reached;
Kokkoja reconnects by itself, and what you wrote meanwhile is sent when
it returns.  *The page could not be saved* means the notebook is out of
reach; the page is still in memory and the saving is tried again.
*Waiting for the host's page* means the host has not started a page
yet, or your connection is down.  The grey notices say that a page was
kept or exported, and where.

For finding faults, the browser's console (F12) keeps a short log of the
session's events: pages, images, the connection, and what your pen or
mouse delivers.

## 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** 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 and no
  second download.  Any mark counts as a change, even a dot from a
  stray touch of the pen.
* **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 the host or a co-host chooses it (see "When the host gives you more" below, and the host's
part).

The notebook list 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; until you make one, everything goes
into the notebook *General*.  The last entry of the list, **New
notebook…**, asks for a name and makes a notebook of that name; it
exists from the moment a page is written into it.  **Current notebook**
in the toolbar is the same list, and lets you change notebook, or make
one, 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.  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** 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 makes you a co-host

Normally only the host puts images on the page, starts new pages, or
loads pages from a notebook.  The host can make you a *co-host*, which
gives you the same powers, for instance in a discussion among
colleagues where everyone brings material.  The Session window then
says *co-host* beside your name, and 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).  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, 5 mm below the image above or at the top of the page;
  one wider than the page widens it.  To put an image on a page of its
  own, press **New** first.
* **Notebooks** 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.  The same
  chooser deletes pages and notebooks of yours, marked with their ×
  and then the **Delete** button, pressed twice; the host's part says
  more.
* **Hide**, among the tools, hides part of the page for everyone: drag
  open a rectangle and whatever lies under it, writing included, is
  covered in white, marked by blue corners so that nobody writes there
  unknowingly.  Rest the pen on it to move it, near a corner to resize
  it; a tap of the eraser removes it and uncovers what was there.  A Hide
  stays even for someone who hides your writing on their own screen.

As a co-host you can also move and scale images, as the host can: rest the pen on an image for a little over half a second
and it follows the pen; rest it near a corner and the corner follows,
the shape kept.  Writing stays where it is, so images are arranged
first and written on afterwards.  A new image always arrives below the
others, centred, at its own size, to be arranged by hand.  A tap of the
eraser on an image removes it; writing on it stays.  An image you added
yourself you may always remove, even after you have stopped being a
co-host.

You stay a co-host until the host decides otherwise or the session ends.