lectern-slides 0.1.0__tar.gz

lectern_slides-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Sync (runtime + dev group)
+        run: uv sync
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format --check
+        run: uv run ruff format --check .
+
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Sync (runtime + dev group + pdf extra)
+        run: uv sync --extra pdf
+      - name: pytest
+        run: uv run pytest

lectern_slides-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+# Publishes lectern-slides to PyPI when a GitHub Release is published.
+# Uses PyPI Trusted Publishing (OIDC) — no API token secret required. Configure
+# the trusted publisher once at https://pypi.org/manage/account/publishing/ with:
+#   owner=bsletten  repo=lectern-slides  workflow=release.yml  environment=pypi
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Build distributions
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Publish
+        run: uv publish

lectern_slides-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenvs / tooling
+.venv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# Lectern build artifacts (deck out_dir / build_dir defaults)
+/dist/
+/build/
+
+# PDF master cache (written under the deck's build_dir on -f pdf)
+.lectern-cache/
+
+# Editor backups (Emacs undo-tree, backups, autosaves)
+*.~undo-tree~
+*~
+\#*\#

lectern_slides-0.1.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to **lectern-slides** are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+aims to adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-17
+
+First public release. A dependency-light Python CLI (`lectern`) that assembles
+Markdown slide sources into one deck and renders it through a pluggable framework
+adapter, with a live-reload preview server and vector PDF export.
+
+### Assembly
+
+- Transclusion and slide-range includes with the `#1-3,14` range grammar.
+- Fence-aware slide splitter; relative + `partials` search-path resolution with
+  cycle and depth guards.
+- Frontmatter handling and a source-map so every diagnostic cites the
+  originating `file:line`/directive, never an internal offset.
+- `lectern assemble` and `lectern check` (validation + warnings, no render).
+
+### Rendering
+
+- Pluggable adapter registry: **reveal** (default) and **remark** native
+  adapters (Python + Jinja2 only), plus **marp** and **quarto** subprocess
+  adapters that `available()`-guard their external binary.
+- Remark input-compat normalizer so existing Remark decks assemble and render
+  unchanged.
+- Neutral directive syntax in HTML comments / Pandoc fenced divs: per-slide
+  classes/id/data-attributes, inline and block classes, content anchors, placed
+  boxes, and incremental builds.
+- Theme resolution with a token contract; ships a `base.css` plus a set of
+  swappable themes. A deck's own theme folder is discovered automatically.
+- Asset resolver (directory + URL `asset_base`): copies, content-hashes, and
+  rewrites references; garbage-collects orphaned hashed assets.
+- Mermaid diagrams, Font Awesome icons, image sizing, and raw HTML/`<canvas>`
+  passthrough.
+
+### Speaker notes
+
+- `<!-- notes -->` comment blocks and `::: {.notes}` fenced divs route to the
+  presenter view.
+- `notes:presenter` category for notes that show in the presenter view but are
+  **excluded from the printed PDF handout**; a mistyped category is flagged.
+
+### Watch + serve
+
+- `lectern watch` — Starlette/Uvicorn serving `dist/`, `watchfiles` rebuild, SSE
+  live-reload, and a build-error overlay.
+- `[serve].coi` COOP/COEP headers (the on-ramp for WASM-threads / WebGPU embeds).
+
+### PDF export
+
+- Vector master printed once via headless Chromium, then imposed and cached for
+  reuse across layout/color changes.
+- Layouts `1up`, `2up`, `2up-notes`, `4up`/`2x2`, `6up`, `3up-notes`; paper
+  presets and `WxH`; B&W (token and ghostscript engines), `--no-backgrounds`,
+  `--light-inverse`, and `--ink-saver`.
+- `-f pdf|pptx` output across capable adapters with graceful degradation.
+
+### Accessibility
+
+- `lectern check` runs a source-cited a11y audit by default: accessible-name and
+  alt-text checks, heading-order and contrast lint, tagged PDF output, a document
+  outline, and forced-colors support.
+
+[Unreleased]: https://github.com/bsletten/lectern-slides/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/bsletten/lectern-slides/releases/tag/v0.1.0

