'
+ )
+ else:
+ img_html = 'Image not found
'
+
+ return (
+ f'\n'
+ f'
\n'
+ )
+
+
+def _build_sidebar(letter_set: dict[str, Any]) -> str:
+ parts: list[str] = []
+ for char, variants in letter_set.get("letters", {}).items():
+ name = _LETTER_NAMES.get(char, char)
+ anchor = _letter_anchor(char)
+ count = len(variants)
+ dots = "".join('' for _ in variants)
+ parts.append(
+ f''
+ f'{_esc(char)}'
+ f'{_esc(name)}'
+ f'{count}'
+ f'{dots}'
+ f''
+ )
+ return "\n".join(parts)
+
+
+def _build_sections(
+ letter_set: dict[str, Any], base_dir: Path
+) -> tuple[str, list[str], dict[str, Path]]:
+ """Return (sections_html, all_variant_ids, images_map).
+
+ *images_map* maps variant_id → absolute asset path for every variant whose
+ file exists on disk; used by the HTTP handler to serve ``/image/\n'
+ f' {vid_attr}\n'
+ f' {_esc(letter_char)} {letter_name}\n'
+ f' {q_label} ({ink_ratio:.2f})\n'
+ f' \n'
+ f'
\n'
+ f' \n'
+ f'
\n'
+ f'{img_html}'
+ f'
\n'
+ f' \n'
+ f' {w}\xd7{h} px
\n'
+ f'
\n'
+ f' \n'
+ f' \n'
+ f' \n'
+ f' \n'
+ f'
\n'
+ f' \n'
+ f' \n'
+ f' \n'
+ f' \n'
+ f'
\n'
+ f' ' + f'{_esc(char)}' + f'{_esc(name)}' + f'{n} {s_label}' + f'
\n{cards}{_esc(writer_label)}
\n' if writer_label else ""
+ )
+ title_esc = _esc(writer_id)
+
+ html_str = (
+ "\n"
+ '\n\n'
+ '\n'
+ '\n'
+ f"\n"
+ f'
\n"
+ ' \U0001f50c Review — {title_esc}
\n' + f" {label_line}" + f'Generated: {date_str}'
+ f" · {total} variant{'s' if total != 1 else ''}
\n"
+ " \n'
+ '
\n"
+ ' '
+ f'0 / {total} reviewed
\n'
+ ' \n'
+ " \n'
+ ' \n"
+ ' \n"
+ "
\n"
+ "\n'
+ ' \n"
+ ' \n'
+ f" {sections_html}\n"
+ " \n"
+ "
\n"
+ '\n'
+ f"\n"
+ "\n\n"
+ )
+ return html_str, images
+
+
+# ---------------------------------------------------------------------------
+# HTTP server
+# ---------------------------------------------------------------------------
+
+
+class _ReviewHandler(http.server.BaseHTTPRequestHandler):
+ """Minimal handler: serves pre-built HTML, images, and manages feedback JSON.
+
+ Concrete values for ``_html``, ``_feedback_path``, and ``_images`` must be
+ provided by a subclass (``serve()`` creates one per invocation to avoid
+ shared class-level state).
+ """
+
+ _html: str
+ _feedback_path: Path
+ _images: dict[str, Path]
+
+ def log_message(self, fmt: str, *args: object) -> None: # silence request log
+ pass
+
+ def do_GET(self) -> None:
+ if self.path == "/":
+ body = self._html.encode("utf-8")
+ self.send_response(200)
+ self.send_header("Content-Type", "text/html; charset=utf-8")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ elif self.path == "/feedback":
+ data: dict[str, Any] = {}
+ fp = self._feedback_path
+ if fp.exists():
+ try:
+ data = json.loads(fp.read_text(encoding="utf-8"))
+ except json.JSONDecodeError:
+ pass
+ body = json.dumps(data, ensure_ascii=False, indent=2).encode("utf-8")
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ elif self.path.startswith("/image/"):
+ # Strip query string / fragment; dict lookup prevents path traversal.
+ vid = self.path[len("/image/"):].split("?")[0].split("#")[0]
+ img_path = self._images.get(vid)
+ if img_path is None or not img_path.exists():
+ self.send_response(404)
+ self.end_headers()
+ return
+ ext = img_path.suffix.lower().lstrip(".")
+ mime = _MIME_MAP.get(ext, "image/png")
+ body = img_path.read_bytes()
+ self.send_response(200)
+ self.send_header("Content-Type", mime)
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ else:
+ self.send_response(404)
+ self.end_headers()
+
+ def do_POST(self) -> None:
+ length = int(self.headers.get("Content-Length", 0))
+ if self.path == "/feedback":
+ raw = self.rfile.read(length)
+ try:
+ data = json.loads(raw.decode("utf-8"))
+ except json.JSONDecodeError:
+ self.send_response(400)
+ self.end_headers()
+ return
+ # Atomic write: write to a sibling .tmp file then replace().
+ # Prevents a corrupt feedback file if the process is killed mid-write.
+ tmp = self._feedback_path.with_suffix(".tmp")
+ tmp.write_text(
+ json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True),
+ encoding="utf-8",
+ )
+ tmp.replace(self._feedback_path)
+ self.send_response(204)
+ self.end_headers()
+ else:
+ if length > 0:
+ self.rfile.read(length) # drain body before responding to avoid TCP RST
+ self.send_response(404)
+ self.end_headers()
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def serve(
+ path: Path,
+ *,
+ port: int = 8765,
+ feedback_path: Path | None = None,
+) -> None:
+ """Build a review page from *path* and serve it on *localhost:port*.
+
+ Parameters
+ ----------
+ path:
+ Absolute or relative path to a ``letter_set.json`` file. PNG assets
+ are resolved relative to ``path.parent``.
+ port:
+ TCP port to listen on (default: 8765).
+ feedback_path:
+ Where to read/write feedback JSON. Defaults to
+ ``.review_feedback.json`` next to *path*.
+ """
+ path = Path(path).resolve()
+ base_dir = path.parent
+ if feedback_path is None:
+ feedback_path = base_dir / _FEEDBACK_FILENAME
+
+ try:
+ letter_set: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+ except FileNotFoundError as exc:
+ raise FileNotFoundError(f"letter_set file not found: {path}") from exc
+ except json.JSONDecodeError as exc:
+ raise ValueError(f"letter_set file is not valid JSON: {exc}") from exc
+
+ html_str, images = _build_html(letter_set, base_dir)
+
+ # Create a fresh handler subclass per invocation so each server has its own
+ # isolated state rather than mutating shared class attributes.
+ class _Handler(_ReviewHandler):
+ _html = html_str
+ _feedback_path = feedback_path # type: ignore[assignment]
+ _images = images
+
+ server = http.server.HTTPServer(("127.0.0.1", port), _Handler)
+ url = f"http://localhost:{port}/"
+ writer_id = letter_set.get("writer_id", path.name)
+ total = sum(len(v) for v in letter_set.get("letters", {}).values())
+
+ print(f"Review server: {url}")
+ print(f"Writer: {writer_id} ({total} variant(s))")
+ print(f"Feedback file: {feedback_path}")
+ print("Press Ctrl-C to stop.")
+ print()
+
+ # The socket is bound and listening after HTTPServer.__init__(), so the
+ # browser can connect immediately without a timing delay.
+ webbrowser.open(url)
+ try:
+ server.serve_forever()
+ except KeyboardInterrupt:
+ print("\nStopped.")
+
+
+__all__ = ["serve"]
diff --git a/src/hletterscriptgen/schemas/letter_set.schema.json b/src/hletterscriptgen/schemas/letter_set.schema.json
index 14d8950..31f0d14 100644
--- a/src/hletterscriptgen/schemas/letter_set.schema.json
+++ b/src/hletterscriptgen/schemas/letter_set.schema.json
@@ -37,7 +37,7 @@
"source_repo": {
"type": "string",
"minLength": 1,
- "description": "Upstream repository identifier, e.g. 'HeOCR/public-domain-hand-written-hebrew-scans'."
+ "description": "Upstream repository identifier, e.g. 'HeOCR/hash'."
},
"source_entry_ids": {
"type": "array",
@@ -81,7 +81,7 @@
"repo": {
"type": "string",
"minLength": 1,
- "description": "Upstream repository identifier in 'owner/name' form, e.g. 'HeOCR/public-domain-hand-written-hebrew-scans'."
+ "description": "Upstream repository identifier in 'owner/name' form, e.g. 'HeOCR/hash'."
},
"revision": {
"type": "string",
diff --git a/src/hletterscriptgen/upstream.py b/src/hletterscriptgen/upstream.py
index c50b406..85e2e38 100644
--- a/src/hletterscriptgen/upstream.py
+++ b/src/hletterscriptgen/upstream.py
@@ -1,7 +1,7 @@
-"""Upstream integration: read and filter ``public-domain-hand-written-hebrew-scans``.
+"""Upstream integration: read and filter ``HeOCR/hash`` (HASH).
This module is read-only: it consumes a local checkout of the upstream
-scan corpus (``HeOCR/public-domain-hand-written-hebrew-scans``) and
+scan corpus (``HeOCR/hash``) and
exposes the records the generator pipeline actually needs. The full
upstream contract is broader than what is modelled here; see
``schemas/entry.schema.json`` in the upstream repo.
@@ -166,7 +166,7 @@ class UpstreamPin:
"""The ``(repo, revision)`` pair written to ``letter_set.v1.upstream``.
``repo`` is the ``owner/name`` form of the upstream remote (e.g.
- ``"HeOCR/public-domain-hand-written-hebrew-scans"``). ``revision``
+ ``"HeOCR/hash"``). ``revision``
is the full SHA of the pinned ``HEAD`` commit.
"""
diff --git a/tests/fixtures/attribution/writer_profile.json b/tests/fixtures/attribution/writer_profile.json
index 3f9960d..c17cd46 100644
--- a/tests/fixtures/attribution/writer_profile.json
+++ b/tests/fixtures/attribution/writer_profile.json
@@ -1,5 +1,5 @@
{
- "upstream_path": "../public-domain-hand-written-hebrew-scans",
+ "upstream_path": "../hash",
"writers": [
{
"writer_id": "writer_bialik",
diff --git a/tests/test_attribution.py b/tests/test_attribution.py
index 4b18283..a30cc35 100644
--- a/tests/test_attribution.py
+++ b/tests/test_attribution.py
@@ -71,7 +71,7 @@ def test_roundtrip_parse_fixture() -> None:
profile = load_attribution(PROFILE_PATH)
assert isinstance(profile, WriterProfile)
- assert profile.upstream_path == Path("../public-domain-hand-written-hebrew-scans")
+ assert profile.upstream_path == Path("../hash")
writers_by_id = {w.writer_id: w for w in profile.writers}
assert set(writers_by_id) == {"writer_bialik", "writer_herzl"}
diff --git a/tests/test_generator.py b/tests/test_generator.py
index ba2b2da..9b060a6 100644
--- a/tests/test_generator.py
+++ b/tests/test_generator.py
@@ -64,7 +64,7 @@ def _make_upstream_checkout(tmp_path: Path) -> Path:
_git(repo, "config", "user.email", "test@example.com")
_git(repo, "config", "user.name", "Test")
_git(repo, "config", "commit.gpgsign", "false")
- _git(repo, "remote", "add", "origin", "https://github.com/HeOCR/public-domain-hand-written-hebrew-scans.git")
+ _git(repo, "remote", "add", "origin", "https://github.com/HeOCR/hash.git")
# entries.jsonl
index_dir = repo / "data" / "index"
@@ -156,7 +156,7 @@ def test_generate_letter_set_content(tmp_path: Path) -> None:
doc = json.loads(paths[0].read_text(encoding="utf-8"))
assert doc["schema_version"] == "letter_set.v1"
assert doc["writer_id"] == "writer_test_a"
- assert doc["upstream"]["repo"] == "HeOCR/public-domain-hand-written-hebrew-scans"
+ assert doc["upstream"]["repo"] == "HeOCR/hash"
assert doc["generator"]["name"] == "hletterscriptgen"
# Both annotated letters must appear
assert "א" in doc["letters"]
@@ -324,7 +324,7 @@ def _make_upstream_checkout_no_cv2(tmp_path: Path) -> Path:
_git(repo, "config", "user.email", "test@example.com")
_git(repo, "config", "user.name", "Test")
_git(repo, "config", "commit.gpgsign", "false")
- _git(repo, "remote", "add", "origin", "https://github.com/HeOCR/public-domain-hand-written-hebrew-scans.git")
+ _git(repo, "remote", "add", "origin", "https://github.com/HeOCR/hash.git")
index_dir = repo / "data" / "index"
index_dir.mkdir(parents=True)
diff --git a/tests/test_reviewer.py b/tests/test_reviewer.py
new file mode 100644
index 0000000..ebad573
--- /dev/null
+++ b/tests/test_reviewer.py
@@ -0,0 +1,599 @@
+"""Tests for hletterscriptgen.reviewer — review app HTML builder and HTTP server."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import struct
+import threading
+import zlib
+from http.server import HTTPServer
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from hletterscriptgen.reviewer import (
+ _build_html,
+ _build_sections,
+ _build_sidebar,
+ _build_variant_card,
+ _ink_quality,
+ _letter_anchor,
+ _ReviewHandler,
+ serve,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _minimal_png(width: int = 4, height: int = 4) -> bytes:
+ """Return a tiny valid grayscale PNG for testing."""
+ raw = b"".join(b"\x00" + bytes([128] * width) for _ in range(height))
+ compressed = zlib.compress(raw, 1)
+
+ def chunk(tag: bytes, data: bytes) -> bytes:
+ crc = zlib.crc32(tag + data) & 0xFFFF_FFFF
+ return struct.pack(">I", len(data)) + tag + data + struct.pack(">I", crc)
+
+ ihdr_data = struct.pack(">II", width, height) + bytes([8, 0, 0, 0, 0])
+ return (
+ b"\x89PNG\r\n\x1a\n"
+ + chunk(b"IHDR", ihdr_data)
+ + chunk(b"IDAT", compressed)
+ + chunk(b"IEND", b"")
+ )
+
+
+def _make_letter_set(
+ writer_id: str = "w1",
+ letters: dict[str, list[dict[str, Any]]] | None = None,
+) -> dict[str, Any]:
+ if letters is None:
+ letters = {
+ "א": [
+ {
+ "variant_id": "alef-0001",
+ "asset_path": "letters/alef/alef-0001.png",
+ "checksum_sha256": "a" * 64,
+ "image": {"width_px": 32, "height_px": 40, "format": "png"},
+ "quality": {"ink_ratio": 0.25},
+ "source": {
+ "scan_entry_id": "scan-001",
+ "license": "PDM-1.0",
+ "bbox_in_source": {"x": 10, "y": 20, "width": 32, "height": 40},
+ },
+ }
+ ]
+ }
+ return {
+ "schema_version": "letter_set.v1",
+ "writer_id": writer_id,
+ "writer_label": "Test Writer",
+ "generated_at": "2026-05-25T00:00:00Z",
+ "letters": letters,
+ }
+
+
+def _start_one_shot_server(
+ html: str,
+ feedback_path: Path,
+ images: dict[str, Path] | None = None,
+) -> tuple[int, HTTPServer]:
+ """Start an HTTPServer bound to a free port; return (port, server).
+
+ Creates a fresh _ReviewHandler subclass per call so tests are isolated —
+ no shared class-level state between invocations.
+ """
+ class _TestHandler(_ReviewHandler):
+ pass
+
+ _TestHandler._html = html
+ _TestHandler._feedback_path = feedback_path
+ _TestHandler._images = images if images is not None else {}
+
+ srv = HTTPServer(("127.0.0.1", 0), _TestHandler)
+ return srv.server_address[1], srv
+
+
+# ---------------------------------------------------------------------------
+# _letter_anchor
+# ---------------------------------------------------------------------------
+
+
+def test_letter_anchor_alef() -> None:
+ assert _letter_anchor("א") == "u05d0"
+
+
+def test_letter_anchor_resh() -> None:
+ assert _letter_anchor("ר") == "u05e8"
+
+
+def test_letter_anchor_tav() -> None:
+ assert _letter_anchor("ת") == "u05ea"
+
+
+# ---------------------------------------------------------------------------
+# _ink_quality
+# ---------------------------------------------------------------------------
+
+
+def test_ink_quality_very_sparse() -> None:
+ label, cls = _ink_quality(0.03)
+ assert label == "Very sparse"
+ assert cls == "quality-low"
+
+
+def test_ink_quality_sparse() -> None:
+ label, cls = _ink_quality(0.10)
+ assert label == "Sparse"
+ assert cls == "quality-warn"
+
+
+def test_ink_quality_normal() -> None:
+ label, cls = _ink_quality(0.30)
+ assert label == "Normal"
+ assert cls == "quality-ok"
+
+
+def test_ink_quality_normal_upper_boundary() -> None:
+ label, cls = _ink_quality(0.60)
+ assert label == "Normal"
+ assert cls == "quality-ok"
+
+
+def test_ink_quality_dense() -> None:
+ label, cls = _ink_quality(0.80)
+ assert label == "Dense"
+ assert cls == "quality-warn"
+
+
+# ---------------------------------------------------------------------------
+# _build_variant_card
+# ---------------------------------------------------------------------------
+
+
+def test_variant_card_contains_variant_id(tmp_path: Path) -> None:
+ variant: dict[str, Any] = {
+ "variant_id": "alef-0042",
+ "asset_path": "letters/alef/alef-0042.png",
+ "checksum_sha256": "a" * 64,
+ "image": {"width_px": 30, "height_px": 40, "format": "png"},
+ "quality": {"ink_ratio": 0.28},
+ "source": {
+ "scan_entry_id": "s001",
+ "license": "PDM-1.0",
+ "bbox_in_source": {"x": 5, "y": 10, "width": 30, "height": 40},
+ },
+ }
+ images: dict[str, Path] = {}
+ html = _build_variant_card(variant, "א", tmp_path, images)
+ assert "alef-0042" in html
+ assert 'id="card-alef-0042"' in html
+
+
+def test_variant_card_missing_image_shows_fallback(tmp_path: Path) -> None:
+ variant: dict[str, Any] = {
+ "variant_id": "alef-0001",
+ "asset_path": "letters/alef/missing.png",
+ "checksum_sha256": "a" * 64,
+ "image": {"width_px": 30, "height_px": 40, "format": "png"},
+ "quality": {"ink_ratio": 0.25},
+ "source": {
+ "scan_entry_id": "s001",
+ "license": "PDM-1.0",
+ "bbox_in_source": {"x": 5, "y": 10, "width": 30, "height": 40},
+ },
+ }
+ images: dict[str, Path] = {}
+ html = _build_variant_card(variant, "א", tmp_path, images)
+ assert "glyph-missing" in html
+ assert "