feat: Presentations, for a teacher who downloaded tonight's session

PRESENTATIONS_ENABLED, off by default, independent of everything else. A
teacher downloads a session in ordinary Chrome and it is on the
Presentations screen a few seconds later, ready for the television. No
file manager, no import button, no Impress.

WHY NOTHING LAUNCHES A DOCUMENT APPLICATION. The brief was to use
existing presentation software, so the existing software was tried
first, on Debian 13, before any of this was designed. `soffice --show`
does start a real fullscreen slideshow — and needs XDG_SESSION_TYPE plus
a VCL plugin or it dies with "Failed to open display", shows a splash,
opened a "Tip of the Day: 1/225" dialog over the slides, and leaves the
Impress editor when the show ends. `okular --presentation` opens THREE
windows: the presentation, the ordinary document window behind it, and
an information dialog. zathura is not a presenter. pdfpc is the closest
and is another dependency with a presenter-console model. Every one of
them leaves an application on screen that can open any file on the
machine, and none of them knows there is a library to go back to.

So LibreOffice converts once, headless, at import, with no window on any
screen; poppler renders the pages; the classroom shows the pictures.
Measured: 0.34s for a ten-slide PPTX, 0.03s for its ten thumbnails,
0.10s for one slide at 1920px. That is not a new renderer — it is the
same engine Impress would have used live — and it means Escape is ours,
presenting is instant, and a PDF exported from Google Slides skips the
conversion entirely and keeps the appearance Google gave it.

THE THREE THINGS KEPT APART. The library thumbnail, the starting slide
and the retention clock are independent, because the first slide of a
Bible study session is a generic opening shared by every session and the
one that names it is usually the second. Quick Look chooses the picture;
it does not change where the slideshow starts and it does not count as
having presented anything. mark_presented() is called when a slide is
actually drawn, not when Present is pressed: an intention is not a
presentation, and a viewer that failed to start must not buy another
thirty days.

IMPORTING. The teacher's download is copied, never moved, renamed or
deleted. A file with a .crdownload beside it is still arriving. Wonder
Ink's own folder is not looked at. Two downloads of the same name are
two presentations, the second titled (2) — found in the lab, where a PDF
and a PPTX of one session both came out with the same name because the
import being named was excluded from the taken-titles set BY TITLE, and
a set holds one copy of a repeated string.

Metadata is written saying "importing" before any work, so a reboot
mid-conversion leaves a directory the next startup sweeps and imports
again. A file that cannot be converted gets a card saying so, offering
only Remove, with the teacher's download untouched.

Retention: 180 days never presented, 30 days from the last presentation,
every presentation starting the thirty over. The cleanup never touches a
presentation being shown, never leaves the library directory, and never
looks at Downloads.

The dock order is unchanged: Presentations is appended after the disc
player, so Wonder Ink, the browser and the player keep the places
teachers have been reaching for. There is a test for exactly that.

classroom-wonderink now asks feature() rather than carrying its own copy
of the default, so the panel and the command cannot disagree.

Co-Authored-By: Claude Opus 5 <[email protected]>

tests/test-classroom-desktop-layout.sh

