diff --git a/docs/backlog.md b/docs/backlog.md index 3564ff7..5a8136f 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -1,9 +1,11 @@ # Backlog — 0.3.0 and later Recorded after hands-on testing of 0.2.6.1 in September 2026. **None of -this is in 0.2.6.2 or 0.2.6.3**: 0.2.6.2 is limited to picture printing, -the Presentations memory failure and the settings lockdown, and 0.2.6.3 -to the black-and-white preview and Print image. Each item says what was +this is in 0.2.6.2 to 0.2.6.4**: 0.2.6.2 is limited to picture printing, +the Presentations memory failure and the settings lockdown, 0.2.6.3 to +the black-and-white preview and Print image, and 0.2.6.4 to temporary +workspace restore (the two items that were here about links and sign-in +retention are answered in wonder-ink.md). Each item says what was observed, so whoever picks it up starts from the evidence. ## Wonder Ink @@ -34,19 +36,20 @@ observed, so whoever picks it up starts from the evidence. once Wonder Ink closes — there is no clipboard manager in the session. Measured, and judged smaller than leaving the picture there. - **A speaker on the tab that is playing sound** (`QWebEnginePage.recentlyAudible`). -- **Linked lesson text opens an intermediate popup** instead of following - the link, where Chrome follows it directly. Investigate: probably a - site script choosing `window.open` for a gesture Wonder Ink reports - differently, or `createWindow` being asked for a popup type we treat as - a tab. -- **Session retention.** Today closing Wonder Ink signs the teacher out - (session-only cookies). Wanted: recover from an accidental close, but - expire after a configurable period of inactivity, including across - restarts. Needs a design that never leaves one teacher signed in for - the next — and first, a real account to measure where the site keeps - its sign-in: 0.2.6.1 found cookies do clear on close, but the profile's - Local Storage persists, and whether the site stores its token there has - never been tested. +- **A picture in its own tab, in a room above 100%** (seen testing + 0.2.6.4). Page zoom is the room's `UI_SCALE`, and the engine's picture + viewer takes it too, so at 200% a slide opened from a lesson is shown + twice its size with scrollbars rather than fitted to the window, as + Chrome shows it. Printing is unaffected. +- **Staying signed in, if WonderInk ever issues a real session token.** + Today its sign-in is the teacher's email and password in a Basic-auth + cookie (measured, 0.2.6.4), so keeping it would mean keeping a password; + Wonder Ink does not. Worth asking WonderInk for a server-issued token + that can be revoked; until then, closing Wonder Ink signs the teacher + out, and only the recent tabs come back. +- **Workspace time as a room setting**, if two hours turns out wrong for + some room: `IDLE_LIMIT_SECONDS` in `classroom_wonderink_workspace.py` is + the one place, and a device.conf key would be a small change. - **The site's sluggishness, where it is ours.** Measured in 0.2.6.1: Wonder Ink and Chrome take the same time (about 2.9 s cold) and the site is the weight — 119 – 160 requests, 3.2 MB, the Google Maps API diff --git a/docs/manual/50-wonderink.md b/docs/manual/50-wonderink.md index 8232ccd..f30e6e2 100644 --- a/docs/manual/50-wonderink.md +++ b/docs/manual/50-wonderink.md @@ -61,14 +61,28 @@ the lesson. **Cancel** prints nothing. ## Worksheets and colouring pages Click the worksheet link in the lesson. It opens in a new tab, ready to -read or print. A worksheet's own **−** and **+** at the top of the page -make it bigger or smaller. +read or print. Any other link in a lesson — a slide, a picture, a video — +also opens in a new tab with one click, and Wonder Ink shows it straight +away; the lesson stays open in its own tab. A worksheet's own **−** and +**+** at the top of the page make it bigger or smaller. Worksheets you download are kept separately from everything else on the computer, so they never get mixed up with anything. +## If Wonder Ink closes by accident + +Open it again. If you used it in the last two hours, **your recent tabs +come back** — the slides, pictures and worksheets you had open, in the +same order. Wonder Ink's own lesson tab comes back at the sign-in page: +sign in again and open your lesson. + +Your password is never kept. After two hours that nobody has used Wonder +Ink, it forgets the tabs and the next person starts with a fresh Wonder +Ink. + ## When you have finished **Close Wonder Ink at the end of your session.** Closing it signs you out, so the next teacher in this room starts with their own account and -not yours. +not yours. Your recent tabs are kept for two hours in case you need them +again, but never your sign-in. diff --git a/docs/screenshots/README.md b/docs/screenshots/README.md index 3e8afa4..52ee258 100644 --- a/docs/screenshots/README.md +++ b/docs/screenshots/README.md @@ -159,6 +159,7 @@ Under the lab's real Plasma session, driven with the pointer. See | `pic-preview-default`, `pic-preview-half-topleft` | a picture in a tab of its own, laid out on Letter: as large as fits, then 50% top left (0.2.6.2) | | `print-image-menu` | right-click on a picture inside a lesson: **Print image…** and **Print page…**; on the words there is only Print page (0.2.6.3) | | `print-image-bw-half-topleft` | Print image on a signed-in picture, 50% top left, Black and white — the preview grey, as the job CUPS kept was (0.2.6.3) | +| `workspace-restored` | Wonder Ink reopened after an accidental close: the lesson's WonderInk tab at its sign-in page, its slide in front, its PDF behind (0.2.6.4, the real site) | ## Failures, kept diff --git a/docs/screenshots/workspace-restored.png b/docs/screenshots/workspace-restored.png new file mode 100644 index 0000000..2235a2d Binary files /dev/null and b/docs/screenshots/workspace-restored.png differ diff --git a/docs/testing.md b/docs/testing.md index f2e3ec1..cf731fc 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -575,14 +575,14 @@ ifupdown stanza is already gone. **Do not run `--adopt` on it.** still reports `yes` - [ ] The laptop still reconnects after a reboot -## Wonder Ink — 0.2.6.1 to 0.2.6.3, before any goes to stable +## Wonder Ink — 0.2.6.1 to 0.2.6.4, before any goes to stable Everything below was done in the lab except what a lab cannot do: paper, a classroom's own graphics, a real keyboard, its network and its screen. Those are these checks. Stable stays on 0.2.2 until they pass. Before starting, on each machine: `dpkg-query -W ekklesia-classroom` -must say `0.2.6.3`, which carries everything 0.2.6.1 and 0.2.6.2 did. The desktops only get it once stable is moved, so on +must say `0.2.6.4`, which carries everything 0.2.6.1 to 0.2.6.3 did. The desktops only get it once stable is moved, so on a desktop install it by hand for the test: ``` @@ -692,12 +692,41 @@ classroom-wonderink --diagnose with a driver named above points at the network - [ ] `free -m`: Wonder Ink needs about 610 MB plus 115 MB per extra tab -### Signing out +### Temporary workspace restore (0.2.6.4) — Little Waders -- [ ] Sign in, close Wonder Ink, open it again → **signed out**. (Cookies - are session-only and measured so; the site's Local Storage is not - cleared, which is the one way this could fail and has never been - tested with a real account) +Use a **Viewer** account. An Admin sees lessons in WonderInk's editor, +where a click on a link shows its Edit/Unlink bubble — WonderInk's design, +not Wonder Ink's; Ctrl+click opens it. See wonder-ink.md, *Links in a +lesson*. + +1. [ ] Sign in to the real WonderInk site +2. [ ] Open three lesson/resource tabs: the lesson, and two of its links — + for example *Saul Welcome Question Slide* and a video or worksheet +3. [ ] Click the **middle** tab +4. [ ] Close Wonder Ink (the × at the top right) +5. [ ] Open it again straight away from the panel +6. [ ] The WonderInk tab asks you to **sign in** — sign in normally (your + password is never kept, so it always will) +7. [ ] The **recent tabs are back**: the slide and the other resource +8. [ ] **In the same order** as before +9. [ ] With the **middle tab in front** +10. [ ] Open a worksheet from a lesson, then close and reopen Wonder Ink: + the worksheet tab comes back, named after the file +11. [ ] Print from a restored tab (the slide or the worksheet) through + Elmer: **the paper matches the preview** +12. [ ] Links still open with one click in a new tab, as before (Viewer) +13. [ ] With the tabs open, **reboot** the computer; within two hours of + using Wonder Ink, open it again +14. [ ] **The recent tabs are back** (after signing in on the WonderInk tab) +15. [ ] **Expiry, without waiting two hours.** Close Wonder Ink. Open the + maintenance terminal (Meta+Ctrl+Alt+Shift+K) and run + `CLASSROOM_WONDERINK_TEST_WORKSPACE_SECONDS=120 classroom-wonderink`. + This is **test-only**: it lasts as long as that one Wonder Ink, + can only shorten the time, and nothing in the classroom sets it +16. [ ] Open a couple of tabs in it, click in one, then touch nothing for + **three minutes** and close it +17. [ ] Open Wonder Ink from the panel: it **starts fresh**, one tab on the + WonderInk start page, none of the old tabs ### Presentations under memory pressure (0.2.6.2, the laptop) diff --git a/docs/wonder-ink.md b/docs/wonder-ink.md index f808b57..d6b6201 100644 --- a/docs/wonder-ink.md +++ b/docs/wonder-ink.md @@ -74,6 +74,49 @@ the code: back, forward, reload, open in a new tab when there is a link, cut/copy/paste in a text field, print image when there is a picture under the pointer, print page. +### Links in a lesson (0.2.6.4) + +A link in a lesson opens with one click in a new tab, and Wonder Ink shows +that tab; the lesson stays in its own. That is what the site asks for — +every link in a lesson's content carries `target="_blank"` — and what the +engine does with it (`createWindow`, answered with a tab that takes the +focus). Measured on the real site, on the real *Rise and Fall of Saul* +lesson: "Saul Welcome Question Slide" is +``, and one click +opened the slide in a new tab, at 100%, at 200% and in Full Screen. + +**The URL bubble teachers saw is WonderInk's editor, shown to admins.** +Testing 0.2.6.3 found that clicking such a link showed a small bubble with +the address and Edit / Remove instead of following it. Found by reading +the site's code and confirmed with the account roles: + +* the site shows lesson text in **CKEditor 5** (35.2.1, its + `RTE_USE_CKEDITOR_PRO` component). For a **Viewer** the content is + read-only and a link is a link; for an **Admin** it is editable, in + place; +* in an editable CKEditor 5, a plain click on a link is an editing click + by design (`LinkEditing._enableLinkOpen` opens a link only with Ctrl, ⌘ + on a Mac); the editor answers it with its link balloon — the address, + *Edit link*, *Unlink*. It is the same code in Chrome; +* moving the teacher's account to Viewer made the bubble go away. + +So Wonder Ink does not override it. Doing so would mean catching clicks +inside WonderInk's editor, which is how admins edit lessons, to fix +something the account's role already decides. An admin who wants to +follow a link straight away: **Ctrl+click** it. + +What each kind of link does, as `tools/lab/wonderink-print-check links:*` +clicks them on a signed-in lesson page: + +| | | +| --- | --- | +| a text link, a linked picture, another site's link (`target="_blank"`) | a new tab, shown | +| a worksheet PDF | a new tab in the PDF viewer; Print fetches it and prints it as a worksheet | +| a picture | a new tab; Print lays it out as a picture, and right-click offers Print image | +| a lesson button that opens a window | a new tab, shown | +| a lesson button, an in-page anchor (`#…`) | what the page does; no tab | +| a link with no target | followed in the same tab, as in a browser; Back returns | + Keys: Ctrl+W closes a tab, Alt+Left and Alt+Right navigate, Ctrl+P prints, Ctrl+Tab switches. Ctrl+T, Ctrl+N and Ctrl+L are deliberately unbound. @@ -434,19 +477,162 @@ logs it to the journal and carries on. sign-in and the room's shared YouTube account are different sessions in different storage that cannot reach each other. The browser is still Chrome and nothing in this change touches it. -* **Cookies live only as long as the window.** This is what the Chrome - policy's `CookiesSessionOnlyForUrls` did for wonderink.org, and it is - the reason closing Wonder Ink ends the teacher's session rather than - leaving the next person signed in as the last one. The whole profile - rather than one domain now, because this profile only ever goes where a - lesson sends it. If a room ever wants sign-ins to survive, it is the one - line `setPersistentCookiesPolicy` in `classroom-wonderink`. +* **Cookies live only as long as the window**, as Chrome's + `CookiesSessionOnlyForUrls` did for wonderink.org, so closing Wonder Ink + signs the teacher out and the next person is not signed in as the last + one. WonderInk's sign-in is the teacher's password in a cookie + (measured, 0.2.6.4), which is one more reason it never reaches the + disk. What does survive a close, for two hours, is the list of tabs — + see *Temporary workspace restore*, below. * **The old Chrome profile is left where it is**, at `~/.local/share/ekklesia-classroom/wonderink`. The new one is `wonderink-shell` beside it, so rolling back to 0.2.0 finds the old one intact. * **One scale for the room** — see *How large a lesson is*, below. +## Temporary workspace restore (0.2.6.4) + +A teacher who closes Wonder Ink by accident, or whose computer crashes or +restarts, gets their recent tabs back if they open it again within **two +hours of last using it**. After that, Wonder Ink starts fresh and the tabs +are forgotten: the next teacher — overnight, next week — never meets the +last one's. It is not a sign-in and not a memory of tabs. + + 10:00 using Wonder Ink + 10:45 closed by accident 10:50 opened again: the tabs are back + 11:00 finished, closed next Sunday: a fresh Wonder Ink + +### Why it is tabs and not the sign-in + +The first design kept the sign-in. It was measured on the real site +before it was built, and stopped: + +| | | +| --- | --- | +| `rrf-auth` | a cookie the site's JavaScript writes: **`Basic ` and the base64 of the teacher's email and password**, sent as a header on every request. Not a token the server issued | +| `rrf-session-id`, `rrf_tsec_tok`, `auth` | session cookies alongside it; none survives the window, which is why closing Wonder Ink signs the teacher out | +| Local Storage `mddui_local_storage`, Session Storage | screen variables and a screen cache | +| the site's start-up | asks the server to authenticate again every time it loads; a reload in the lab ended signed out even with the cookie present | + +Keeping the sign-in would have meant keeping the teacher's password, in a +form anyone at the maintenance terminal could reverse, on a shared +computer. It is not done. **Closing Wonder Ink still signs the teacher +out**, exactly as before; the engine writes no cookie to disk for any site. + +### What comes back + +* **Resource tabs** — a slide, a picture, a worksheet or video the lesson + linked to — exactly as they were. WonderInk's files are public (the + lesson's slide loads with no sign-in, measured), so they need none. +* **WonderInk's own tabs as one.** Every WonderInk page has the same + address (`https://app.wonderink.org/?`) whichever lesson it shows — the + site draws each screen itself — so a restored WonderInk tab opens the + site's start page and asks the teacher to sign in, as it would anyway. + Several of them become one, where the first was, so a teacher meets one + sign-in page, not five. +* **Worksheet tabs**, named and where they were — if the file is still in + `~/Downloads/Wonder Ink` and still a PDF. A worksheet that has gone is + left out, silently. Nothing outside that folder is ever opened from a + kept workspace, whatever the file says. +* **The order, and the tab that was in front.** The tab in front loads at + once; the others load the first time they are clicked. Measured: a PDF + loaded in a tab nobody was looking at was fitted to a window of no size, + and showed at 10% when clicked. Until then a tab is kept by the address + it will load, so closing Wonder Ink again loses nothing. + +Measured on the real site, with a real Viewer account, under the lab's +Plasma session: the *Rise and Fall of Saul* lesson, its welcome slide and +its WONDER@HOME PDF, the slide in front; closed and reopened — the three +tabs in that order, the slide in front, the WonderInk tab at its sign-in +page; and again after rebooting the machine with Wonder Ink open. The kept +file held the three addresses and titles, and none of the password, the +Basic-auth value or the email address. + +Never: the sign-in, a cookie, a header, a page's storage, a form, the +clipboard, a print preview or any of its temporary files. + +### What is kept, and when + +`~/.local/share/ekklesia-classroom/wonderink-workspace.json`, readable only +by the classroom account: + + format, last_activity, active, attempts, + tabs: [{kind: "web" | "worksheet", where: address or file, title}] + +An address is kept only if it is `http` or `https` and carries no +credential — no user and password in it, no query parameter named like a +token, key, password, session or signature. `tests/` writes a workspace +with such addresses and a Basic-auth value and checks the file holds none +of them; the lab signs in on a stand-in whose sign-in is Basic auth, as +WonderInk's is, and checks the same. + +It is written a second after the tabs change — opened, closed, dragged +into another order, brought to the front, navigated — and the time of +last use at most every 30 seconds, whole, to a temporary file renamed +into place. A crash or a power cut loses at most half a minute of use and +never leaves half a file. + +### What counts as using it + +The teacher's input reaching Wonder Ink: a click, a key, the wheel, a +touch — so following a link, scrolling, switching, opening and closing +tabs, opening a worksheet, printing and zooming all count. Nothing a page +does by itself does: timers, animation, background requests, analytics, +advertising, video buffering, service workers — measured with a page +making a request every second and animating for 20 s: not activity. A +print preview left open untouched is not activity either. + +**Opening Wonder Ink and having the tabs restored is not using it.** The +time kept is the teacher's last use, carried over, so closing and +reopening cannot keep a workspace alive by itself; the teacher clicking +in the restored tabs is using it, and the two hours start again. + +### When it is not restored + +At start, and only then: more than two hours since the last use, a file +that cannot be read or is from another version, a clock gone backwards by +more than a minute — Wonder Ink starts fresh, removes the file and says +why in the journal. No question is asked. + +A restore that crashes Wonder Ink does not make it unusable. Starting from +a workspace is counted in the file before any tab loads, and cleared once +Wonder Ink has run 20 seconds. After two starts that did not get that +far, the workspace is abandoned and Wonder Ink starts fresh, with a line +in the journal. + +Two hours is `IDLE_LIMIT_SECONDS` in +`lib/classroom_wonderink_workspace.py`, the one place it is decided. + +**Testing without waiting two hours.** From the maintenance terminal in +the session (Meta+Ctrl+Alt+Shift+K), with Wonder Ink closed: + + CLASSROOM_WONDERINK_TEST_WORKSPACE_SECONDS=120 classroom-wonderink + +That one Wonder Ink keeps the workspace for two minutes after the last +use, and says `TEST ONLY` in the journal. The variable can only shorten +the time, nothing in the classroom sets it (a test checks), and it lasts +as long as that process. + +### What it cannot do + +* **Reopen a lesson where it was.** WonderInk's screens have no address of + their own, so its tab comes back at its start page; after signing in + the teacher opens the lesson again. The slides, pictures and worksheets + they had open alongside it are already there. +* **Know who is at the keyboard.** Two hours is two hours of nobody using + Wonder Ink. A teacher who leaves and whose room is used within two hours + leaves their tabs — not their sign-in — to the next person. + +`tools/lab/wonderink-workspace-check` runs each of these against the +installed command: restored after 5 and 90 minutes; fresh after two hours +and a minute, the next day and the next week; reopened twice untouched; +activity after a restore; a busy page; an untouched print preview; +pressing Print; a closed tab; tabs reordered; a worksheet, and one whose +file has gone; killed outright; a restore that crashes twice; a corrupt +file, a later format, a half-written file; the privacy of the file; and +restored tabs printing. `tests/test-classroom-wonderink-workspace.sh` +covers the rules at every build. + ## How large a lesson is Teachers found lessons in Wonder Ink too small next to the same site in