cappv1 1.7.0__py3-none-any.whl

cappv1/.env.example

@@ -0,0 +1,33 @@
+# Which AI service to use: openrouter, openai, anthropic, or ollama.
+# ollama runs the model on this computer: free, offline, and nothing leaves it
+# (see the README, "Private mode"). It needs no key.
+# Leave PROVIDER out and the first key you fill in below is used.
+PROVIDER=openrouter
+
+# Fill in the key for the provider you chose (the others can stay blank).
+OPENROUTER_API_KEY=your-key-here
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+
+# MODEL / FALLBACK_MODEL must be models from the provider you chose.
+# Leave MODEL blank to use that provider's default:
+#   openrouter: minimax/minimax-m3:free   (fallback google/gemma-3-12b-it)
+#   openai:     gpt-4o-mini
+#   anthropic:  claude-haiku-5-5
+#   ollama:     gemma3:4b   (must be a vision model you've downloaded with: ollama pull <name>)
+# FALLBACK_MODEL is tried when MODEL is unavailable, rate-limited, or out of credits.
+# Avoid "reasoning" models here - they burn completion tokens on hidden thinking,
+# which can starve short caption outputs.
+MODEL=
+FALLBACK_MODEL=
+# Leave blank for the default: 4 at a time (1 for ollama).
+CONCURRENCY=
+MIN_IMAGE_SIZE_PX=40
+# Alt text the author already wrote that is shorter than this is treated as unfinished
+# and improved; longer text is kept unless the AI judges it inadequate. Blank = 30.
+MIN_EXISTING_ALT_CHARS=
+MAX_ALT_TEXT_CHARS=125
+
+# Ollama only. Defaults shown; you normally don't need to touch these.
+# OLLAMA_BASE_URL=http://localhost:11434
+# REQUEST_TIMEOUT=300

