glideshow 0.1.2__py3-none-any.whl

glideshow/build.py

@@ -0,0 +1,54 @@
+"""--build: a self-contained copy of a deck that presents without the network."""
+
+import hashlib, re, urllib.request
+from pathlib import Path
+
+# --build: a copy of the deck that needs no network. reveal.js (and the notes plugin shapes.js loads beside it) is
+# vendored under vendor/, and the deck's Google Fonts / Material Symbols links become assets/fonts/google-fonts.css and
+# google-icons.css with the font files
+# beside it. Only https URLs in those two places are fetched; everything else is copied as is.
+MAX_FETCH = 25_000_000   # bytes: pasted image URLs larger than this are refused
+REVEAL_FILES = ["dist/reveal.css", "dist/reveal.js", "plugin/notes/notes.js", "plugin/highlight/highlight.js"]
+WOFF2_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36"
+
+
+def fetch(url: str, ua: str = "slides-build") -> bytes:
+    with urllib.request.urlopen(urllib.request.Request(url, headers={"User-Agent": ua}), timeout=30) as r:
+        return r.read(MAX_FETCH)
+
+
+def build(deck: Path, out: Path) -> None:
+    import shutil
+    if out.exists() and any(out.iterdir()):
+        raise SystemExit(f"{out} is not empty")
+    shutil.copytree(deck, out, dirs_exist_ok=True, ignore=shutil.ignore_patterns(".*"))
+    html = (out / "deck.html").read_text()
+    for m in sorted(set(re.findall(r"https://cdn\.jsdelivr\.net/npm/(reveal\.js@[\d.]+)/dist/reveal\.(?:css|js)", html))):
+        for rel in REVEAL_FILES:
+            dst = out / "vendor" / m.replace("@", "-") / rel
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            dst.write_bytes(fetch(f"https://cdn.jsdelivr.net/npm/{m}/{rel}"))
+        html = html.replace(f"https://cdn.jsdelivr.net/npm/{m}/", f"vendor/{m.replace('@', '-')}/")
+    for ver in sorted(set(re.findall(r"https://cdn\.jsdelivr\.net/npm/katex@([\d.]+)/dist/", html))):   # equations (shapes.js)
+        base, dst = f"https://cdn.jsdelivr.net/npm/katex@{ver}/dist/", out / "vendor" / f"katex-{ver}"
+        for rel in ["katex.min.css", "katex.min.js", "contrib/auto-render.min.js"]:
+            (dst / rel).parent.mkdir(parents=True, exist_ok=True)
+            (dst / rel).write_bytes(fetch(base + rel))
+        for rel in sorted(set(re.findall(r"url\((fonts/[^)]+?\.woff2)\)", (dst / "katex.min.css").read_text()))):
+            (dst / rel).parent.mkdir(parents=True, exist_ok=True)
+            (dst / rel).write_bytes(fetch(base + rel))
+        html = html.replace(base, f"vendor/katex-{ver}/")
+    for link in re.finditer(r'<link id="deck-(fonts|icons)"[^>]*href="(https://fonts\.googleapis\.com/css2\?[^"]+)"', html):
+        css = fetch(link.group(2).replace("&amp;", "&"), WOFF2_UA).decode()
+        fonts = out / "assets" / "fonts"
+        fonts.mkdir(parents=True, exist_ok=True)
+        def local(m):
+            data = fetch(m.group(1))
+            name = hashlib.sha1(data).hexdigest()[:12] + ".woff2"
+            (fonts / name).write_bytes(data)
+            return f"url({name})"
+        css = re.sub(r"url\((https://fonts\.gstatic\.com/[^)]+)\)", local, css)
+        (fonts / f"google-{link.group(1)}.css").write_text(css)
+        html = html.replace(link.group(2), f"assets/fonts/google-{link.group(1)}.css")
+    (out / "deck.html").write_text(html)
+    print(f"Built {out / 'deck.html'} (no network needed)")

glideshow/cli.py