lectern_slides-0.1.0/CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md — Lectern
+
+Guidance for building Lectern with Claude Code. Read `SPECIFICATION.md` for the
+full design and `ROADMAP.md` for sequencing. This file is the operating manual.
+
+## What you are building
+
+A Python CLI (`lectern`) that assembles Markdown slide sources (transclusion +
+slide-range includes) into one deck and renders it via a pluggable framework
+adapter, with a live `--watch` preview server. It is the Markdown front-end to a
+larger resource-oriented slide system; keep the `Source` seam clean so a future
+CMS/graph backend can replace the filesystem source without changing anything
+downstream.
+
+## Prime directives
+
+- **Build the smallest thing that works, then grow.** Follow the milestones below
+  in order. Do not scaffold future phases speculatively.
+- **Keep the core dependency-light.** `reveal` and `remark` adapters use only
+  Python + templates. `marp`/`quarto` adapters shell out and must `available()`-
+  guard the external binary. Never make Pandoc a required dependency.
+- **Directives live in HTML comments** so raw `.md` stays valid CommonMark. The
+  assemble stage expands them.
+- **Pure where it matters.** `ranges.py`, the fence-aware splitter, and the
+  include resolver are pure functions with no I/O — they get the heaviest tests.
+- **Errors map to source.** Carry a source-map; every user-facing error cites the
+  originating `file:line`/directive, never an internal offset.
+- **Static-mostly.** Do not model animation timelines. Raw HTML/script passthrough
+  plus the asset pipeline is the entire animation story for now.
+
+## Tech choices (don't re-litigate)
+
+Python ≥3.11 · `typer` CLI · `pydantic` config · `jinja2` templates ·
+`python-frontmatter` · `watchfiles` · `starlette`+`uvicorn` server · `httpx` for
+URL assets · `tomllib` (stdlib). Package with hatchling: distribution name
+**`lectern-slides`** (PyPI/GitHub), import package `lectern`, `console_scripts` →
+`lectern`, PDF extra `lectern-slides[pdf]`, license **MIT** (`LICENSE` file +
+`license = "MIT"` in pyproject). (Import name `lectern` technically
+shares PyPI's Minecraft `lectern` namespace; harmless here — namespace to
+`lectern_slides` only if that ever matters.) Format with `ruff format`; lint with
+`ruff`; type-check with `pyright`/`mypy`.
+
+## Milestones (each ends in a working, committed, tested state)
+
+**M1 — assemble.** `ranges.py` (the `#1-3,14` grammar), fence-aware slide
+splitter, include resolver (relative + `partials` search paths + cycle/depth
+guards), frontmatter handling, source-map. `lectern assemble SOURCE -o out.md`
+and `lectern check SOURCE`. Unit + golden-file tests. No rendering yet.
+
+**M2 — render (reveal).** Config model, theme resolution + token injection,
+`reveal` adapter via Jinja2 template (assembled md → reveal.js HTML), asset
+resolver (dir + URL, copy + rewrite). `lectern build SOURCE`. Ship `themes/base.css`.
+
+**M3 — watch + serve.** Starlette/Uvicorn serving `dist/`, `watchfiles` rebuild,
+SSE live-reload, build-error overlay, `[serve].coi` COOP/COEP headers.
+`lectern watch SOURCE`.
+
+**M4 — remark adapter + migration.** Native `remark` adapter and the Remark
+input-compat normalizer (`.cls[]`, `class:`/`name:`/`layout:` property lines,
+`--` flatten) so existing decks assemble and render unchanged.
+
+**M5 — marp + quarto adapters.** Subprocess adapters with neutral→flavor lowering
+and `available()` guards; capability-based graceful degradation. `-f pdf|pptx`.
+
+**M6 — PDF finishing.** Per `PDF-EXPORT.md`: the 1-up vector master via Playwright
+ships earlier (M2); this milestone adds N-up imposition / `3up-notes` (pypdf +
+reportlab overlay),
+the B&W engines, `light_inverse`, auto poster capture, and handout chrome.
+
+Stop here for v1. Phases beyond (components/WASM/WebGPU, CMS source backend) are
+in `ROADMAP.md` and are *not* M-scope.
+
+## Working habits
+
+- Run `pytest` before declaring any milestone done; commit per milestone with a
+  short message.
+- When you touch `ranges.py`, the splitter, or the include resolver, add/adjust
+  tests in the same change — these are the load-bearing pure functions.
+- Add a `fixtures/` deck early (M1) that exercises includes, ranges, partials,
+  assets, classes, notes, and a raw-HTML/`<canvas>` slide; grow it as you go.
+- Prefer one clear way to do a thing over configurable cleverness. This is one
+  author's tool.
+
+## Seams to respect (so later phases are cheap, without building them now)
+
+- `source.py` `Source` protocol — filesystem now, CMS/graph later. Nothing
+  downstream may import filesystem paths directly; go through `Source`.
+- `render/base.py` registry — adapters are discovered, not hard-wired.
+- Theme **token contract** — components and adapters read tokens, never hardcode
+  colors/sizes.
+- `[serve].coi` headers — the on-ramp for WASM-threads/WebGPU embeds.
+
+## Definition of done (v1)
+
+`lectern watch ./talks/ai-sec` serves a live, reloading reveal deck assembled
+from a manifest with at least one ranged partial include and a URL `asset_base`;
+`lectern build -f pdf` produces a vector PDF; existing Remark decks render via the
+`remark` adapter unchanged; `pytest` is green.

