csl-pyutil 0.24.1__tar.gz

csl_pyutil-0.24.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanskrit Lexicon / Cologne Digital Sanskrit Dictionaries contributors
+
+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.

csl_pyutil-0.24.1/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: csl-pyutil
+Version: 0.24.1
+Summary: Generic (non-Sanskrit-specific) Python helpers shared across the CDSL / Sanskrit-Lexicon repos
+Author: Sanskrit Lexicon / CDSL
+License: MIT
+Project-URL: Homepage, https://github.com/sanskrit-lexicon/csl-pyutil
+Keywords: cdsl,lexicography,review-sheet,tooling
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file

csl_pyutil-0.24.1/README.md

@@ -0,0 +1,255 @@
+# csl-pyutil
+
+_Created: 14-07-2026 · Last updated: 05-09-2026_
+
+Generic (non-Sanskrit-specific) Python helpers shared across the CDSL /
+Sanskrit-Lexicon repos. Distinct from
+[`sanskrit-util`](https://github.com/sanskrit-lexicon/sanskrit-util), which is
+scoped narrowly to Sanskrit string/transcoding helpers (IAST/SLP1/Devanāgarī)
+— this package is for everything else that shouldn't be re-typed per repo but
+also isn't Sanskrit-linguistics-specific.
+
+## Why this exists
+
+A [cross-repo dev-status + reuse review](https://github.com/gasyoun/Uprava/blob/main/CROSS_REPO_DEV_STATUS_AND_REUSE_REVIEW_07.2026.md)
+found **six independently hand-rolled ~150–250-line HTML review-sheet shells**
+across four repos — all implementing the same approve/reject/defer pattern
+(running tally, `localStorage` persistence, a/r/d keyboard shortcuts, free-text
+notes, `Download decisions.json` with an identical
+`{sheet_id, generated, decided, items}` schema) — with **no shared import
+between any of them**. Root cause: the org's `/review-sheet` Claude Code skill
+is prose-only, so every invocation re-derived the same markup/JS from
+scratch. Proven drift: none of the six shells implemented the skill-mandated
+`showSaveFilePicker` auto-save + legend footer (H779, 12-07-2026) — manual
+propagation had already failed once.
+
+## `render_review_sheet()`
+
+```sh
+pip install "csl-pyutil @ git+https://github.com/sanskrit-lexicon/csl-pyutil@main"
+```
+
+```python
+from csl_pyutil import render_review_sheet
+
+html = render_review_sheet(
+    items=[
+        {"id": "L142", "filt": "typeA", "title": "headword or item label",
+         "badges": ["tag1", "tag2"],
+         "question": "the judgment question shown on the card (HTML allowed)",
+         "panels": [("Panel heading", "<pre>panel body, HTML allowed</pre>")],
+         "note_placeholder": "optional custom placeholder text"},
+        ...
+    ],
+    config={
+        "sheet_id": "commentarystrategies-sundarakanda_35-37",  # org naming convention
+        "title": "Sundarakāṇḍa commentary xref — sarga 35-37",
+        "subtitle": "43 candidate cross-references needing a decision",
+        "footer": "Approve = accept the xref. Reject = discard. Defer = unsure.",
+        "approve_label": "Approve", "reject_label": "Reject",
+        "filters": [("typeA", "Type A"), ("typeB", "Type B")],
+        "generated": "2026-07-14",  # caller-supplied, never computed here — deterministic output
+        # Optional: make final exports publication-review admissible.
+        "strict_review": {
+            "reviewer": "gasyoun",
+            "require_all_votes": True,
+            "require_reject_note": True,
+        },
+    },
+    # Required when extras=True (default) since v0.8.0 / H1649:
+    screening={
+        "deterministic": 0,
+        "lookup": 0,
+        "agent": 0,
+        "human": 43,
+        "evidence_path": "review/screening_evidence.md",
+        "rules": ["none"],  # or the real rule names applied
+    },
+)
+open("review/commentarystrategies-sundarakanda_35-37_review.html", "w",
+     encoding="utf-8").write(html)
+```
+
+Ported byte-for-byte (proven by a fixture test, `tests/test_fixture_byte_identical.py`)
+from
+[`SanskritLexicography/RussianTranslation/src/build_h180_review_sheets.py`](https://github.com/gasyoun/SanskritLexicography/blob/master/RussianTranslation/src/build_h180_review_sheets.py)
+— the richest of the six hand-rolled shells (H925). `extras=True` (the
+default) additionally folds in what H779 mandated but no shell implemented: a
+File System Access API "Save to folder" auto-save control and a button-legend
+footer. Pass `extras=False` only to reproduce a pre-H779 shell's literal
+historical output.
+
+Exported decisions-JSON shape (unchanged from every shell's prior contract, so
+[`Uprava/tools/review_decisions_watcher.py`](https://github.com/gasyoun/Uprava/blob/main/tools/review_decisions_watcher.py)
+needs no changes):
+
+```json
+{"sheet_id": "...", "generated": "2026-07-14T12:00:00.000Z", "decided": 12,
+ "items": [{"id": "L142", "decision": "approve", "note": ""}, ...]}
+```
+
+With `strict_review`, the same payload gains additive top-level fields:
+
+```json
+{"sheet_id": "...", "generated": "2026-07-14", "decided": 12,
+ "reviewer": "gasyoun", "reviewedAt": "2026-07-17T20:45:00.000Z",
+ "complete": true,
+ "items": [{"id": "L142", "decision": "approve", "note": ""}, ...]}
+```
+
+Partial File System Access API auto-saves use `complete: false` and
+`reviewedAt: null`. Final download is blocked until the reviewer is non-empty,
+every item is voted, and every rejected item has a note. Callers that omit
+`strict_review` retain the 0.1.x behavior and byte-identical core rendering.
+
+See [`csl_pyutil/review_sheet.py`](https://github.com/sanskrit-lexicon/csl-pyutil/blob/main/csl_pyutil/review_sheet.py) for the full
+item/config schema docstring.
+
+### Presentation (0.5.0)
+
+`config["font_scale"]` multiplies the whole type scale and **defaults to 1.5** —
+MG's "+150%", ruled 28-07-2026 while voting the G5 sheet, together with a fix to
+the inherited hierarchy: the panel `<pre>` holding the text under judgement used
+to be the smallest type on the page. An A−/A+ toolbar control re-points the scale
+per browser. `font_scale=1` restores the donor sizes; `extras=False` never gets
+the layer, so the byte-identical fixture stands.
+
+`config["extra_css"]` appends caller CSS last in the cascade.
+
+### The evidence gate — V9 / V10 (0.9.0)
+
+V1–V8 are entirely about *presentation*. A sheet can be green on every one of them
+and still ask a human to re-derive, by eye, a conclusion the repo already holds on
+disk — measured 29-07-2026 on the sheet that prompted this: **191 of 200 cards**
+already carried a machine verdict, a named rule and cited evidence computed from
+the same inputs, none of it rendered, and **69 of 200** were not disagreements at
+all. So the emitter now refuses to write those sheets.
+
+```python
+from csl_pyutil import EvidenceManifest, render_review_sheet
+
+man = EvidenceManifest(sheet_id=SHEET_ID, row_ids=[i["id"] for i in items],
+                       repo_root=REPO)
+man.declare_joined("research/adjudication.tsv", ["verdict", "rule", "reason"])
+man.declare_omitted_path("research/superseded_run.tsv",
+                         because="superseded by the H1681 rerun, kept for audit")
+man.declare_omitted("DCS attested sentence",
+                    because="no per-compound sentence map exists; only sense-level")
+for it in items:
+    man.add_card(it["id"], evidence_fields=["verdict", "rule"])
+
+html = render_review_sheet(items, config, screening=..., manifest=man)  # raises, or returns
+```
+
+**V9 — evidence reuse.** With `manifest=`, [`preflight()`](https://github.com/sanskrit-lexicon/csl-pyutil/blob/main/csl_pyutil/evidence.py)
+runs against the *finished* document (after `ui_strings`, so it sees exactly what the
+reviewer sees) and raises `PreflightError` before a byte is returned: undeclared
+prior art keyed on the same row ids, cards under the evidence floor with no stated
+reason, Cyrillic/IAST mixed inside one word, SLP1 leaking into human-facing text,
+and structurally impossible sūtra citations. Tune it with `config["preflight"]`
+(`allow_slp1_tokens`, `overlap_threshold`, `skip_prior_art`). Without `manifest=`
+you get a `PreflightWarning` naming the reason — a migration ramp for the pre-0.9.0
+generators that **becomes an error in 1.0.0**; escalate it today with
+`-W error::csl_pyutil.evidence.PreflightWarning`.
+
+**V10 — no non-decisions.** `config["non_decision_share"]` is the largest fraction
+of cards the sheet may carry that your own pre-filter already resolved, marked per
+card as `item["machine_resolvable"] = True`. The caller classifies (only it knows its
+domain); the emitter enforces. It **defaults to 0.0** — a card the machine has
+answered does not belong on a human's plate — and a sheet with no flagged item is
+unaffected.
+
+Two asymmetries in the gate are deliberate and load-bearing: a conceptual
+`declare_omitted()` can never silence a real file the scan found (only
+`declare_omitted_path()` can), and the SLP1 detector stays **silent** on the
+undecidable all-lowercase case (`agni + deva` is byte-identical in SLP1 and IAST)
+rather than guessing.
+
+## `anatomy` — colour-coded CDSL raw markup
+
+```python
+from csl_pyutil import anatomy
+
+panel_body = anatomy.highlight(raw_record, target="As")     # tinted, markup still visible
+legend     = anatomy.legend_html(parts=["sanskrit", "gloss", "citation"])
+```
+
+A raw CDSL record dumped verbatim into a review card is a wall of punctuation.
+`highlight()` keeps every tag **visible** — the tags are the anatomy — but dims the
+delimiters and colours each payload by part class (Sanskrit form · gloss · citation ·
+grammar · abbreviation · cross-reference · etymology · homonym), outlining any form
+equal to `target`. Written for csl-atlas's xref sheet (H1646), moved here under H1808
+when a second generator needed it; csl-atlas's `scripts/lib/cdsl_anatomy.py` is now a
+re-export shim so there is one canonical copy.
+
+Hooks for what a shared module cannot know:
+
+| Argument | Use |
+|---|---|
+| `tag_parts={"ab": "crossref"}` | override the tag → part map (PWG wraps *every* abbreviation in `<ab>`; an xref sheet wants the brighter class) |
+| `plain_hook(text)` | reach text the markup does not delimit — NWS-layer cards carry citations as bare text with no `<ls>` around them |
+| `payload_hook(part, inner, attrs)` | render a tagged payload yourself, e.g. `<ls>` as a Cologne source link |
+
+The sheet's naming, placement (gitignored `review/`), GTD `@DO` line, and
+`Uprava/REVIEW_SHEETS_INDEX.md` registration are still the caller's job — this
+function only produces the HTML string. See
+[`~/.claude/commands/review-sheet.md`](https://github.com/gasyoun/claude-config/blob/main/commands/review-sheet.md)
+for the full process.
+
+## `integrity_tripwire` — a committed checksum on human-reviewed data
+
+```sh
+python -m csl_pyutil.integrity_tripwire --check   --pin data/integrity/<store>.pin.json
+python -m csl_pyutil.integrity_tripwire --extract --pin data/integrity/<store>.pin.json \
+       --write-pin --reason "what changed and why"
+```
+
+Three repos have each lost human review work to an automated writer that left a
+file that still parsed: csl-atlas's `--reseed` drops every preserved ruling,
+eleven WhitneyRoots `apply_*` scripts open `src/app_data.json` with `'w'` and no
+lock, and pwg_ru's own review-applying script is unlocked and un-gated. Nobody
+noticed for months, because nothing was watching. This module is what watches.
+
+It hashes a **projection** — only the key fields and the reviewed fields of the
+rows a store's predicate calls reviewed — so a reformat, a reorder, or an edit
+to unreviewed content is invisible, and a dropped `reviewer` stamp is not. A
+whole-file SHA-256 was tried first and cried wolf (a 1.29 MB serializer shrink
+at an identical row count), which is how it came to be ignored. Two digests:
+`overlay_sha256` for *did the reviewed content change*, `keyset_sha256` for
+*did the reviewed row set change* — an in-place overwrite moves only the first,
+a deleted row only the second.
+
+The rule for "a row is reviewed" is **data, not code**: it lives in the `spec`
+block of each pin, copied from the org census, because the three stores share no
+review stamp. pwg_ru has `reviewer`/`review_status`/`editorial_decision*`;
+csl-atlas needs `reviewStatus` **and** a human `reviewer` (137 of its 147
+status-reviewed rows are agent-attributed, so status alone over-claims human
+review 14.7×); WhitneyRoots has no per-row stamp at all and is reviewed
+file-level.
+
+CI runs `--check` and **fails** on a mismatch. A legitimate change regenerates
+the pin in the same commit with a one-line `reason` — that is the whole
+acknowledgement ritual. Exit codes: `0` match, `1` tripwire, `2` broken spec
+(a defect must not be able to look like a clean store).
+
+Gitignored stores (pwg_ru's live 26 MB JSONL) commit a derived `--extract`
+projection instead, so CI can check what it cannot see. The live bytes never
+enter git: `redact_fields` names reviewed fields whose value is replaced by
+`sha256:<hex>` of itself, so a field like pwg_ru's `human_review` — the
+curator's verbatim free-text notes, watched precisely because a wipe of it is
+the failure mode — stays fully covered by the digest while publishing nothing
+into a public repo. The hash moves the instant a single character does.
+
+## Tests
+
+```sh
+pip install -e . pytest
+pytest tests -q
+```
+
+`tests/fixtures/` holds 100%-synthetic placeholder content generated only
+through the donor's own render functions — never real translation data (the
+donor's own gitignored/unpublished pwg_ru store must never land in this
+public repo).
+
+_Dr. Mārcis Gasūns_

csl_pyutil-0.24.1/csl_pyutil/__init__.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+"""csl_pyutil — generic (non-Sanskrit-specific) Python helpers shared across
+the CDSL / Sanskrit-Lexicon repos.
+
+Public API
+----------
+render_review_sheet(items, config, extras=True)   self-contained HTML review/
+                                                    voting sheet (H925)
+render_review_sheet_packset(items, config, ...)   the same sheet split into
+                                                    packs of 10 sharing one
+                                                    sheet_id, plus an index
+                                                    page (V16, H2991)
+anatomy.highlight(raw, target=None, ...)          colour-coded CDSL raw-markup
+anatomy.legend_html(parts=None, ...)                anatomy for a panel (H1808)
+evidence.EvidenceManifest / evidence.preflight    the V9 evidence-reuse gate a
+                                                    sheet must pass before it is
+                                                    written (H1889)
+RU_UI_STRINGS                                     one-line Russian chrome
+                                                    preset for config["ui_strings"]
+                                                    (H2854)
+integrity_tripwire.check / .extract               committed checksum + key-set
+                                                    on human-reviewed overlay
+                                                    data, red in CI when a
+                                                    seeder wipes it (H2891)
+"""
+from csl_pyutil import anatomy, evidence
+from csl_pyutil.evidence import EvidenceManifest, PreflightError, PreflightWarning, preflight
+from csl_pyutil.review_sheet import (render_review_sheet, render_review_sheet_packset,
+                                     esc, mark_cyrillic, RU_UI_STRINGS)
+
+# integrity_tripwire is imported LAZILY (PEP 562), not eagerly like its
+# neighbours. Its documented CI invocation is `python -m
+# csl_pyutil.integrity_tripwire --check`, and runpy warns "found in sys.modules
+# after import of package" whenever the package has already pulled the module
+# in — which it would, on every single tripwire run in every consumer repo. A
+# gate whose job is to be believed when it prints RED must not also print a
+# spurious RuntimeWarning every time it prints GREEN.
+_LAZY = {
+    "integrity_tripwire": None,
+    "TripwireError": "integrity_tripwire",
+    "project": "integrity_tripwire",
+    "overlay_digest": "integrity_tripwire",
+    "keyset_digest": "integrity_tripwire",
+    "is_reviewed": "integrity_tripwire",
+    "extract": "integrity_tripwire",
+    "check": "integrity_tripwire",
+    "redact": "integrity_tripwire",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY:
+        import importlib
+
+        module = importlib.import_module("csl_pyutil.integrity_tripwire")
+        return module if _LAZY[name] is None else getattr(module, name)
+    raise AttributeError("module %r has no attribute %r" % (__name__, name))
+
+
+def __dir__():
+    return sorted(list(globals()) + list(_LAZY))
+
+__version__ = "0.24.1"
+__all__ = ["render_review_sheet", "render_review_sheet_packset", "esc", "mark_cyrillic",
+           "RU_UI_STRINGS", "anatomy", "evidence",
+           "EvidenceManifest", "PreflightError", "PreflightWarning", "preflight",
+           "integrity_tripwire", "TripwireError", "project", "overlay_digest",
+           "keyset_digest", "is_reviewed", "extract", "check"]

csl_pyutil-0.24.1/csl_pyutil/anatomy.py

@@ -0,0 +1,237 @@
+# -*- coding: utf-8 -*-
+"""anatomy — colour-code the anatomy of a raw CDSL dictionary record.
+
+A CDSL record body is a dense mix of SGML-ish tags (``<s>``, ``<lex>``, ``<ls>``,
+``<ab>``) and brace markers (``{#…#}``, ``{%…%}``) whose classes differ per
+dictionary. Dumped verbatim into a review card it is a wall of punctuation, and a
+reviewer cannot see which clause the judgement rests on (H1646: "add dictionary
+entry anatomy markup, the bright colors for different part of entry").
+
+This module keeps the markup fully VISIBLE — the tags are the anatomy, not noise
+to be stripped — but dims the delimiters and colours the payload by part class, so
+the shape of the entry reads at a glance.
+
+Provenance: written for csl-atlas's xref sheet (H1646) as
+``scripts/lib/cdsl_anatomy.py``, lifted here unchanged in behaviour under H1808
+when a SECOND sheet generator (SanskritLexicography's G5 print-readiness lane)
+turned out to need the same thing and had no way to reach it — MG, voting that
+sheet: "why entry anatomy is missing again? It must be a hook". One canonical
+copy in the shared emitter's package is that fix; csl-atlas's file is now a
+re-export shim.
+
+Prior art it deliberately reuses rather than re-derives:
+
+* Part taxonomy and colour semantics — the ``/entry-anatomy`` skill
+  (``entry_anatomy.py``'s ``PARTS`` / ``DICT_MAPS``), which segments a CDSL entry
+  into headword · grammar · etymology · sense · citation · cross-reference.
+* The raw-markup highlighting approach and dark palette —
+  ``SanskritLexicography/EntryAnatomy/build_entry_anatomy.py`` ``raw_highlight()``
+  + ``GENERIC_EXTRA_CSS``, whose colours already sit on a dark panel.
+
+Colours are INLINE ``style=`` attributes, not a stylesheet: the output has to drop
+into any panel body of any sheet, including callers that pass no ``extra_css``.
+The container carries ``class="anatomy"`` so the emitter's type scale can still
+reach it (the ``!important`` scale layer outranks the inline ``font`` shorthand).
+"""
+import html
+import re
+
+#: Part class -> (colour, human label, extra CSS). Dark-panel palette, matching the
+#: review sheet's own --panel2 (#1e222b). Labels drive the rendered legend.
+#: Labels are Russian: the surfaces rendering this legend are review sheets, whose
+#: reviewer reads Russian (H1648). Keys stay English machine identifiers.
+PARTS = {
+    "sanskrit": ("#e6c07b", "санскритская форма", ""),
+    "gloss": ("#98c379", "перевод / значение", "font-style:italic"),
+    "citation": ("#e06c75", "ссылка на источник", ""),
+    "grammar": ("#d19a66", "грамматическая помета", ""),
+    "abbreviation": ("#c9a227", "сокращение (<ab>)", ""),
+    "crossref": ("#56b6c2", "маркер перекрёстной ссылки (cf. / Vgl.)", "font-weight:600"),
+    "etymology": ("#61afef", "этимология / когнат", ""),
+    "language": ("#7aa2c9", "название языка", ""),
+    "taxon": ("#c678dd", "ботаническое / зоологическое название", ""),
+    "homonym": ("#b57edc", "номер омонима", ""),
+    "structure": ("#7f8c9b", "разделитель значения / раздела", ""),
+}
+
+#: Paired content tags -> part class. ``<s>``/``<s1>``/``<s2>`` are MW's Sanskrit
+#: spans; ``<is>`` is PWG's.
+#:
+#: ``<ab>`` defaults to ``abbreviation`` — in PWG it wraps EVERY abbreviation
+#: (``caus.``, ``gerund.``, ``v. a.``), of which cf./Vgl. is one case. csl-atlas's
+#: xref sheet judges cross-references specifically and wants the brighter
+#: ``crossref`` treatment, so it passes ``tag_parts={"ab": "crossref"}``.
+TAG_PARTS = {
+    "s": "sanskrit", "s1": "sanskrit", "s2": "sanskrit", "is": "sanskrit",
+    "ns": "gloss",
+    "ls": "citation",
+    "lex": "grammar",
+    "ab": "abbreviation",
+    "etym": "etymology",
+    "lang": "language",
+    "bot": "taxon", "zoo": "taxon",
+    "hom": "homonym",
+}
+
+#: Brace markers -> part class. ``{#…#}`` Sanskrit, ``{%…%}`` gloss (PWG/AP90),
+#: ``{@…@}`` a sense/section number.
+BRACE_PARTS = {"#": "sanskrit", "%": "gloss", "@": "structure"}
+
+_DELIM = "#5c6773"          # tag/brace delimiters — present but receded
+_ACCENT = "#ff7b72"         # Vedic accent marks inside a Sanskrit form
+_PIPE = "#e06c75"           # the ¦ head/body separator
+_PLAIN = "#d8dce2"          # untagged running text
+
+_SCANNER = re.compile(
+    r"(?P<pair><(?P<tag>s1|s2|s|is|ns|ls|lex|ab|etym|lang|bot|zoo|hom)\b(?P<attrs>[^>]*)>"
+    r"(?P<inner>.*?)</(?P=tag)>)"
+    r"|(?P<brace>\{(?P<bk>[#%@])(?P<binner>.*?)(?P=bk)\})"
+    r"|(?P<other><[^>]+>)"
+    r"|(?P<pipe>¦)",
+    re.DOTALL,
+)
+
+#: Vedic accent / length marks CDSL writes inside SLP1 forms. Stripped only when
+#: comparing a form against the highlight target.
+_ACCENT_CHARS = "/\\^~"
+
+
+def _strip_accents(text):
+    return "".join(ch for ch in text if ch not in _ACCENT_CHARS)
+
+
+def _span(text, colour, extra="", title=None, escape=True):
+    body = html.escape(text) if escape else text
+    style = "color:%s" % colour
+    if extra:
+        style += ";" + extra
+    attrs = ' title="%s"' % html.escape(title) if title else ""
+    return '<span style="%s"%s>%s</span>' % (style, attrs, body)
+
+
+def _sanskrit_body(inner, target_norm):
+    """Colour a Sanskrit payload, marking accents and the highlight target."""
+    colour, _label, extra = PARTS["sanskrit"]
+    pieces = []
+    for ch in inner:
+        if ch in _ACCENT_CHARS:
+            pieces.append(_span(ch, _ACCENT, "font-weight:700"))
+        else:
+            pieces.append(html.escape(ch))
+    body = "".join(pieces)
+    if target_norm and _strip_accents(inner).strip() == target_norm:
+        # This span IS the form the card is asking about.
+        return (
+            '<span style="background:rgba(86,182,194,.22);outline:1px solid #56b6c2;'
+            'border-radius:3px;padding:0 2px" title="цель перекрёстной ссылки, о которой спрашивает эта карточка">'
+            + _span(body, colour, extra, escape=False)
+            + "</span>"
+        )
+    return _span(body, colour, extra, escape=False)
+
+
+def highlight(raw, target=None, *, tag_parts=None, plain_hook=None, payload_hook=None):
+    """Return colour-coded HTML for one raw CDSL record body.
+
+    ``target`` is the SLP1 form under judgement; every Sanskrit span in the
+    record equal to it (ignoring accent marks) is outlined.
+
+    ``tag_parts`` overrides the tag -> part mapping for this call (merged over
+    ``TAG_PARTS``), e.g. ``{"ab": "crossref"}``.
+
+    ``plain_hook(text) -> html`` is called for every UNTAGGED run. A caller uses
+    it to reach content the markup does not delimit — bare citations, bracketed
+    diasystem tags — and is responsible for escaping what it returns. Return
+    ``None`` to fall through to the default plain rendering.
+
+    ``payload_hook(part, inner, attrs) -> html`` is called for each tagged
+    payload before it is coloured; a caller returns ready HTML (e.g. an ``<ls>``
+    citation rendered as a source link) or ``None`` to fall through.
+    """
+    text = str(raw or "")
+    target_norm = _strip_accents(str(target or "").strip()) or None
+    parts_map = dict(TAG_PARTS)
+    if tag_parts:
+        parts_map.update(tag_parts)
+
+    def plain(chunk):
+        if plain_hook is not None:
+            got = plain_hook(chunk)
+            if got is not None:
+                return got
+        return _span(chunk, _PLAIN)
+
+    out = []
+    pos = 0
+    for m in _SCANNER.finditer(text):
+        if m.start() > pos:
+            out.append(plain(text[pos:m.start()]))
+        if m.group("pair"):
+            tag, attrs, inner = m.group("tag"), m.group("attrs") or "", m.group("inner")
+            part = parts_map.get(tag, "structure")
+            colour, label, extra = PARTS[part]
+            out.append(_span("<%s%s>" % (tag, attrs), _DELIM, title=label))
+            hooked = payload_hook(part, inner, attrs) if payload_hook is not None else None
+            if hooked is not None:
+                out.append(hooked)
+            elif part == "sanskrit":
+                out.append(_sanskrit_body(inner, target_norm))
+            else:
+                out.append(_span(inner, colour, extra, title=label))
+            out.append(_span("</%s>" % tag, _DELIM, title=label))
+        elif m.group("brace"):
+            bk, inner = m.group("bk"), m.group("binner")
+            part = BRACE_PARTS.get(bk, "structure")
+            colour, label, extra = PARTS[part]
+            out.append(_span("{" + bk, _DELIM, title=label))
+            if part == "sanskrit":
+                out.append(_sanskrit_body(inner, target_norm))
+            else:
+                out.append(_span(inner, colour, extra, title=label))
+            out.append(_span(bk + "}", _DELIM, title=label))
+        elif m.group("other"):
+            # <div n="v">, <info lex="m"/> and friends: structural, kept visible but quiet.
+            out.append(_span(m.group("other"), _DELIM, title="structural markup"))
+        else:
+            out.append(_span("¦", _PIPE, "font-weight:700", title="headword / body separator"))
+        pos = m.end()
+    if pos < len(text):
+        out.append(plain(text[pos:]))
+    return (
+        '<div class="anatomy" style="background:#20242a;border-radius:6px;padding:12px 14px;'
+        'font:12.5px/1.9 Consolas,\'Cascadia Mono\',monospace;white-space:pre-wrap;'
+        'word-break:break-word">' + "".join(out) + "</div>"
+    )
+
+
+def legend_html(parts=None, extra_chips=()):
+    """A compact swatch legend for the part classes, for one place on the sheet.
+
+    ``parts`` restricts (and orders) the classes shown — pass only the ones the
+    sheet's dictionary actually uses. ``extra_chips`` appends caller chips as
+    ``(colour, label)`` pairs, for conventions this module does not own.
+    """
+    keys = list(parts or PARTS)
+    chips = []
+    for key in keys:
+        colour, label, extra = PARTS[key]
+        chips.append(
+            '<span style="display:inline-block;margin:0 10px 4px 0;white-space:nowrap">'
+            '<span style="display:inline-block;width:10px;height:10px;border-radius:2px;'
+            'background:%s;margin-right:5px;vertical-align:baseline"></span>'
+            '<span style="color:%s;%s">%s</span></span>' % (colour, colour, extra, html.escape(label))
+        )
+    chips.append(
+        '<span style="display:inline-block;margin:0 10px 4px 0;white-space:nowrap">'
+        '<span style="display:inline-block;width:10px;height:10px;border-radius:2px;'
+        'background:rgba(86,182,194,.22);outline:1px solid #56b6c2;margin-right:5px"></span>'
+        '<span style="color:#56b6c2">цель перекрёстной ссылки</span></span>'
+    )
+    for colour, label in extra_chips:
+        chips.append(
+            '<span style="display:inline-block;margin:0 10px 4px 0;white-space:nowrap">'
+            '<span style="display:inline-block;width:10px;height:10px;border-radius:2px;'
+            'background:%s;margin-right:5px;vertical-align:baseline"></span>'
+            '<span style="color:%s">%s</span></span>' % (colour, colour, html.escape(label))
+        )
+    return '<div style="font-size:12px;line-height:1.9">' + "".join(chips) + "</div>"