@@ -0,0 +1,320 @@
+"""The `glideshow` command.
+
+    glideshow                         open the home screen (starting the server if needed)
+    glideshow new "Lab meeting"       a new deck in $GLIDESHOW_HOME (default ~/decks), opened in the editor
+                                      (--no-open: only made, its folder printed; the editor isn't touched)
+    glideshow find <words>            the folder of the deck that best matches (nothing is opened)
+    glideshow <name>                  open the deck whose folder name best matches <name> (in any folder)
+    glideshow build <name> <out>      a self-contained copy that presents offline
+    glideshow serve [DECK] [...]      run the server in the foreground (--port N, --build OUT, --init, --add-image FILE)
+    glideshow url                     print the running server's address (starting it if needed)
+    glideshow selection [--json]      what the open editor shows: the deck, the slide on show, the selected boxes and their text
+    glideshow render [deck] [N ...]   the deck's slides as 960 × 540 PNGs (default: the deck open in the editor; -o DIR; --full:
+                                      1920 × 1080), one path per line, then any problems (overflow, cut-off code, off-slide,
+                                      overlaps, small text, inside figures, notes left; --json); --sheet: nine slides to a picture
+                                      instead; --morph: each Morph step's pairs and a picture halfway through it
+    glideshow check [deck] [N ...]    only the problems, no pictures (exit 1 if any)
+    glideshow docs [reference]        for an agent: the guide and recipes (reference: the full deck format)
+    glideshow layout [NAME]           the layouts' exact placeholder boxes; with NAME, a slide in that layout to paste
+    glideshow slides <deck> [N ...]   only the deck's <section>s (no inlined CSS / JS), each with its line in deck.html;
+                                      --outline: one line per slide (its layout, title, boxes' ids and first words)
+    glideshow put <deck> N            replace slide N with the <section>s on stdin (--after N inserts, --delete N removes, --all replaces every slide)
+    glideshow figure add|refresh|size a picture placed or replaced in place, remembering the command that made it (see
+                                      `glideshow figure`); refresh re-runs those commands; size gives matplotlib settings
+    glideshow comments <deck>         the open comments, each on the slide it's on now (--all, --json)
+    glideshow stop                    stop the background server
+    glideshow skill                   teach Claude Code to make decks here: links the Glideshow skill into ~/.claude/skills
+    glideshow install                 start the server at login (macOS, Linux, Windows), and link the skill (glideshow skill)
+    glideshow init-remote OWNER/REPO  back the library up to a new private GitHub repo (needs `gh`); every save is pushed
+    glideshow publish <name>          share the deck at an unguessable glideshow.org link (the library on GitHub, with the Glideshow app on it)
+    glideshow unpublish <name>        take it down again; `glideshow published` lists the links
+    glideshow import-google <url>     a Google Slides deck as a new deck, through the Slides API (--login once; --report scores it)
+
+One server serves every deck, in the background, on port 47800 (or the next free one; GLIDESHOW_PORT overrides). It is
+recorded in ~/.glideshow/server.json (server-PORT.json with GLIDESHOW_PORT set; GLIDESHOW_CACHE moves the whole folder),
+restarts itself when its code changes, and a second one is never started. A separate library for tests:
+GLIDESHOW_HOME=/tmp/x/decks GLIDESHOW_CACHE=/tmp/x/cache GLIDESHOW_PORT=48900 glideshow …
+--no-open skips the browser and prints the address instead (`glideshow url` prints it too)."""
+import datetime, json, os, re, subprocess, sys, time, webbrowser
+from pathlib import Path
+
+from .service import CACHE, DEFAULT_PORT, code_version, live, post, same_install
+
+HERE = Path(__file__).resolve().parent
+HOME = Path(os.environ.get("GLIDESHOW_HOME") or Path.home() / "decks").expanduser()
+URL = f"http://localhost:{DEFAULT_PORT}/"   # updated to the live server's address by running()
+
+
+def slug(title: str) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-") or "deck"
+    return f"{s}-{datetime.date.today().isoformat()}"
+
+
+def decks() -> list:
+    """Every deck in the library, in any folder, most recently edited first."""
+    from .decks import walk_library
+    return sorted(walk_library()[0], key=lambda d: -(d / "deck.html").stat().st_mtime)
+
+
+def match(name: str) -> Path:
+    """Exact folder, then substring, then every word (in any order), then letters in order (fuzzy); spaces, dashes and
+    underscores are alike ("lab meeting" finds lab-meeting-2026-10-15); the most recently edited wins ties."""
+    norm = lambda t: re.sub(r"[^a-z0-9]+", "-", t.lower()).strip("-")
+    q, ds = norm(name), decks()
+    words = [w for w in q.split("-") if w]
+    for test in (lambda d: norm(d.name) == q, lambda d: q in norm(d.name), lambda d: words and all(w in norm(d.name) for w in words),
+                 lambda d: re.search(".*?".join(map(re.escape, q.replace("-", ""))), norm(d.name).replace("-", ""))):
+        hit = [d for d in ds if test(d)]
+        if hit: return hit[0]
+    raise SystemExit(f"no deck in {HOME} matches {name!r}")
+
+
+def running() -> bool:
+    """Is our one server up, on the current code? A server running older code is told to quit (a fresh one replaces it)."""
+    global URL
+    s = live()
+    if s and not same_install(s):
+        print(f"(the running server is another install of slides: {s.get('install')})", file=sys.stderr)
+    elif s and s["version"] != code_version():
+
+        try: post(s["url"], "api/quit", {})
+        except Exception: pass
+        time.sleep(0.5); return False
+    if s: URL = s["url"]
+    return bool(s)
+
+
+def start(deck: Path | None = None):
+    """Start the background server (detached, logging to ~/.glideshow/server.log) and wait until it answers."""
+    log = open(CACHE.mkdir(parents=True, exist_ok=True) or CACHE / "server.log", "a")
+    subprocess.Popen([sys.executable, "-m", "glideshow.server", *([str(deck)] if deck else []), "--no-open"],
+                     stdout=log, stderr=log, stdin=subprocess.DEVNULL, start_new_session=True)
+    for _ in range(600):   # (a cold first start can take a while: imports, a fresh .pyc cache)
+        if running(): return
+        time.sleep(0.1)
+    raise SystemExit(f"the slides server did not start; see {CACHE / 'server.log'}")
+
+
+def serve(deck: Path, open_browser: bool):
+    """Open the deck in the editor; the terminal shows its address only when no browser opens (--no-open)."""
+    if running():   # switch the running server to this deck
+        err = post(URL, "api/open", {"path": str(deck), "create": True}).get("error")
+        if err: raise SystemExit(err)
+    else:
+        start(deck)
+    if open_browser: webbrowser.open(URL + "edit")
+    else: print(f"Editing {deck} at {URL}edit")
+
+
+def new(title: str) -> Path:
+    HOME.mkdir(parents=True, exist_ok=True)
+    if not (HOME / ".git").exists() and subprocess.run(["git", "-C", str(HOME), "rev-parse"], capture_output=True).returncode:
+        subprocess.run(["git", "init", "-q", str(HOME)], check=False)   # decks are versioned from the first one
+        if not (HOME / ".gitignore").exists(): (HOME / ".gitignore").write_text(IGNORE)
+    deck, n = HOME / slug(title), 2
+    while deck.exists(): deck, n = HOME / f"{slug(title)}-{n}", n + 1
+    (deck / "assets").mkdir(parents=True)
+    from .decks import new_deck   # the template with base.css / shapes.js / present.js filled in, + AGENTS.md
+    new_deck(deck / "deck.html", title)
+    return deck
+
+
+BIG = 50 * 1024 * 1024   # GitHub warns above 50 MB and refuses 100 MB
+# `**/` so the rules still hold once decks are moved into folders (a plain `*/refs/` matches one level only)
+IGNORE = ".DS_Store\n*.tmp\n# regenerable comparison renders (gslides2deck refs, test/snap.py shots), at any folder depth\n**/refs/\n**/refs-svg/\n**/source/snap*/\n**/source/cmp/\n"
+
+
+
+def init_remote(repo: str):
+    """The whole library ($GLIDESHOW_HOME) as one git repo with a private GitHub origin; the server pushes after each commit."""
+    git = lambda *a, **k: subprocess.run(["git", "-C", str(HOME), *a], capture_output=True, text=True, **k)
+    HOME.mkdir(parents=True, exist_ok=True)
+    if git("rev-parse", "--is-inside-work-tree").stdout.strip() != "true":
+        git("init", "-q", "-b", "main")
+    ig = HOME / ".gitignore"
+    big = sorted({f"**/{p.name}" for p in HOME.rglob("*") if p.is_file() and ".git" not in p.parts and p.stat().st_size > BIG})   # by name: still ignored after a move
+
+    text = ig.read_text() if ig.exists() else IGNORE
+    new = [b for b in big if b not in text.split("\n")]
+    if new: text += "# over 50 MB: kept on this Mac only\n" + "".join(b + "\n" for b in new)
+    ig.write_text(text)
+    git("add", "-A")
+    if git("diff", "--cached", "--quiet").returncode:
+        git("commit", "-q", "-m", "library: back up decks")
+    if git("remote", "get-url", "origin").returncode == 0:
+        print(f"origin is already {git('remote', 'get-url', 'origin').stdout.strip()}; pushing")
+        r = git("push", "-u", "origin", "HEAD")
+    elif subprocess.run(["gh", "repo", "view", repo], capture_output=True).returncode == 0:
+        url = subprocess.run(["gh", "repo", "view", repo, "--json", "sshUrl", "-q", ".sshUrl"], capture_output=True, text=True).stdout.strip()
+        git("remote", "add", "origin", url); r = git("push", "-u", "origin", "HEAD")
+    else:
+        r = subprocess.run(["gh", "repo", "create", repo, "--private", "--source", str(HOME), "--remote", "origin", "--push",
+                            "--description", "Slide decks (backed up by the slides editor)"], capture_output=True, text=True)
+    if r.returncode:
+        raise SystemExit(f"push failed: {(r.stderr or r.stdout).strip()[:400]}")
+    print(f"{HOME} is backed up to {repo} (private); the server pushes after every commit (--no-push to stop)"
+          + (f"; not uploaded (over 50 MB): {', '.join(big)}" if big else ""))
+
+
+SKILL = (HERE / "skills" if (HERE / "skills").is_dir() else HERE.parent / "skills") / "glideshow"
+
+
+def link_skill():
+    """The Glideshow skill (skills/glideshow/SKILL.md) in ~/.claude/skills, so every Claude Code session on this computer, in
+    any folder, knows how to make and check decks here. A link, so it follows updates; a real folder there is left alone."""
+    dst = Path.home() / ".claude" / "skills" / "glideshow"
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if dst.is_symlink(): dst.unlink()
+    if dst.exists(): return print(f"{dst} exists and isn't a link; left as it is (the skill is at {SKILL})")
+    dst.symlink_to(SKILL, target_is_directory=True)
+    print(f"Claude Code now knows Glideshow: {dst} -> {SKILL}")
+
+
+def render(args: list[str], check: bool = False):
+    """`glideshow render` (the slides as PNGs, then any problems) and `glideshow check` (only the problems; exit 1 if
+    any) through glideshow/render.py, a uv script that brings Playwright with it."""
+    out = None
+    if "-o" in args: i = args.index("-o"); out = Path(args[i + 1]).expanduser(); args = args[:i] + args[i + 2:]
+    flags = [a for a in args if a in ("--json", "--morph", "--full", "--sheet")] + (["--check"] if check else [])
+    args = [a for a in args if not a.startswith("--")]
+    is_num = lambda a: re.fullmatch(r"\d+(\.\d+)?", a)
+    nums, names = [a for a in args if is_num(a)], [a for a in args if not is_num(a)]
+    if names: deck = Path(names[0]).expanduser() if (Path(names[0]).expanduser() / "deck.html").exists() else match(names[0])
+    else:
+        s = live()
+        if not s: raise SystemExit("Name a deck (glideshow render <deck> [N ...]); no editor is open to take it from.")
+        deck = Path(s["deck"])
+    from .agent import ensure_server, scan, slide_number
+    ensure_server(deck)   # the edits being checked are kept as versions by it
+    text = (deck / "deck.html").read_text()
+    nums = [str(slide_number(text, a)) for a in nums]   # the deck's own numbers (8.1) as the file's
+    os.environ["GLIDESHOW_STRUCTURE"] = json.dumps(scan(text)[1])   # what render.py can't see: the file's own structure
+    out = out or CACHE / "renders" / deck.name
+    try: r = subprocess.run(["uv", "run", "--quiet", str(HERE / "render.py"), str(deck.resolve()), str(out), *nums, *flags])
+    except FileNotFoundError: raise SystemExit("glideshow render needs uv (https://docs.astral.sh/uv/), which brings Playwright with it")
+    raise SystemExit(r.returncode)
+
+
+def install():
+    """Start the server at login: a launchd agent (macOS), a systemd user service (Linux), the Startup folder (Windows)."""
+    link_skill()
+    py, log = sys.executable, CACHE / "server.log"
+    CACHE.mkdir(parents=True, exist_ok=True)
+    if sys.platform == "darwin":
+        f = Path.home() / "Library" / "LaunchAgents" / "com.glideshow.server.plist"
+        f.parent.mkdir(parents=True, exist_ok=True)
+        f.write_text(f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.glideshow.server</string>
+  <key>ProgramArguments</key><array><string>{py}</string><string>-m</string><string>glideshow.server</string><string>--no-open</string></array>
+  <key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>StandardOutPath</key><string>{log}</string><key>StandardErrorPath</key><string>{log}</string>
+</dict></plist>
+""")
+        subprocess.run(["launchctl", "unload", str(f)], capture_output=True)
+        subprocess.run(["launchctl", "load", str(f)], check=False)
+    elif sys.platform.startswith("linux"):
+        f = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "systemd" / "user" / "glideshow.service"
+        f.parent.mkdir(parents=True, exist_ok=True)
+        f.write_text(f"[Unit]\nDescription=Glideshow editor server\n\n[Service]\nExecStart={py} -m glideshow.server --no-open\nRestart=on-failure\n\n[Install]\nWantedBy=default.target\n")
+        subprocess.run(["systemctl", "--user", "daemon-reload"], check=False)
+        subprocess.run(["systemctl", "--user", "enable", "--now", "glideshow.service"], check=False)
+    elif sys.platform == "win32":
+        f = Path(os.environ["APPDATA"]) / "Microsoft" / "Windows" / "Start Menu" / "Programs" / "Startup" / "slides-server.cmd"
+        f.write_text(f'@start "" /min "{Path(py).with_name("pythonw.exe")}" -m glideshow.server --no-open\r\n')
+    else:
+        raise SystemExit("glideshow install knows macOS, Linux and Windows")
+    print(f"The Glideshow server now starts at login ({f}). `glideshow` opens it.")
+
+
+def main(argv):
+    open_browser = "--no-open" not in argv
+    args = [a for a in argv if a != "--no-open"]
+    if not args:   # the home screen, starting the server if needed
+        if not running(): start()
+        if open_browser: webbrowser.open(URL)
+        else: print(URL)   # the address only when no browser opens
+        return
+    cmd, rest = args[0], args[1:]
+    if cmd in ("-h", "--help", "help") or any(a in ("-h", "--help") for a in rest): return print(__doc__)   # `glideshow new --help` too: usage, not a deck called "--help"
+    if cmd == "url":   # the running server's address, starting it if needed (the desktop app asks this)
+        if not running(): start()
+        return print(URL)
+    if cmd == "selection":   # for an agent working beside the editor: what "this" means
+        s = live()
+        import urllib.request
+        if not s:
+            if "--json" in rest: print(json.dumps({"slide": None, "boxes": [], "error": "no server, so no editor is open"}))
+            raise SystemExit(1 if "--json" in rest else "No editor is open (the Glideshow server isn't running), so there is no selection: ask the user which slide they mean.")
+        sel = json.load(urllib.request.urlopen(s["url"] + "api/selection", timeout=5))
+        age = round(time.time() - sel["time"]) if sel.get("time") else None
+        if age is not None: sel["age"] = age
+        if "--json" in rest:
+            print(json.dumps(sel, indent=2))
+            if not sel.get("slide"): raise SystemExit(1)
+            return
+        if not sel.get("slide"): raise SystemExit(f"{sel['file']}\nNo editor window has reported what it shows (the server is running, but no editor is open in a browser): ask the user which slide they mean.")
+        from .agent import sections
+        n_file = len(sections(Path(sel["file"]).read_text())) if Path(sel["file"]).exists() else None
+        if n_file and sel.get("slides") and n_file != sel["slides"]: print(f"(the editor reported {sel['slides']} slides but deck.html now has {n_file}: it may not have reloaded yet, or the report is old)")
+        lines = [sel["file"], f"slide {sel['slide']} of {sel.get('slides', '?')}" + (f"  (reveal #/{sel['h']}/{sel['v']})" if sel.get("v") else "")
+                 + (f"  (reported {age} s ago{'; the editor may be closed' if age > 600 else ''})" if age is not None else "")]
+        for b in sel.get("boxes", []):
+            lines.append(f"  box id={b['id']}  ({b['shape']}, box {b['index'] + 1} on the slide, at {b['x']},{b['y']} size {b['w']}×{b['h']})" + (f": {b['text'][:120]}" if b.get("text") else ""))
+        if not sel.get("boxes"): lines.append("  nothing selected (the whole slide)")
+        if sel.get("selectedText"): lines.append(f"  selected text: {sel['selectedText'][:200]!r}")
+        return print("\n".join(lines))
+    if cmd == "serve":   # the server itself, in the foreground: `glideshow serve DECK [--port N] [--build OUT] [--init] [--add-image F]`
+        from .server import main as server_main
+        sys.argv = ["glideshow serve", *argv[1:]]; return server_main()
+    if cmd == "new":
+        if rest and rest[0].startswith("-"): raise SystemExit('usage: glideshow new "<title>" [--no-open]   (a title can\'t start with "-")')
+        deck = new(" ".join(rest) or "Untitled")
+        if not open_browser:   # an agent's: made and printed; the editor (and what it shows) is left alone
+            if not running(): start(deck)   # the background server, so every edit to the deck becomes a version
+            return print(deck)
+        return serve(deck, open_browser)
+    if cmd in ("layout", "slides", "put", "figure", "find", "stop", "comments"):
+        from . import agent
+        if cmd == "stop": return agent.stop_cmd()
+        return {"layout": agent.layout_cmd, "slides": agent.slides_cmd, "put": agent.put_cmd, "figure": agent.figure_cmd, "find": agent.find_cmd, "comments": agent.comments_cmd}[cmd](rest)
+
+    if cmd == "build":
+        if len(rest) != 2: raise SystemExit("usage: glideshow build <name> <out>")
+        return subprocess.run([sys.executable, "-m", "glideshow.server", str(match(rest[0])), "--build", rest[1]], check=True)
+    if cmd == "install": return install()
+    if cmd == "skill": return link_skill()
+    if cmd in ("render", "check"): return render(rest, check=cmd == "check")
+    if cmd == "docs":   # the guide and recipes; `docs reference` the format reference (AGENTS.md beside each deck holds both)
+        from .decks import docs_text
+        return print(docs_text("reference" if rest[:1] == ["reference"] else "guide"))
+    if cmd in ("publish", "unpublish", "published"):
+        from . import publish as pub
+        if cmd == "published":
+            return print("\n".join(f"{v.get('url', '(not deployed)')}  {v.get('title', rel)}" for rel, v in pub.ledger().items()) or "nothing published")
+        if not rest: raise SystemExit(f"usage: glideshow {cmd} <name>")
+        deck = match(" ".join(rest))
+        if cmd == "unpublish": pub.unpublish(deck); return print(f"{deck.name} is no longer shared")
+        return print(f"{deck.name} is at {pub.publish(deck)['url']}  (anyone with this link can view it once the library is pushed; Share sets who can)")
+
+    if cmd == "import-google":   # a Google Slides deck → a deck here (slides/gslides.py: OAuth once, then the Slides API)
+        from . import gslides
+        return gslides.main(rest + ([] if open_browser else ["--no-open"]))
+    if cmd == "init-remote":
+
+        if len(rest) != 1 or "/" not in rest[0]: raise SystemExit("usage: glideshow init-remote OWNER/REPO")
+        return init_remote(rest[0])
+
+    serve(match(" ".join(args)), open_browser)
+
+
+def run():   # the `glideshow` entry point
+    import signal
+    if hasattr(signal, "SIGPIPE"): signal.signal(signal.SIGPIPE, signal.SIG_DFL)   # `glideshow … | head` just stops
+    main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    run()
+

glideshow/comments.py

@@ -0,0 +1,35 @@
+"""Comments on a deck: comments.json beside deck.html, the same file glideshow.org writes when people comment on a
+shared deck (cloud/share.js has the format). Committed with the deck's saves."""
+
+import re, json, secrets, time
+from pathlib import Path
+
+
+def read(deck: Path) -> dict:
+    try: c = json.loads((deck / "comments.json").read_text())
+    except (OSError, ValueError): c = {}
+    return {"comments": c.get("comments") if isinstance(c.get("comments"), list) else []}
+
+
+def change(deck: Path, r: dict, by: dict) -> dict:
+    """add {slide, sid, box, x, y, quote, text} / reply {id, text} / resolve {id, resolved} / delete {id}."""
+    doc = read(deck); items = doc["comments"]
+    find = lambda i: next((c for c in items if c.get("id") == i), None)
+    text, now, rid = str(r.get("text", "")).strip()[:4000], time.strftime("%Y-%m-%dT%H:%MZ", time.gmtime()), lambda: secrets.token_hex(4)
+    who = {"n": by.get("n", ""), "e": by.get("e", "")}
+    op = r.get("op")
+    if op == "add" and text:
+        sid = str(r.get("sid") or "") if re.fullmatch(r"[\w-]{1,40}", str(r.get("sid") or "")) else ""   # the slide's data-sid: it finds the slide after slides move
+        items.append({"id": rid(), "slide": max(1, int(r.get("slide") or 1)), **({"sid": sid} if sid else {}), "box": str(r.get("box", ""))[:40], "x": round(float(r.get("x") or 0)), "y": round(float(r.get("y") or 0)),
+                      "quote": str(r.get("quote", ""))[:200], "text": text, "by": who, "at": now, "resolved": False, "replies": []})
+    elif op == "reply" and (c := find(r.get("id"))) and text:
+        c.setdefault("replies", []).append({"id": rid(), "text": text, "by": who, "at": now})
+    elif op == "resolve" and (c := find(r.get("id"))):
+        c["resolved"] = bool(r.get("resolved"))
+        c.setdefault("replies", []).append({"id": rid(), "text": "(resolved)" if c["resolved"] else "(reopened)", "by": who, "at": now, "event": True})
+    elif op == "delete" and (c := find(r.get("id"))):
+        items.remove(c)
+    else:
+        return {**doc, "error": "nothing to do"}
+    (deck / "comments.json").write_text(json.dumps({"comments": items}, indent=2) + "\n")
+    return {"comments": items}

glideshow/decks.py

@@ -0,0 +1,230 @@
+"""Deck folders: a new deck from the template (+ its AGENTS.md), pictures added from the command line, the recent
+list, the library ($GLIDESHOW_HOME) and switching the server to another deck."""
+
+import hashlib, json, os, re
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+# The editor's files and the docs copied into decks: inside the package when installed, beside it in the repository.
+EDITOR = HERE / "editor" if (HERE / "editor").is_dir() else HERE.parent / "editor"
+DOCS = HERE / "docs" if (HERE / "docs").is_dir() else HERE.parent / "docs"
+DECK_FILES = EDITOR / "deck"   # the template and what every deck carries inline: base.css, shapes.js, present.js
+
+
+def new_deck(path: Path, title: str = "") -> None:
+    html = (DECK_FILES / "template.html").read_text()
+    html = html.replace("{{BASE}}", (DECK_FILES / "base.css").read_text().strip())
+    html = html.replace("{{SHAPES}}", (DECK_FILES / "shapes.js").read_text().strip())
+    html = html.replace("{{PRESENT}}", (DECK_FILES / "present.js").read_text().strip())
+    if title:
+        import html as _html
+        html = re.sub(r"<title>.*?</title>", f"<title>{_html.escape(title)}</title>", html, count=1, flags=re.S)
+    import datetime   # every deck has a date (the talk's or meeting's), today's to start with
+    html = html.replace("</title>", f'</title>\n<meta name="date" content="{datetime.date.today().isoformat()}">', 1)
+    path.write_text(html)
+    write_agents_md(path.parent)
+
+
+def docs_text(part: str = "") -> str:
+    """AGENTS.md: the guide and recipes (docs/agents.md, with the layouts' table written from the editor's own) and the
+    format reference (docs/deck-format.md); `glideshow docs` prints the first ("guide"), `glideshow docs reference` the
+    second, so an agent reads the reference only when it needs it."""
+    from .agent import layout_table
+    guide = (DOCS / "agents.md").read_text().replace("{{LAYOUTS}}", layout_table()).rstrip()
+    ref = (DOCS / "deck-format.md").read_text()
+    return {"guide": guide, "reference": ref}.get(part) or guide + "\n\n" + ref
+
+
+def write_agents_md(deck: Path) -> None:
+    """AGENTS.md beside deck.html (docs_text)."""
+    (deck / "AGENTS.md").write_text(docs_text())
+
+
+def image_size(data: bytes):
+    """(width, height) of a PNG, JPEG or GIF, read from its header; None if unknown."""
+    import struct
+    if data[:8] == b"\x89PNG\r\n\x1a\n": return struct.unpack(">II", data[16:24])
+    if data[:6] in (b"GIF87a", b"GIF89a"): return struct.unpack("<HH", data[6:10])
+    if data[:2] == b"\xff\xd8":
+        i = 2
+        while i < len(data) - 9:
+            if data[i] != 0xFF: i += 1; continue
+            marker, size = data[i + 1], struct.unpack(">H", data[i + 2:i + 4])[0]
+            if marker in (0xC0, 0xC1, 0xC2): h, w = struct.unpack(">HH", data[i + 5:i + 9]); return w, h
+            i += 2 + size
+    return None
+
+
+def add_image(deck: Path, src: Path, slide: int | None = None) -> str:
+    """Copy a picture into assets/ and place it on slide N (1-based; default the last), fitted into the body area."""
+    data = src.read_bytes()
+    name = f"{hashlib.sha1(data).hexdigest()[:12]}{src.suffix.lower() or '.png'}"
+    (deck / "assets").mkdir(exist_ok=True); (deck / "assets" / name).write_bytes(data)
+    w0, h0 = image_size(data) or (1600, 900)
+    k = min(1680 / w0, 760 / h0); w, h = round(w0 * k), round(h0 * k)
+    x, y = 120 + (1680 - w) // 2, 240 + (760 - h) // 2
+    box = f'  <div class="box image" style="left: {x}px; top: {y}px; width: {w}px; height: {h}px;"><div class="content"><img src="assets/{name}" alt=""></div></div>\n'
+    html = (deck / "deck.html").read_text()
+    ends = [m.start() for m in re.finditer(r"</section>", html)]
+    leaves = [e for e in ends if not re.search(r"</section>\s*$", html[:e])]   # a stack's outer </section> follows an inner one
+    if not leaves: raise SystemExit("the deck has no slides")
+    at = leaves[(slide - 1) if slide else -1]
+    (deck / "deck.html").write_text(html[:at] + box + html[at:])
+    return f"assets/{name}"
+
+
+# Decks opened recently (newest first), for File → Open; the server can switch to another deck folder.
+RECENT = Path(os.environ.get("GLIDESHOW_CACHE") or Path.home() / ".glideshow") / "recent.json"
+
+
+def recent_decks() -> list:
+    try:
+        paths = json.loads(RECENT.read_text())
+    except (OSError, ValueError):
+        paths = []
+    return [p for p in paths if (Path(p) / "deck.html").exists()]
+
+
+# A new presentation is a draft until it has a title: it lives in ~/.glideshow/drafts/, outside the library (not listed,
+# not committed, not backed up), and moves into the library folder it was started from once it is named.
+DRAFTS = RECENT.parent / "drafts"
+UNTITLED = "Untitled deck"
+
+
+def is_draft(deck: Path) -> bool:
+    return DRAFTS.resolve() in deck.resolve().parents
+
+
+def new_draft(folder: str = "") -> Path:
+    import shutil, time as _t
+    for old in DRAFTS.glob("*") if DRAFTS.is_dir() else []:   # drafts nobody named within a day are dropped
+        if old.is_dir() and _t.time() - old.stat().st_mtime > 86400: shutil.rmtree(old, ignore_errors=True)
+    d = DRAFTS / f"draft-{int(_t.time() * 1000)}"
+    (d / "assets").mkdir(parents=True)
+    new_deck(d / "deck.html")
+    (d / ".draft.json").write_text(json.dumps({"folder": folder}))
+    return d
+
+
+def name_draft(d: Path) -> Path | None:
+    """The draft's new home in the library once it has a title, moved there; None while it is still untitled."""
+    import shutil
+    title = deck_title(d)
+    if title in ("", UNTITLED) or title == d.name: return None
+    try: folder = json.loads((d / ".draft.json").read_text()).get("folder", "")
+    except (OSError, ValueError): folder = ""
+    base = in_library(folder) / (re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")[:60] or "deck")
+    dst, n = base, 2
+    while dst.exists(): dst, n = Path(f"{base}-{n}"), n + 1
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    (d / ".draft.json").unlink(missing_ok=True)
+    shutil.move(str(d), dst)
+    return dst
+
+
+def remember(deck: Path) -> None:
+    if is_draft(deck): return   # drafts never show in recent decks
+    paths = [str(deck)] + [p for p in recent_decks() if p != str(deck)]
+
+    RECENT.parent.mkdir(parents=True, exist_ok=True)
+    RECENT.write_text(json.dumps(paths[:12]))
+
+
+def deck_date(deck: Path) -> str:
+    """The deck's date, <meta name="date" content="YYYY-MM-DD">, or '' when it has none."""
+    m = re.search(r'<meta name="date" content="(\d{4}-\d{2}-\d{2})"', (deck / "deck.html").read_text(errors="replace")[:20000])
+    return m.group(1) if m else ""
+
+
+def deck_title(deck: Path) -> str:
+    m = re.search(r"<title>(.*?)</title>", (deck / "deck.html").read_text(errors="replace"), re.S)
+    return (m.group(1).strip() if m else "") or deck.name
+
+
+HOME = Path(os.environ.get("GLIDESHOW_HOME") or Path.home() / "decks").expanduser()
+
+
+def walk_library():
+    """(decks, folders) under $GLIDESHOW_HOME: a folder holding deck.html is a deck (not looked inside); any other folder
+    groups decks and may nest. Hidden folders are skipped."""
+    decks, folders = [], []
+    def visit(d: Path, depth: int):
+        for c in sorted(d.iterdir()) if d.is_dir() else []:
+            if not c.is_dir() or c.name.startswith(".") or c.name == "assets": continue   # assets/ outside a deck is a leftover, not a folder
+
+            if (c / "deck.html").exists(): decks.append(c)
+            elif depth < 6: folders.append(c); visit(c, depth + 1)
+    visit(HOME, 0)
+    return decks, folders
+
+
+def folder_of(d: Path) -> str | None:
+    """The deck's folder in the library ('' at the top, 'Lab/2026' nested), or None for a deck outside it."""
+    try: rel = d.parent.resolve().relative_to(HOME.resolve())
+    except ValueError: return None
+    return "" if rel == Path(".") else rel.as_posix()
+
+
+
+def deck_id(d: Path) -> str:
+    return hashlib.sha1(str(d.resolve()).encode()).hexdigest()[:12]   # stable, unique even when two folders share a name
+
+
+def all_decks(current: Path) -> list:
+    """The current deck, recent decks and every deck in $GLIDESHOW_HOME (in any folder), newest edit first."""
+    seen, out = set(), []
+    for d in [current, *map(Path, recent_decks()), *walk_library()[0]]:
+        d = d.resolve()
+        if d in seen or not (d / "deck.html").exists() or d.name.startswith(".") or is_draft(d):
+
+            continue
+        seen.add(d)
+        out.append({"path": str(d), "id": deck_id(d), "name": d.name, "folder": folder_of(d), "title": deck_title(d), "shown": shown_title(d), "date": deck_date(d),
+
+                    "mtime": (d / "deck.html").stat().st_mtime, "current": d == current})
+    return sorted(out, key=lambda x: -x["mtime"])
+
+
+def shown_title(d: Path) -> str:
+    """What the home screen calls a deck: its title, or for a generic one ('Untitled deck', 'Untitled presentation')
+    the first line of text on its first slide ('' if it has none either)."""
+    t = deck_title(d)
+    if not re.fullmatch(r"\s*untitled( deck| presentation)?\s*", t, re.I): return t
+    html = (d / "deck.html").read_text(errors="replace")
+    first = html[html.find("<section"):][:200000]
+    first = first[:first.find("</section>")] if "</section>" in first else first
+    for m in re.finditer(r'<div class="box(?![^"]*\bnote\b)[^"]*"[^>]*>\s*<div class="content"[^>]*>(.*?)</div>\s*</div>', first, re.S):
+        lines = [re.sub(r"\s+", " ", l).strip() for l in re.sub(r"<[^>]+>", " ", re.sub(r"<(br|/div|/p|/li)[^>]*>", "\n", m.group(1))).split("\n")]
+        if line := next((l for l in lines if l), ""): return html_unescape(line)[:80]
+
+    return ""
+
+
+def html_unescape(s: str) -> str:
+    import html
+    return html.unescape(s)
+
+
+def library_folders() -> list:
+
+    """Every folder in the library as a path relative to $GLIDESHOW_HOME ('Lab', 'Lab/2026')."""
+    return [f.resolve().relative_to(HOME.resolve()).as_posix() for f in walk_library()[1]]
+
+
+def in_library(rel: str) -> Path:
+    """A folder path relative to $GLIDESHOW_HOME, refusing anything that would leave it."""
+    p = (HOME / (rel or "")).resolve()
+    if p != HOME.resolve() and HOME.resolve() not in p.parents: raise ValueError(f"{rel!r} is outside the library")
+    return p
+
+
+def forget(deck: Path) -> None:
+    RECENT.parent.mkdir(parents=True, exist_ok=True)
+    RECENT.write_text(json.dumps([p for p in recent_decks() if Path(p).resolve() != deck.resolve()]))
+
+
+
+def set_title(deck: Path, title: str) -> None:
+    import html as _html
+    f = deck / "deck.html"
+    f.write_text(re.sub(r"<title>.*?</title>", f"<title>{_html.escape(title)}</title>", f.read_text(), count=1, flags=re.S))