cappv1/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to cappv1. Versions follow [Semantic Versioning](https://semver.org): MAJOR.MINOR.PATCH.
+
+## 1.7.0 - 2026-10-30
+
+### New
+
+- Changelog page under Learn: a card per release with its date, grouped into new, improved and fixed. It is read from this file, so it is always current.
+- Appearance page under Learn: choose the theme and an accent color (blue, teal, green, purple, rose or amber) for buttons and links, each checked for contrast in light and dark. Remembered in this browser. They are no longer in the sidebar.
+- Install with `pipx install cappv1` (or `pipx install git+https://github.com/srsuiux/cappv1.git`). No cloning, symlink or virtual environment.
+- cappv1 is published on PyPI, so `pipx install cappv1` works. Releases are built and uploaded by GitHub Actions when a version tag is pushed, using PyPI Trusted Publishing (no stored token).
+- Install cappv1 from the browser as an app with its own window. It still needs to be running, and the address it prints, to connect.
+- Each run keeps its finished copies in `output/<date>_<time>/` instead of replacing the last ones. Download or delete one copy or a whole run from the Files page, or in the terminal with `/history` and `/remove`; both see the change. Copies left loose in `output/` by older versions show as the oldest run.
+
+### Changed
+
+- **You will notice:** `cappv1 --batch` now runs in the foreground and prints the log, instead of starting a background job and returning. A script that relied on it returning at once should run `cappv1 --batch &` itself.
+- **You will notice:** when cappv1 is installed with pipx, your settings (`.env`), `input`, `output`, saved progress and logs live in `~/cappv1` (or the folder in `CAPPV1_HOME`). A cloned copy still uses its own project folder, so nothing moves for existing users; if you switch from a clone to pipx, copy `.env` and the folders you want into `~/cappv1`.
+
+### Improved
+
+- The Python package is now `cappv1` (it was `src`), and `pyproject.toml` is the only place dependencies are listed. `python -m cappv1` also works.
+- Checks on every push and pull request: ruff (lint and format), mypy, tests on Linux and macOS with Python 3.11 to 3.13 and coverage, a wheel build that is installed and run, and a link check for the docs. Dependabot keeps dependencies and Actions up to date, and `pre-commit` runs the same lint locally.
+- Type checking: mypy now covers every module except a short list still being fixed (tracked in issue #1). Five modules were fixed in this release.
+- A test runs the sample deck and checks that only alt text changed in the finished copy.
+- The docs are split into focused pages under `docs/`, with an index.
+- Every page now uses the full window width, in the same card layout as Files, with a shared page header.
+- The window is fixed to the screen and only the content scrolls; the sidebar no longer folds.
+- Files page: three panels (Current files, Past files, Finished copies), with sizes and dates on each card. Long processing notes moved into a ? on the card that shows them on hover, focus or tap.
+
+### Fixed
+
+- PowerPoint: finished decks open without the repair prompt and preview in Blackboard. The output is now the original file with only the slides that got alt text replaced, instead of a python-pptx re-save, which dropped embedded-object relationships with `Target="NULL"` and left slides pointing at nothing.
+
+## 1.6.0 - 2026-10-29
+
+### New
+
+- Word: Blackboard Ally structure fixes. Heading levels are renumbered to start at Heading 1 with no gaps, using copies of the existing heading styles so nothing looks different; captions become Heading 1 in a document with no headings; empty headings stop being headings; every table gets a header row, including one-row boxes; the Title property is filled when empty or wrong; text that fails the 4.5:1 contrast check is darkened to 7:1 and noted (the one visible change). `python -m src.docx_check` checks a file against these rules.
+- Word: a table's first row is now marked as its header (the Header Row box and Repeat as header row), which Blackboard Ally needs: a test file scored 100% with both and 68% with the box alone. Only plain tables: no table style, two or more rows and columns, text in every first-row cell, nothing merged. One visible effect, which the owner accepted: a table that runs onto a second page repeats its header row there. Applied even in documents where table descriptions are skipped.
+- Word: embedded objects (for example Visio drawings) now get alt text, so an accessibility checker no longer sees them as undescribed pictures. The Privacy page now lists the text read from an embedded object.
+- Files page: every file has a checkbox, with Select all and a count. "Improve accessibility" runs only the ticked files (`POST /runs` takes `files`). New files are ticked for you; previous files can be ticked too. "Remove all" empties the Current files list after an inline confirmation.
+
+### Improved
+
+- Sidebar: an icon beside every link, and a button that folds it to an icon rail (remembered in this browser). The theme choice is now three icon buttons (System, Light, Dark) with tooltips and screen-reader names.
+- A damaged item no longer stops a file. A slide or document item that cannot be read (for example an embedded object whose part is missing, which used to end the file with "no relationship with key 'rId4'") is skipped, noted in the file's saved progress and the log, and the rest finishes. The Files page lists what was skipped under each file and marks the slide, and the terminal run view prints it. Applies to decks and Word documents.
+- A run started from the browser now prints its log in the terminal that started cappv1 (`--web`, or `/web` in the terminal session).
+
+### Fixed
+
+- Word: finished copies open in Word and preview in Blackboard. The output is now the original file with only `word/document.xml` replaced, instead of a python-docx re-save. Documents saved in Word compatibility mode 11 or 12 (what LibreOffice writes) get no table alt text, because Word refuses to open them with it; picture alt text is unaffected, and one note says to use Save As in Word first.
+- Fixes a stray "null" shown on the finished-run card.
+
+## 1.5.0 - 2026-10-29
+
+### New
+
+- Word documents (`.docx`): pictures and tables get alt text (`wp:docPr` description and `w:tblDescription`), through the terminal, the batch command and the web UI. Charts, SmartArt, embedded objects and headers/footers are not handled yet, and `/audit` stays decks-only.
+
+### Improved
+
+- The Files page shows a deck's slide tiles or a document's item chips, lists current files apart from previous (already finished) ones, and always shows the "replace alt text" option, off by default.
+- Wording now describes cappv1 as improving accessibility (by writing alt text) for PowerPoint and Word.
+
+### Changed
+
+- API: the upload error code `not_pptx` is now `unsupported_file`; the audit of a Word file returns `audit_unsupported`. Run events carry `kind`.
+
+## 1.4.3 - 2026-10-27
+
+- On the Files page, a finished run shows every slide tile instead of clipping long decks.
+
+## 1.4.2 - 2026-10-27
+
+- The contrast audit now also checks text in table cells and in grouped shapes.
+
+## 1.4.1 - 2026-10-27
+
+- Fixes a syntax error that stopped cappv1 from installing on Python 3.11 (1.4.0 only works on 3.12 and newer, so use 1.4.1).
+
+## 1.4.0 - 2026-10-27
+
+- The Files page now puts a run front and center: a card at the top shows each slide lighting up and ticking off, what cappv1 is reading, and, when done, a clear "Your finished document is ready" card with Download, the saved location, and a note that the original is unchanged. The finished file is marked in the list too. Animations respect reduced-motion settings.
+- The Files page has a Check accessibility button that shows the same report in the browser.
+- New `/audit` command and `GET /api/v1/files/<name>/audit`: reports low-contrast text (WCAG AA, judged against the real backdrop including template shapes, patterns and gradients) and slides whose reading order doesn't follow the layout. Findings with the same cause are grouped across slides. It only reports; colors and layout are never changed.
+
+## 1.3.0 - 2026-10-27
+
+- A table's first row is now flagged as its header when that changes nothing visually (no table style, two or more rows, every first-row cell filled, nothing merged). This fixes Blackboard Ally's "tables are missing headers". Tables where it would change the look are left alone and the reason is logged.
+- `skills.md` now allows a short list of visually inert accessibility fixes beyond alt text. Colors, including low contrast, are never changed.
+
+## 1.2.0 - 2026-10-27
+
+### Added
+- **Local web interface** (`cappv1 --web`, or `/web` inside cappv1; `/init` now ends by offering the browser or the terminal). It is a small site served on this computer only:
+  - A front page that introduces cappv1 to new visitors and, once you're set up, leads with an Overview (next step, file counts, service, health, data) and moves the introduction below it.
+  - Files (add decks, run, live feed of the alt text being written, stop, download), Services (choose service, model and key), Health, and Your data (what is kept and where, with an erase button).
+  - How it works, Privacy, FAQ and About pages. The Privacy page states exactly what is sent to an AI service and what is stored, and a test keeps it in step with the code.
+  - Light, dark and system themes with a switch in the side panel, applied before the page paints; a test checks the contrast of every color pair in both themes. Keyboard, screen-reader and small-screen friendly; a favicon.
+- **Web server and API** (`src/web`, standard library only, documented in `docs/API.md`): bound to this computer, per-launch token, Host check, strict content policy, size-limited validated uploads, live progress over Server-Sent Events that resumes after a dropped connection.
+- Each service says what it does with your slides and links to its privacy policy; saved API keys can be removed from Services.
+- A new `alt_written` progress event carrying each piece of alt text as it is settled.
+- `src/services/`, a service layer between the engine and the screens, with a pytest suite and GitHub Actions CI.
+- `CAPPV1_HOME` to keep settings, decks and progress in a folder of your choice.
+- Project files: `SECURITY.md`, `CODE_OF_CONDUCT.md`, issue and pull request templates, `.editorconfig`, `pyproject.toml`, and `docs/ARCHITECTURE.md`.
+
+### Fixed
+- Pictures are matched by their exact bytes. Before, flat or near-identical images (for example two solid-color pictures) could share one caption.
+- A picture whose "alt text" is only its file name (`image1.png`, filled in by some tools) is no longer treated as text the author wrote.
+- The terminal toolbar no longer re-reads every deck on each keystroke.
+
+### Changed
+- No more colored bars down one side of panels, menu items or messages; they use whole, subtle borders instead. The three steps and other boxes follow the same paper-like style.
+- `cappv1` is now the only command in the shell. `cappv1 doctor`, `models`, `clean`, `init` and `start` are refused; use `/doctor`, `/models`, `/clean` and the others inside the session. `cappv1 --batch` remains for scripts, plus `--version` and `--help`.
+- `/init` shows the current service and model first and lets you keep it, change only the model, or switch service, instead of asking everything again. `/models` goes straight to the service and model pickers. Both are listed in `/help` and in the `/` menu.
+
+## 1.1.0 - 2026-10-26
+
+### Added
+- Interactive terminal session (`cappv1`, `cappv1 start`, `cappv1 init`): slash commands with completion, arrow-key menus, drag-and-drop of `.pptx` files, and a live run view whose animation follows what is happening (picture, chart, table, diagram, saving).
+- Local, private captioning with Ollama (`PROVIDER=ollama`); nothing leaves the computer, and a remote Ollama address is refused unless explicitly allowed.
+- `/models`: one flow to switch AI service and model, including free and paid OpenRouter vision models with prices (reaches DeepSeek, Google, OpenAI and more).
+- Alt text that authors already wrote is built on, not replaced: short text is improved, adequate text is kept as written. `/run --force` replaces it after confirmation.
+- Edited decks are recognised by content hash and reprocessed; unchanged items reuse saved captions. Unchanged files are reported as already captioned.
+
+### Fixed
+- Resuming after a crash lost the captions of slides finished before the crash.
+- One unreadable progress file stopped the whole run; it is now set aside.
+- Output and progress files are written atomically, so a crash cannot leave a half-written file.
+- An edited deck with the same filename was skipped as "already complete".
+
+### Changed
+- `cappv1 start` opens the interactive session. The old background behavior is `cappv1 start --batch` (also used automatically when there is no terminal).
+
+## 1.0.0 - 2026-10-26 (tag `engine-cappv1-1.0.0`)
+
+- Terminal engine: alt text for pictures, tables, charts, SmartArt and embedded objects; invisible shapes marked decorative; files processed in sequence and resumable.
+- Providers: OpenRouter, OpenAI, Anthropic, and Ollama.

cappv1/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from cappv1.main import main
+
+sys.exit(main())

cappv1/audit.py

@@ -0,0 +1,377 @@
+"""Read-only accessibility checks that report problems but never change a deck.
+
+Two checks: text that is hard to read against its background, and slides whose
+reading order (the order a screen reader follows, which is the order shapes
+appear in the slide's XML) disagrees with how they are laid out. Colors and
+layout belong to the author, so nothing here is ever written back."""
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from pptx.oxml.ns import qn
+
+from cappv1.audit_color import _Theme, contrast_ratio
+from cappv1.pptx_reader import open_presentation
+
+_A = "http://schemas.openxmlformats.org/drawingml/2006/main"
+NORMAL_MIN, LARGE_MIN = 4.5, 3.0  # WCAG 2.x AA
+_EMU_PER_PT = 12700
+
+
+@dataclass
+class Finding:
+    slide: int
+    kind: str  # contrast | reading_order
+    message: str
+    detail: str = ""
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class Report:
+    findings: list
+    checked_text: int  # text runs whose colors could be resolved and measured
+    unmeasured_text: int  # runs on gradients, pictures or unusual colors: not judged
+
+    def grouped(self) -> list:
+        """Findings with the same cause collapsed: one entry, many slides."""
+        groups: dict = {}
+        for f in self.findings:
+            key = (f.kind, f.detail if f.kind == "contrast" else f.message + f.detail)
+            g = groups.setdefault(key, {"kind": f.kind, "message": f.message, "detail": f.detail, "slides": []})
+            g["slides"].append(f.slide)
+        return list(groups.values())
+
+    def as_dict(self) -> dict:
+        return {
+            "groups": self.grouped(),
+            "problems": len(self.findings),
+            "checked_text": self.checked_text,
+            "unmeasured_text": self.unmeasured_text,
+        }
+
+
+def _fill_colors(theme: _Theme, pr, phclr=None) -> list | None:
+    """Every color a fill can show: one for solid, the stops for a gradient, both
+    colors for a pattern. None when it can't be judged (a picture, or odd colors)."""
+    if pr is None:
+        return None
+    for tag, path in (("solidFill", "."), ("gradFill", ".//" + f"{{{_A}}}gs"), ("pattFill", None)):
+        el = pr.find(f"{{{_A}}}{tag}")
+        if el is None:
+            continue
+        if tag == "pattFill":
+            parts = [c[0] for c in (el.find(f"{{{_A}}}fgClr"), el.find(f"{{{_A}}}bgClr")) if c is not None and len(c)]
+        elif tag == "gradFill":
+            parts = [gs[0] for gs in el.iter(f"{{{_A}}}gs") if len(gs)]
+        else:
+            parts = [el[0]] if len(el) else []
+        colors = [theme.resolve(p, phclr) for p in parts]
+        return colors if colors and all(colors) else None
+    return None
+
+
+def _has_nonsolid_fill(el) -> bool:
+    return el is not None and any(el.find(f"{{{_A}}}{t}") is not None for t in ("gradFill", "blipFill", "pattFill"))
+
+
+def _background(theme: _Theme, slide) -> str | None:
+    """The slide's background color: its own, else its layout's, else the master's."""
+    for part in (slide, slide.slide_layout, slide.slide_layout.slide_master):
+        bg = part._element.find(f".//{qn('p:bg')}")
+        if bg is None:
+            continue
+        pr = bg.find(qn("p:bgPr"))
+        if pr is not None:
+            return _fill_colors(theme, pr)
+        ref = bg.find(qn("p:bgRef"))
+        if ref is not None and len(ref):
+            phclr = theme.resolve(ref[0])
+            idx = int(ref.get("idx", "0"))
+            if 1001 <= idx < 1001 + len(theme.fills) and phclr:
+                style = theme.fills[idx - 1001]
+                if style.tag.endswith("solidFill") and len(style):
+                    return [theme.resolve(style[0], phclr)]
+            return None
+    return ["FFFFFF"]
+
+
+def _shape_fill(theme: _Theme, el) -> tuple[bool, list | None]:
+    """(has_own_fill, colors). Own fills on a text shape replace the slide background."""
+    sp_pr = el.find(qn("p:spPr"))
+    if sp_pr is None or sp_pr.find(f"{{{_A}}}noFill") is not None:
+        return False, None
+    if not any(sp_pr.find(f"{{{_A}}}{t}") is not None for t in ("solidFill", "gradFill", "blipFill", "pattFill")):
+        ref = el.find(f"{qn('p:style')}/{{{_A}}}fillRef")
+        if ref is not None and ref.get("idx", "0") != "0":
+            return True, None  # filled by the theme's shape style: not judged
+        return False, None
+    return True, _fill_colors(theme, sp_pr)
+
+
+# ---- contrast --------------------------------------------------------------------
+def _placeholder_chain(slide, sp):
+    """The shape's own element, then the layout's and master's matching placeholders."""
+    chain = [sp]
+    ph = sp.find(f"{qn('p:nvSpPr')}/{qn('p:nvPr')}/{qn('p:ph')}")
+    if ph is None:
+        return chain, None
+    for part in (slide.slide_layout, slide.slide_layout.slide_master):
+        for cand in part._element.iter(qn("p:sp")):
+            cph = cand.find(f"{qn('p:nvSpPr')}/{qn('p:nvPr')}/{qn('p:ph')}")
+            if cph is None:
+                continue
+            same_idx = ph.get("idx") is not None and cph.get("idx") == ph.get("idx")
+            same_type = ph.get("idx") is None and (cph.get("type") or "obj") == (ph.get("type") or "obj")
+            title = {"title", "ctrTitle"}
+            if same_idx or same_type or (ph.get("type") in title and cph.get("type") in title):
+                chain.append(cand)
+                break
+    return chain, ph.get("type") or "body"
+
+
+def _run_color(theme: _Theme, run, para, slide, sp) -> str | None:
+    rpr = run.find(qn("a:rPr"))
+    if rpr is not None and _has_nonsolid_fill(rpr):
+        return None
+    color = theme.solid(rpr) if rpr is not None else None
+    if color:
+        return color
+    ppr = para.find(qn("a:pPr"))
+    lvl = f"lvl{int(ppr.get('lvl', '0')) + 1 if ppr is not None else 1}pPr"
+    dflt = ppr.find(qn("a:defRPr")) if ppr is not None else None
+    color = theme.solid(dflt) if dflt is not None else None
+    if color:
+        return color
+    chain, kind = _placeholder_chain(slide, sp)
+    for shape in chain:
+        node = shape.find(f".//{qn('p:txBody')}/{{{_A}}}lstStyle/{{{_A}}}{lvl}/{{{_A}}}defRPr")
+        color = theme.solid(node) if node is not None else None
+        if color:
+            return color
+    styles = slide.slide_layout.slide_master._element.find(qn("p:txStyles"))
+    group = "titleStyle" if kind in ("title", "ctrTitle") else ("bodyStyle" if kind else "otherStyle")
+    node = styles.find(f"{qn('p:' + group)}/{{{_A}}}{lvl}/{{{_A}}}defRPr") if styles is not None else None
+    color = theme.solid(node) if node is not None else None
+    if color:
+        return color
+    ref = sp.find(f"{qn('p:style')}/{{{_A}}}fontRef")
+    if ref is not None and len(ref):
+        return theme.resolve(ref[0])
+    return theme.resolve(_synthetic("tx1"))
+
+
+def _synthetic(name):
+    from lxml import etree
+
+    return etree.Element(f"{{{_A}}}schemeClr", val=name)
+
+
+def _size_pt(run) -> float:
+    rpr = run.find(qn("a:rPr"))
+    sz = rpr.get("sz") if rpr is not None else None
+    return int(sz) / 100 if sz else 18.0  # PowerPoint's default body size
+
+
+def _bold(run) -> bool:
+    rpr = run.find(qn("a:rPr"))
+    return rpr is not None and rpr.get("b") in ("1", "true")
+
+
+def _through_groups(el, box):
+    """Maps a box from a group's own coordinate space out to the slide, group by group."""
+    x, y, w, h = box
+    parent = el.getparent()
+    while parent is not None and parent.tag == qn("p:grpSp"):
+        xf = parent.find(f"{qn('p:grpSpPr')}/{{{_A}}}xfrm")
+        if xf is not None and all(xf.find(f"{{{_A}}}{t}") is not None for t in ("off", "ext", "chOff", "chExt")):
+            g = {t: xf.find(f"{{{_A}}}{t}") for t in ("off", "ext", "chOff", "chExt")}
+            cw, ch = int(g["chExt"].get("cx")) or 1, int(g["chExt"].get("cy")) or 1
+            sx, sy = int(g["ext"].get("cx")) / cw, int(g["ext"].get("cy")) / ch
+            x = int(g["off"].get("x")) + (x - int(g["chOff"].get("x"))) * sx
+            y = int(g["off"].get("y")) + (y - int(g["chOff"].get("y"))) * sy
+            w, h = w * sx, h * sy
+        parent = parent.getparent()
+    return x, y, w, h
+
+
+def _box(chain):
+    """(x, y, w, h) of a shape on the slide, taken from the first of its placeholder chain that sets one."""
+    for el in chain:
+        xfrm = el.find(f"{qn('p:spPr')}/{{{_A}}}xfrm")
+        if xfrm is not None and xfrm.find(f"{{{_A}}}off") is not None and xfrm.find(f"{{{_A}}}ext") is not None:
+            off, ext = xfrm.find(f"{{{_A}}}off"), xfrm.find(f"{{{_A}}}ext")
+            raw = (int(off.get("x")), int(off.get("y")), int(ext.get("cx")), int(ext.get("cy")))
+            return _through_groups(el, raw) if el is chain[0] else raw
+    return None
+
+
+def _covers(el, point) -> bool:
+    box = _box([el])
+    if box is None:
+        return False
+    x, y, w, h = box
+    px, py = point
+    geom = el.find(f"{qn('p:spPr')}/{{{_A}}}prstGeom")
+    if geom is not None and geom.get("prst") == "ellipse":
+        return w > 0 and h > 0 and ((px - x - w / 2) / (w / 2)) ** 2 + ((py - y - h / 2) / (h / 2)) ** 2 <= 1
+    return x <= px <= x + w and y <= py <= y + h
+
+
+def _behind(theme: _Theme, slide, sp, fallback):
+    """The colors a text shape sits on: the topmost filled shape beneath its center
+    (master, then layout, then earlier shapes on the slide), else the slide background."""
+    chain, _ = _placeholder_chain(slide, sp)
+    box = _box(chain)
+    if box is None:
+        return fallback
+    return _behind_point(theme, slide, sp, (box[0] + box[2] / 2, box[1] + box[3] / 2), fallback)
+
+
+def _behind_point(theme: _Theme, slide, sp, point, fallback):
+    if point is None:
+        return fallback
+    found = fallback
+    layers = [slide.slide_layout.slide_master._element, slide.slide_layout._element]
+    for root in layers:
+        for cand in root.iter(qn("p:sp")):
+            if cand.find(f"{qn('p:nvSpPr')}/{qn('p:nvPr')}/{qn('p:ph')}") is not None:
+                continue
+            has, colors = _shape_fill(theme, cand)
+            if has and _covers(cand, point):
+                found = colors
+    for cand in slide._element.iter(qn("p:sp")):
+        if cand is sp:
+            break
+        has, colors = _shape_fill(theme, cand)
+        if has and _covers(cand, point):
+            found = colors
+    return found
+
+
+def check_contrast(prs) -> tuple[list, int, int]:
+    theme = _Theme(prs)
+    findings, measured, unmeasured = [], 0, 0
+    for number, slide in enumerate(prs.slides, 1):
+        bg = _background(theme, slide)
+        seen: set = set()
+        for sp in slide._element.iter(qn("p:sp")):
+            own, fill = _shape_fill(theme, sp)
+            backdrop = fill if own else _behind(theme, slide, sp, bg)
+            for para in sp.iter(f"{{{_A}}}p"):
+                for run in para.findall(qn("a:r")):
+                    text = (run.findtext(qn("a:t")) or "").strip()
+                    if not text:
+                        continue
+                    fg = _run_color(theme, run, para, slide, sp)
+                    if not fg or not backdrop:
+                        unmeasured += 1
+                        continue
+                    measured += 1
+                    ratio = min(contrast_ratio(fg, b) for b in backdrop)
+                    size = _size_pt(run)
+                    need = LARGE_MIN if size >= 18 or (size >= 14 and _bold(run)) else NORMAL_MIN
+                    shown = ", ".join("#" + b for b in backdrop)
+                    if ratio < need and (fg, tuple(backdrop), text[:30]) not in seen:
+                        seen.add((fg, tuple(backdrop), text[:30]))
+                        findings.append(
+                            Finding(
+                                number,
+                                "contrast",
+                                f"“{text[:50]}” is hard to read.",
+                                f"Contrast {ratio:.1f}:1, needs {need}:1 (text #{fg} on {shown}).",
+                            )
+                        )
+        # table cells: each cell's own fill, else the table frame's backdrop
+        for frame in slide._element.iter(qn("p:graphicFrame")):
+            tbl = frame.find(f".//{{{_A}}}tbl")
+            if tbl is None:
+                continue
+            styled = tbl.find(f"{{{_A}}}tblPr/{{{_A}}}tableStyleId") is not None
+            xf = frame.find(qn("p:xfrm"))
+            where = None
+            if xf is not None:
+                off, ext = xf.find(f"{{{_A}}}off"), xf.find(f"{{{_A}}}ext")
+                where = (int(off.get("x")) + int(ext.get("cx")) // 2, int(off.get("y")) + int(ext.get("cy")) // 2)
+            frame_bg = _behind_point(theme, slide, frame, where, bg)
+            for cell in tbl.iter(f"{{{_A}}}tc"):
+                pr = cell.find(f"{{{_A}}}tcPr")
+                own = pr is not None and any(pr.find(f"{{{_A}}}{t}") is not None for t in ("solidFill", "gradFill", "blipFill", "pattFill"))
+                if pr is not None and pr.find(f"{{{_A}}}noFill") is not None:
+                    own = False
+                backdrop = _fill_colors(theme, pr) if own else (None if styled else frame_bg)
+                for para in cell.iter(f"{{{_A}}}p"):
+                    for run in para.findall(qn("a:r")):
+                        text = (run.findtext(qn("a:t")) or "").strip()
+                        if not text:
+                            continue
+                        rpr = run.find(qn("a:rPr"))
+                        fg = theme.solid(rpr) if rpr is not None else None
+                        if not fg and not styled:
+                            fg = theme.resolve(_synthetic("tx1"))
+                        if not fg or not backdrop:
+                            unmeasured += 1
+                            continue
+                        measured += 1
+                        ratio = min(contrast_ratio(fg, b) for b in backdrop)
+                        size = _size_pt(run)
+                        need = LARGE_MIN if size >= 18 or (size >= 14 and _bold(run)) else NORMAL_MIN
+                        shown = ", ".join("#" + b for b in backdrop)
+                        if ratio < need and (fg, tuple(backdrop), text[:30]) not in seen:
+                            seen.add((fg, tuple(backdrop), text[:30]))
+                            findings.append(
+                                Finding(
+                                    number,
+                                    "contrast",
+                                    f"“{text[:50]}” is hard to read.",
+                                    f"Contrast {ratio:.1f}:1, needs {need}:1 (text #{fg} on {shown}).",
+                                )
+                            )
+    return findings, measured, unmeasured
+
+
+# ---- reading order ---------------------------------------------------------------
+def _meaningful(shape) -> bool:
+    el = shape._element
+    if el.tag in (qn("p:pic"), qn("p:graphicFrame"), qn("p:grpSp")):
+        return True
+    return el.tag == qn("p:sp") and bool(shape.has_text_frame and shape.text_frame.text.strip())
+
+
+def check_reading_order(prs) -> list:
+    findings = []
+    for number, slide in enumerate(prs.slides, 1):
+        items = [s for s in slide.shapes if _meaningful(s) and None not in (s.top, s.height, s.left)]
+        title = slide.shapes.title
+        if title is not None and title.text_frame.text.strip() and items and items[0].shape_id != title.shape_id:
+            findings.append(
+                Finding(number, "reading_order", "The title is not read first.", f"A screen reader starts with “{_label(items[0])}”.")
+            )
+            continue
+        for i, first in enumerate(items):
+            above = next((later for later in items[i + 1 :] if later.top + later.height <= first.top), None)
+            if above is not None:
+                findings.append(
+                    Finding(
+                        number,
+                        "reading_order",
+                        "Reading order does not follow the layout.",
+                        f"“{_label(first)}” is read before “{_label(above)}”, which sits above it.",
+                    )
+                )
+                break
+    return findings
+
+
+def _label(shape) -> str:
+    text = shape.text_frame.text.strip() if shape.has_text_frame else ""
+    return (text or shape.name)[:40]
+
+
+# ---- entry point -----------------------------------------------------------------
+def audit_deck(path: Path) -> Report:
+    prs = open_presentation(path)
+    contrast, measured, unmeasured = check_contrast(prs)
+    return Report(contrast + check_reading_order(prs), measured, unmeasured)

cappv1/audit_color.py

@@ -0,0 +1,87 @@
+"""Color maths and theme colors for the read-only accessibility check (see audit.py)."""
+
+from pptx.oxml.ns import qn
+
+_A = "http://schemas.openxmlformats.org/drawingml/2006/main"
+
+
+# ---- colors ----------------------------------------------------------------------
+def _lum(hex6: str) -> float:
+    chan = [int(hex6[i : i + 2], 16) / 255 for i in (0, 2, 4)]
+    chan = [c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4 for c in chan]
+    return 0.2126 * chan[0] + 0.7152 * chan[1] + 0.0722 * chan[2]
+
+
+def contrast_ratio(a: str, b: str) -> float:
+    hi, lo = sorted((_lum(a), _lum(b)), reverse=True)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+def _hls(hex6):
+    import colorsys
+
+    r, g, b = (int(hex6[i : i + 2], 16) / 255 for i in (0, 2, 4))
+    return colorsys.rgb_to_hls(r, g, b)
+
+
+def _from_hls(h, l, s) -> str:
+    import colorsys
+
+    r, g, b = colorsys.hls_to_rgb(h, min(max(l, 0), 1), s)
+    return "".join(f"{round(c * 255):02X}" for c in (r, g, b))
+
+
+class _Theme:
+    def __init__(self, prs) -> None:
+        self.colors: dict[str, str] = {}
+        self.fills: list = []
+        master = prs.slide_master
+        for rel in master.part.rels.values():
+            if rel.reltype.endswith("/theme"):
+                from lxml import etree
+
+                root = etree.fromstring(rel.target_part.blob)
+                scheme = root.find(f".//{{{_A}}}clrScheme")
+                for el in scheme if scheme is not None else []:
+                    child = el[0]
+                    val = child.get("val") if child.tag.endswith("srgbClr") else child.get("lastClr")
+                    if val:
+                        self.colors[el.tag.split("}")[1]] = val.upper()
+                lst = root.find(f".//{{{_A}}}bgFillStyleLst")
+                self.fills = list(lst) if lst is not None else []
+        cmap = master._element.find(qn("p:clrMap"))
+        self.map = dict(cmap.attrib) if cmap is not None else {"tx1": "dk1", "bg1": "lt1", "tx2": "dk2", "bg2": "lt2"}
+
+    def resolve(self, color_el, phclr: str | None = None) -> str | None:
+        """A color element (srgbClr, schemeClr, ...) to 'RRGGBB', or None if it can't be judged."""
+        tag = color_el.tag.split("}")[1]
+        if tag == "srgbClr":
+            base = color_el.get("val").upper()
+        elif tag == "schemeClr":
+            val = color_el.get("val")
+            if val == "phClr":
+                base = phclr
+            else:
+                base = self.colors.get(self.map.get(val, val))
+        else:
+            return None
+        if not base or len(base) != 6:
+            return None
+        for mod in color_el:
+            name, val = mod.tag.split("}")[1], mod.get("val")
+            if name == "alpha" and int(val) < 100000:
+                return None  # semi-transparent: what shows through is unknown
+            if name in ("lumMod", "lumOff"):
+                continue
+            if name in ("tint", "shade", "satMod", "hueMod", "satOff", "hueOff", "comp", "inv", "gray"):
+                return None
+        h, l, s = _hls(base)
+        mod = next((int(m.get("val")) for m in color_el if m.tag.endswith("}lumMod")), 100000)
+        off = next((int(m.get("val")) for m in color_el if m.tag.endswith("}lumOff")), 0)
+        if mod != 100000 or off:
+            return _from_hls(h, l * mod / 100000 + off / 100000, s)
+        return base
+
+    def solid(self, fill_parent, phclr=None) -> str | None:
+        sf = fill_parent.find(f"{{{_A}}}solidFill") if fill_parent is not None else None
+        return self.resolve(sf[0], phclr) if sf is not None and len(sf) else None