@@ -85,8 +85,16 @@ check("a desktop can have Wonder Ink taken away",
 check("and keeps everything else",
       desktop_no_ink["DVD"] is True and desktop_no_ink["PARENT_CALL"] is True)
 
-check("an existing room that has never heard of these keeps them all",
-      all(module.wanted({}).values()), str(module.wanted({})))
+unset = module.wanted({})
+check("an existing room that has never heard of these keeps all three",
+      unset["WONDERINK"] and unset["DVD"] and unset["PARENT_CALL"],
+      str(unset))
+# The one that must NOT follow that rule. Every existing classroom has
+# Wonder Ink, a drive and Parent Call, so an upgrade has to leave all
+# three on. No existing classroom has Presentations, so an upgrade has to
+# leave it off — a new button on a bar nobody asked for is a support call.
+check("but Presentations is off until a device asks for it",
+      unset["PRESENTATIONS"] is False, str(unset))
 
 
 print("3. a drive can only ever take the player away")
@@ -126,13 +134,18 @@ check("and an unconfigured machine keeps every application",
 print("5. the bar that comes out, evaluated in node")
 STUB = r"""
 const fs = require("fs");
-const captured = {widgets: [], config: {}};
+const captured = {widgets: [], config: {}, launchers: []};
 let current = null;
 function makeWidget(type) {
     const w = {
         type: type,
         currentConfigGroup: [],
-        writeConfig: function (k, v) { captured.config[type + "." + k] = String(v); },
+        writeConfig: function (k, v) {
+            captured.config[type + "." + k] = String(v);
+            // Quick Launch widgets share a config key, so the last one
+            // written would otherwise be the only one anybody could see.
+            if (k === "launcherUrls") { captured.launchers.push(String(v)); }
+        },
         reloadConfig: function () {}
     };
     captured.widgets.push(type);
@@ -172,8 +185,15 @@ else:
     check("a classroom gets Wonder Ink, the browser and the player, in order",
           every and every["config"].get(LAUNCH) == f"{INK},{WEB},{DISC}",
           (every or {}).get("config", {}).get(LAUNCH, why))
+    CALL = "file:///usr/share/applications/ekklesia-parent-call.desktop"
+    HELP = "file:///usr/share/applications/ekklesia-manual.desktop"
+
     check("and Parent Call in the corner",
-          every and "org.kde.plasma.quicklaunch" in every["widgets"])
+          every and CALL in every["launchers"],
+          str((every or {}).get("launchers")))
+    check("and Help beside it",
+          every and HELP in every["launchers"],
+          str((every or {}).get("launchers")))
 
     no_ink, why = bar({"WONDERINK_ENABLED": "false"})
     check("a Bible study desktop has the browser first and no gap",
@@ -188,8 +208,50 @@ else:
           bible and bible["config"].get(LAUNCH) == WEB,
           (bible or {}).get("config", {}).get(LAUNCH, why))
     check("with no Parent Call button on it",
-          bible and "org.kde.plasma.quicklaunch" not in bible["widgets"],
-          str((bible or {}).get("widgets")))
+          bible and CALL not in bible["launchers"],
+          str((bible or {}).get("launchers")))
+    # Help is not optional. A teacher who needs the manual is by
+    # definition one who does not know where to look, so every room has
+    # it — what differs is which pages it opens on.
+    check("but Help is still there, because every room has a manual",
+          bible and HELP in bible["launchers"],
+          str((bible or {}).get("launchers")))
+    SLIDES = "applications:ekklesia-presentations.desktop"
+
+    # THE DOCK ORDER IS THE THING NOT TO BREAK.
+    #
+    # Every existing room has Wonder Ink, the browser and the player in
+    # that order, and teachers have been pressing them in that order for
+    # months. Presentations is appended, so all three keep their place on
+    # every machine that upgrades into this release.
+    module.has_optical_drive = lambda: True
+    slides, why = bar({"PRESENTATIONS_ENABLED": "true"})
+    check("Presentations goes on the END of the row, after the player",
+          slides and slides["config"].get(LAUNCH)
+          == f"{INK},{WEB},{DISC},{SLIDES}",
+          (slides or {}).get("config", {}).get(LAUNCH, why))
+
+    without, why = bar({"PRESENTATIONS_ENABLED": "false"})
+    check("and is absent entirely when the device does not offer it",
+          without and SLIDES not in without["config"].get(LAUNCH, ""),
+          (without or {}).get("config", {}).get(LAUNCH, why))
+    check("which leaves the other three exactly where they were",
+          without and without["config"].get(LAUNCH) == f"{INK},{WEB},{DISC}",
+          (without or {}).get("config", {}).get(LAUNCH, why))
+
+    # The prayer-room laptop: the browser and Presentations, nothing else.
+    module.has_optical_drive = lambda: False
+    study, why = bar({"PRESENTATIONS_ENABLED": "true",
+                      "WONDERINK_ENABLED": "false",
+                      "PARENT_CALL_ENABLED": "false",
+                      "DEVICE_TYPE": "laptop"})
+    check("the Bible study laptop gets the browser and Presentations",
+          study and study["config"].get(LAUNCH) == f"{WEB},{SLIDES}",
+          (study or {}).get("config", {}).get(LAUNCH, why))
+    check("and still no Parent Call on it",
+          study and CALL not in study["launchers"],
+          str((study or {}).get("launchers")))
+
     check("and the status corner is untouched",
           bible and "org.kde.plasma.volume" in bible["widgets"]
           and "org.kde.plasma.digitalclock" in bible["widgets"]
@@ -227,12 +289,28 @@ print("7. a disabled application does not start either")
 # talked into running it by a stale desktop entry or a technician's
 # muscle memory.
 for script, setting in (("classroom-wonderink", "WONDERINK_ENABLED"),
-                        ("classroom-parent-call", "PARENT_CALL_ENABLED")):
+                        ("classroom-parent-call", "PARENT_CALL_ENABLED"),
+                        ("classroom-presentations", "PRESENTATIONS_ENABLED"),
+                        ("classroom-presentation-import",
+                         "PRESENTATIONS_ENABLED")):
     text = (root / "scripts" / script).read_text()
     check(f"{script} refuses when {setting} is false",
           setting in text and "not starting" in text)
-    check(f"{script} defaults to starting, so existing rooms are unaffected",
-          'default=True' in text or 'feature(' in text)
+    check(f"{script} asks the shared helper rather than reading the file",
+          "feature(" in text and "read_device_config()" in text)
+
+# And each of them defaults the way its own room needs, which is not the
+# same answer for all four. Asserting one rule for all of them would pass
+# for the wrong reason on the one that differs.
+from classroom_config import feature as _feature  # noqa: E402
+
+for setting, default, why in (
+        ("WONDERINK_ENABLED", True, "every existing classroom has it"),
+        ("DVD_ENABLED", True, "every existing classroom has it"),
+        ("PARENT_CALL_ENABLED", True, "every existing classroom has it"),
+        ("PRESENTATIONS_ENABLED", False, "no existing classroom has it")):
+    check(f"{setting} defaults to {default} — {why}",
+          _feature({}, setting) is default)
 
 print()
 print(f"{passed} passed, {failed} failed")

tests/test-classroom-presentations.sh

@@ -0,0 +1,263 @@
+#!/bin/bash
+# The Presentations library: what it imports, what it refuses, what it
+# keeps and what it is never allowed to delete.
+#
+# No LibreOffice and no poppler here. Those are exercised by the lab and
+# by the release validator against a real Debian; this is the part that
+# has to be right whatever is installed — when a download counts as
+# finished, whose files may be touched, what a teacher's choice of
+# thumbnail does and does not change, and which of the two retention
+# clocks is running.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+PYTHONPATH="$ROOT/lib" python3 - "$ROOT" <<'PY'
+import os
+import shutil
+import sys
+import tempfile
+import time
+from datetime import timedelta
+from pathlib import Path
+
+root = Path(sys.argv[1])
+sys.path.insert(0, str(root / "lib"))
+
+import classroom_presentations as library
+
+passed = failed = 0
+
+
+def check(label, condition, detail=""):
+    global passed, failed
+    if condition:
+        print(f"  ok   {label}")
+        passed += 1
+    else:
+        print(f"  FAIL {label}")
+        if detail:
+            print(f"       {detail}")
+        failed += 1
+
+
+work = Path(tempfile.mkdtemp(prefix="classroom-presentations-"))
+downloads = work / "Downloads"
+wonderink = downloads / "Wonder Ink"
+shelf = work / "library"
+wonderink.mkdir(parents=True)
+shelf.mkdir(parents=True)
+
+
+def download(name, contents="x" * 400, age=60):
+    """A file sitting in Downloads, finished `age` seconds ago."""
+    path = downloads / name
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(contents)
+    when = time.time() - age
+    os.utime(path, (when, when))
+    return path
+
+
+def entry(**data):
+    """A presentation in the library, without running an import."""
+    directory = shelf / data.get("id", "one")
+    directory.mkdir(parents=True, exist_ok=True)
+    base = {
+        "id": directory.name,
+        "state": "ready",
+        "title": "A session",
+        "pages": 10,
+        "thumbnail_page": 1,
+        "imported_at": library.stamp(),
+        "last_presented_at": None,
+        "times_presented": 0,
+    }
+    base.update(data)
+    presentation = library.Presentation(directory, base)
+    presentation.save()
+    (directory / "slides.pdf").write_text("%PDF-1.4")
+    return presentation
+
+
+print("1. a download that has finished, and ones that have not")
+done = download("Session 7 - Romans.pptx")
+check("a settled PowerPoint is importable", library.importable(done))
+
+arriving = download("Still arriving.pptx")
+partial = downloads / "Still arriving.pptx.crdownload"
+partial.write_text("half")
+check("one with a .crdownload beside it is not",
+      not library.importable(arriving),
+      "Chrome renames the .crdownload away when the transfer completes")
+
+check("and the .crdownload itself is never a candidate",
+      not library.importable(partial))
+
+fresh = download("Just landed.pdf", age=0)
+check("one still being written is not",
+      not library.importable(fresh),
+      "a file copied from a USB stick has no .crdownload to go by")
+
+check("something that is not a presentation is not",
+      not library.importable(download("notes.txt")))
+
+empty = download("Nothing.pdf", contents="", age=60)
+check("a nought-byte file is not", not library.importable(empty))
+
+print("2. Wonder Ink's worksheets are not presentations")
+worksheet = wonderink / "Colouring page.pdf"
+worksheet.write_text("%PDF-1.4" + "x" * 400)
+os.utime(worksheet, (time.time() - 60, time.time() - 60))
+check("a file in the Wonder Ink folder is recognised as Wonder Ink's",
+      library.within_wonderink(worksheet, downloads))
+check("and one beside it in Downloads is not",
+      not library.within_wonderink(done, downloads))
+
+names = [p.name for p in library.candidates(downloads)]
+check("so it is not offered for import", "Colouring page.pdf" not in names,
+      str(names))
+check("the finished session is", "Session 7 - Romans.pptx" in names, str(names))
+check("and nothing unfinished is",
+      "Still arriving.pptx" not in names and "Just landed.pdf" not in names,
+      str(names))
+
+print("3. titles a teacher would recognise")
+check("an ordinary name is kept",
+      library.readable_title("Session 7 - Romans.pptx") == "Session 7 - Romans",
+      library.readable_title("Session 7 - Romans.pptx"))
+check("underscores become spaces",
+      library.readable_title("Session_7_Romans.pdf") == "Session 7 Romans",
+      library.readable_title("Session_7_Romans.pdf"))
+check("a browser's duplicate counter goes",
+      library.readable_title("Bible Study (1).pdf") == "Bible Study",
+      library.readable_title("Bible Study (1).pdf"))
+check("a percent-escaped space is decoded",
+      library.readable_title("Session%207.pdf") == "Session 7",
+      library.readable_title("Session%207.pdf"))
+hashed = library.readable_title(
+    "a4f39c2e91bb4d7e.pdf", "Session 7 of the autumn study\nmore")
+check("a hash falls back to the document's own first words",
+      hashed == "Session 7 of the autumn study", hashed)
+check("and something with no name at all still gets one",
+      library.readable_title("...pdf", "") == "Presentation",
+      library.readable_title("...pdf", ""))
+
+print("4. two downloads of the same name are two presentations")
+first = entry(id="first", title="Session 7")
+second = entry(id="second", title="Session 7")
+# The bug this replaces: excluding the import being named BY TITLE also
+# removed the other presentation's identical title from the set, so a
+# PDF and a PPTX of one session both came out called "Session 7".
+taken = library.titles_in_use(shelf, exclude="second")
+check("the other presentation's title is still in the way",
+      "Session 7" in taken, str(taken))
+check("so the second gets a title of its own",
+      library.unique_title("Session 7", taken) == "Session 7 (2)",
+      library.unique_title("Session 7", taken))
+check("and a name nothing else has is left alone",
+      library.unique_title("Session 8", taken) == "Session 8")
+shutil.rmtree(shelf / "first")
+shutil.rmtree(shelf / "second")
+
+print("5. the thumbnail is the teacher's choice, and only that")
+# The first slide of a Bible study session is a generic opening shared by
+# every session; the one that names the session is usually the second.
+p = entry(id="thumb", pages=12)
+before = dict(p.data)
+p.set_thumbnail_page(2)
+after = library.load(shelf / "thumb")
+check("the chosen slide is remembered", after.thumbnail_page == 2,
+      str(after.thumbnail_page))
+check("it survives being read back from disk, so it survives a restart",
+      library.load(shelf / "thumb").thumbnail_page == 2)
+check("choosing it did not mark the session as presented",
+      after.last_presented_at is None and after.times_presented == 0)
+check("and did not move the retention clock",
+      after.data["imported_at"] == before["imported_at"]
+      and after.data.get("last_presented_at") is None)
+check("a slide past the end is clamped rather than stored",
+      entry(id="thumb2", pages=5, thumbnail_page=99).thumbnail_page == 5)
+check("and a nonsense one does not crash the card",
+      entry(id="thumb3", pages=5, thumbnail_page="banana").thumbnail_page == 1)
+
+print("6. the two retention clocks")
+old = library.now() - timedelta(days=181)
+recent = library.now() - timedelta(days=100)
+
+never = entry(id="never", imported_at=library.stamp(old))
+check("never presented, imported over 180 days ago, is expired",
+      never.expired(), str(never.expires_at()))
+
+young = entry(id="young", imported_at=library.stamp(recent))
+check("never presented but only 100 days old is not",
+      not young.expired(), str(young.expires_at()))
+
+shown = entry(id="shown",
+              imported_at=library.stamp(old),
+              last_presented_at=library.stamp(library.now() - timedelta(days=2)),
+              times_presented=3)
+check("presented two days ago is kept, however old the import is",
+      not shown.expired(),
+      "presenting has to start the 30-day clock and stop the 180-day one")
+
+stale = entry(id="stale",
+              imported_at=library.stamp(old),
+              last_presented_at=library.stamp(library.now() - timedelta(days=31)),
+              times_presented=1)
+check("presented 31 days ago is expired", stale.expired())
+
+print("7. presenting is the only thing that resets the clock")
+p = entry(id="counted", pages=4)
+check("a fresh import has never been presented",
+      p.last_presented_at is None and p.times_presented == 0)
+p.mark_presented()
+reread = library.load(shelf / "counted")
+check("presenting is recorded", reread.last_presented_at is not None)
+check("and counted", reread.times_presented == 1)
+first_due = reread.expires_at()
+time.sleep(1.1)
+reread.mark_presented()
+again = library.load(shelf / "counted")
+check("presenting again starts the thirty days over",
+      again.expires_at() > first_due, f"{first_due} -> {again.expires_at()}")
+check("and counts again", again.times_presented == 2)
+
+print("8. an import that was interrupted is not shown to a teacher")
+half = entry(id="half", state="importing")
+check("it is in the library's own list",
+      any(x.id == "half" for x in library.library(shelf)))
+check("but it is not ready, so no card offers Present",
+      not library.load(shelf / "half").ready)
+broken = shelf / "broken"
+broken.mkdir()
+(broken / "presentation.json").write_text("{ this is not json")
+check("a truncated metadata file is skipped rather than crashing the library",
+      all(x.id != "broken" for x in library.library(shelf)),
+      "a card a teacher cannot open is worse than no card")
+
+print("9. the presenting lock cannot outlive a reboot")
+check("it lives in the runtime directory",
+      "/run" in str(library.presenting_lock())
+      or str(library.presenting_lock()).startswith("/tmp"),
+      str(library.presenting_lock()))
+
+print("10. the ledger remembers a download after its presentation is gone")
+mark = library.fingerprint(done)
+library.remember(mark, "some-id", shelf)
+check("a fingerprint is path, size and time",
+      mark is not None and str(done.resolve()) in mark, str(mark))
+check("it is written down", library.ledger(shelf).get(mark) == "some-id")
+check("so Remove means removed, not removed until the next scan",
+      mark in library.ledger(shelf))
+touched = download("Session 7 - Romans.pptx", contents="y" * 900)
+check("but re-downloading the same session is a new presentation",
+      library.fingerprint(touched) != mark,
+      "a different size or time is a different download")
+
+shutil.rmtree(work, ignore_errors=True)
+
+print()
+print(f"{passed} passed, {failed} failed")
+raise SystemExit(1 if failed else 0)
+PY