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.

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 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, Notebooks, 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 a second and its explanation appears beneath it.

The page

The page is A4 in size, lying on its side, shown so that it fits the window. Write anywhere on it. When your writing comes near an edge, the page 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. A click on the page that only brings the browser window to the front, when you come back to it from another window, makes no mark.

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, a full A4 page filling the window, so that a page shrunk to a small exercise is seen at its own size 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.
• Expand, which only the host and co-hosts have, makes the page itself fill the window, for everyone, at the present zoom, in both directions. The page grows equally on every side, so nothing on it moves and nothing is rescaled; there is simply more room around it.
• 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 page 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.

Notebooks in the toolbar opens a chooser that shows your notebooks and small pictures of the pages kept in them, wherever they are kept. Rest the pointer on a page for a second and its facts appear: the first text on it, when it was last changed, who wrote on it, what is on it and the size of the page; on a notebook, how many pages it keeps and from when, when it was last written in, and where it is. There you can delete pages and notebooks you no longer want: mark them with the × at their left, then press Delete twice. In the browser a deleted page is gone for good; with the Kokkoja program it goes to the Trash. Starting a page for everyone from a kept page is the host's business, and a co-host's.

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 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, which everyone has, now also starts a new page for everyone from a page kept in one of your notebooks, with everything that was written on it: choose the page in the chooser. The kept page itself is not changed: the session works on a copy.
• 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.