lectern_slides-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Sletten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lectern_slides-0.1.0/PDF-EXPORT.md

@@ -0,0 +1,179 @@
+# PDF Export — Strategy
+
+How Lectern turns a deck into PDF. Read alongside `SPECIFICATION.md` (§7 reveal
+adapter) and `examples/sample-deck/`.
+
+## Principle
+
+One **vector master**, many cheap derivations.
+
+```
+                          render-time                 post-process
+  assembled deck ──▶ [ Chromium print: reveal     ──▶ 1-up master.pdf
+                       ?print-pdf, vector ]              │
+                       • backgrounds on/off              ├─▶ impose ──▶ 2-up / N-up / notes
+                       • light-inverse                   │     (pypdf places vector pages)
+                       • poster frames for embeds        └─▶ grayscale ──▶ B&W
+                       • fragments flatten/steps                (tokens or Ghostscript)
+```
+
+The master is always 1 slide / page, vector, full color. Everything the user
+asks for — 2-up, handouts with notes, B&W, no-backgrounds — is either a flag that
+changes the *master render* or a transform *applied to the master*. We never fall
+back to rasterizing the deck (that was DeckTape's failure mode).
+
+## Engines
+
+- **Render + capture:** Playwright for Python driving headless Chromium. One
+  dependency, no Node. Gives `page.pdf(...)` (vector, honors `@page`,
+  `print_background`) and `page.screenshot(...)` for poster capture, plus
+  `emulate_media(media="print", reduced_motion="reduce")`.
+- **Imposition (N-up / handouts):** `pypdf` (BSD-3-Clause, pure Python) places the
+  source *vector* pages scaled and translated into the grid via
+  `PageObject.add_transformation(Transformation().scale(s).translate(x, y))` +
+  `merge_page`. The handout chrome that pypdf can't draw — borders, slide numbers,
+  header/footer, and the **notes text** — is rendered as a thin overlay with
+  `reportlab` (BSD-3-Clause) and merged in. Both pure-Python and permissive, so the
+  whole tool stays MIT-clean. No quality loss (slide pages remain vector).
+- **Grayscale (optional, for full-document B&W incl. raster images):** Ghostscript
+  (`-sColorConversionStrategy=Gray`). External binary; only needed for the
+  `ghostscript` B&W engine (see Color/B&W).
+
+These live behind a `lectern-slides[pdf]` install extra so the core stays light.
+
+## Render-time options (change the master)
+
+| Option | Effect |
+| --- | --- |
+| `backgrounds = true\|false` | `print_background` on/off **and** an injected print stylesheet that hides `data-background-*` and `.inverse` fills when off. Default `true`. |
+| `light_inverse = true\|false` | Flip `.inverse` (dark) slides to light for ink economy, using the theme's own tokens (`--inverse-bg`→`--bg`, `--inverse-fg`→`--fg`). Default `false`. |
+| `fragments = "flatten"\|"steps"` | Maps to reveal `pdfSeparateFragments`. `flatten` = one page per slide with all builds shown (handout default); `steps` = one page per build. |
+| `paper = "deck"\|"letter"\|"a4"\|WxH` | `deck` (default) uses the slide aspect via `prefer_css_page_size` for the 1-up master; for a multi-up handout `deck` falls back to `letter` (a deck-shaped sheet leaves tiled slides tiny). Named sizes letterbox the slide for standard paper. |
+| `posters = "auto"\|"explicit"\|"off"` | How live embeds become stills (next section). |
+
+Because these change printed pixels, they are set when the master is rendered.
+The pipeline injects a small print stylesheet built on the **theme token
+contract**, so `light_inverse` / `backgrounds=off` work for any theme without the
+theme needing its own print block (a theme MAY still add `@media print`
+refinements; it's optional).
+
+## Animations → a default frame
+
+Live embeds (the D3 iframe today; WASM/WebGPU components later) can't animate in a
+PDF, so each resolves to one deterministic still. Resolution order:
+
+1. **Explicit poster.** `<iframe data-poster="assets/d3.png">` → that image is
+   used. Most predictable; recommended for anything you care about exactly.
+2. **Auto-capture** (`posters = "auto"`, the default). The pipeline loads the
+   embed in headless Chromium with reduced-motion emulated and `?static=1`
+   appended, waits `data-poster-at` ms (default 1200) — or for a
+   `window.lecternReady === true` signal if the embed sets one — screenshots the
+   embed's box to PNG, and swaps the `<iframe>` for an `<img>` in the print DOM.
+3. **Static-mode passthrough** (`posters = "off"` or capture unavailable). The
+   print render loads the embed with reduced-motion + `?static=1`; a well-behaved
+   embed paints a single frame, which prints inline. (This already works for the
+   sample's `d3-bars.html`, which honors `prefers-reduced-motion`.)
+
+**Embed authoring contract** (so an embed produces a clean default frame):
+- Honor `prefers-reduced-motion: reduce` **and** a `?static=1` query by drawing
+  one deterministic frame and not looping.
+- Optionally set `window.lecternReady = true` once that frame is painted, so
+  auto-capture knows when to shoot instead of guessing with `data-poster-at`.
+
+WebGPU/WASM note: headless Chromium needs ANGLE/SwiftShader flags
+(`--enable-unsafe-swiftshader`) for GPU contexts, and late-painting components
+should rely on explicit posters or `lecternReady` rather than a fixed delay.
+
+## Layout: 1-up, 2-up, N-up, handouts (imposition)
+
+The master is imposed onto sheets with pypdf (+ a reportlab overlay for chrome and
+notes). Presets:
+
+| `layout` | Sheet |
+| --- | --- |
+| `2up-notes` (**default**) | 2 slides stacked on a portrait page, each with its speaker notes beside it |
+| `1up` | the master, unchanged — clean projection slides |
+| `2up` | 2 slides stacked, no notes |
+| `4up` / `2x2` | 4 slides, 2×2 |
+| `6up` | 6 slides, 2×3 |
+| `3up-notes` | 3 slides down the left, **speaker notes beside each** |
+
+`2up-notes` is the default delivered layout: a portrait page holds two rows, each
+row a slide thumbnail (~58% width, left) with its notes column (right). Use
+`--layout 1up` when you want bare slides for projection. The notes are the real
+ones Lectern already parses from `<!-- notes -->` / `::: notes`, so handouts carry
+your script, not blank lines.
+
+Imposition controls: `paper`, `orientation` (`auto` by default — the sheet is
+turned to match the deck aspect, so wide 16:9 slides tile without big margins),
+`margins`, `gutter`,
+`frame = true|false` (hairline border per thumbnail), `slide_numbers`,
+`header` / `footer` (e.g. title, date, page x/y). All vector; text stays
+selectable.
+
+## Color / B&W
+
+Two engines, pick per taste:
+
+- **`tokens` (default, no dependency).** The pipeline reads the active theme's
+  color tokens, maps each to its perceptual-luminance gray, and injects the gray
+  token set for the render. Vector, text stays crisp, and contrast is *designed*
+  (the indigo and the vermilion seal become distinct grays rather than mud). Does
+  **not** recolor embedded raster images / captured posters — those stay as-is.
+- **`ghostscript` (full document).** Post-processes the finished PDF to DeviceGray,
+  converting everything including raster posters and images. Needs the `gs`
+  binary; use when you want guaranteed end-to-end grayscale.
+
+`color = "color" | "bw"`; `bw_engine = "tokens" | "ghostscript"`.
+
+Convenience preset: **`ink_saver = true`** = `bw` + `backgrounds = false` +
+`light_inverse = true`. The handout-friendly default for printing.
+
+## CLI & config
+
+```
+lectern build SOURCE -f pdf [--layout 1up] [--bw] [--no-backgrounds]
+                            [--light-inverse] [--ink-saver] [--paper a4]
+```
+
+```toml
+[pdf]
+layout        = "2up-notes"  # 2up-notes (default) | 1up | 2up | 4up | 6up | 3up-notes
+color         = "color"      # color | bw
+bw_engine     = "tokens"     # tokens | ghostscript
+backgrounds   = true
+light_inverse = false
+fragments     = "flatten"    # flatten | steps
+paper         = "deck"       # deck | letter | a4 | 1280x720
+posters       = "auto"       # auto | explicit | off
+poster_at     = 1200         # ms, default capture moment for auto posters
+tagged        = true         # emit a tagged (structured) PDF for screen readers;
+                             # preserved by the 1up master, flattened by N-up imposition
+
+# handout chrome (used by 2up/4up/6up/3up-notes)
+frame         = true
+slide_numbers = true
+gutter        = "10mm"
+header        = ""
+footer        = "{title} · {date} · {page}/{pages}"
+```
+
+CLI flags override `[pdf]`, which overrides defaults. `--ink-saver` expands to the
+three options above.
+
+## Caching & determinism
+
+The 1-up master is content-hashed and cached under the deck's `build_dir`
+(`build/.lectern-cache/`). Re-exporting `2up` then `4up` then `--bw` re-runs only
+imposition / conversion, not the (slow) Chromium render. Poster captures are
+cached per embed + `poster_at`. A given deck + options always produces a
+byte-stable master so diffs are meaningful. Because the cache lives in
+`build_dir`, `lectern clean` (which clears `out_dir`) keeps it; `lectern clean
+--all` drops it.
+
+## Milestone mapping
+
+- **M2** ships the 1-up vector master (`-f pdf`) — backgrounds toggle, fragments
+  flatten, poster *passthrough* (reduced-motion static frames).
+- A later milestone (**M6, PDF finishing**) adds imposition (N-up / `3up-notes`),
+  the B&W engines, `light_inverse`, auto poster capture, and handout chrome.