scriptconv 0.0.3a7__tar.gz → 0.0.3a9__tar.gz

{scriptconv-0.0.3a7 → scriptconv-0.0.3a9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptconv
-Version: 0.0.3a7
+Version: 0.0.3a9
 Summary: Zero-dependency script & phoneme-notation core — ISO-15924 detection & metadata, IPA↔ARPABET/X-SAMPA/Lexique/Kirshenbaum/Cotovía/RFE, Buckwalter↔Arabic, Hangul→jamo, kana
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/TigreGotico/scriptconv
@@ -199,6 +199,15 @@ Transcoding faithfulness depends on the target notation's inventory. IPA is the
 notation↔notation goes through IPA. The table below states, for each notation, whether a
 round-trip is exact and what happens to a symbol the table does not know.
 
+Every converter (and `convert()`) accepts a codecs-style `errors=` policy for
+symbols outside its table: `"pass"` keeps the symbol (the default everywhere
+except `ipa_to_arpa`), `"replace"` substitutes the notation's placeholder
+(`?`; the historical `ipa_to_arpa` default, tunable via `unknown=`),
+`"ignore"` drops it, and `"strict"` raises `UnknownSymbolError` naming the
+symbol, its position, and the notation. The "Unknown-token behaviour" column
+below describes the per-converter default.
+
+
 | Notation | `to_ipa` → `from_ipa` round-trip | `from_ipa` → `to_ipa` round-trip | Unknown-token behaviour |
 |----------|----------------------------------|----------------------------------|-------------------------|
 | **ARPABET** | Exact for base symbols; **stress digits are dropped** and `AH0`↔`AX` (schwa) is not distinguished | **Lossy** — ARPABET is an English-only inventory, so any IPA symbol outside it becomes the *unknown* placeholder | `arpa_to_ipa`: passed through unchanged. `ipa_to_arpa`: diacritics and suprasegmentals (combining marks, length/stress modifiers) are dropped; other out-of-inventory symbols are replaced with `?` by default (`unknown=` param; `unknown=""` drops) |

{scriptconv-0.0.3a7 → scriptconv-0.0.3a9}/README.md

@@ -166,6 +166,15 @@ Transcoding faithfulness depends on the target notation's inventory. IPA is the
 notation↔notation goes through IPA. The table below states, for each notation, whether a
 round-trip is exact and what happens to a symbol the table does not know.
 
+Every converter (and `convert()`) accepts a codecs-style `errors=` policy for
+symbols outside its table: `"pass"` keeps the symbol (the default everywhere
+except `ipa_to_arpa`), `"replace"` substitutes the notation's placeholder
+(`?`; the historical `ipa_to_arpa` default, tunable via `unknown=`),
+`"ignore"` drops it, and `"strict"` raises `UnknownSymbolError` naming the
+symbol, its position, and the notation. The "Unknown-token behaviour" column
+below describes the per-converter default.
+
+
 | Notation | `to_ipa` → `from_ipa` round-trip | `from_ipa` → `to_ipa` round-trip | Unknown-token behaviour |
 |----------|----------------------------------|----------------------------------|-------------------------|
 | **ARPABET** | Exact for base symbols; **stress digits are dropped** and `AH0`↔`AX` (schwa) is not distinguished | **Lossy** — ARPABET is an English-only inventory, so any IPA symbol outside it becomes the *unknown* placeholder | `arpa_to_ipa`: passed through unchanged. `ipa_to_arpa`: diacritics and suprasegmentals (combining marks, length/stress modifiers) are dropped; other out-of-inventory symbols are replaced with `?` by default (`unknown=` param; `unknown=""` drops) |

{scriptconv-0.0.3a7 → scriptconv-0.0.3a9}/scriptconv/__init__.py

@@ -22,6 +22,10 @@ readings:
     extra; Chinese hanzi → pinyin/bopomofo via the ``zh`` extra).
 cangjie:
     Hanzi → Cangjie5 input codes (shape decomposition, vendored table).
+graph:
+    Conversion-graph engine: representations (notations and orthographies)
+    as nodes, registered transforms as edges, lossless-preferring routing.
+    External packages extend graph instances explicitly.
 conventions:
     Orthographic conventions — script-scoped decorations orthogonal to
     identity (tashkeel, niqqud, wakachigaki, pinyin tone spelling…).
@@ -45,6 +49,7 @@ from scriptconv.scripts import (
 )
 from scriptconv.notation import (
     Notation,
+    UnknownSymbolError,
     NotationInfo,
     NOTATION_INFO,
     convert,
@@ -81,6 +86,7 @@ from scriptconv.readings import (
 )
 from scriptconv.conventions import (
     Convention,
+    Transition,
     CONVENTION_REGISTRY,
     conventions_for,
     restyle,
@@ -88,6 +94,13 @@ from scriptconv.conventions import (
     apply,
     detect as detect_convention,
 )
+from scriptconv.graph import (
+    Representation,
+    Edge,
+    ConversionGraph,
+    DEFAULT_GRAPH,
+    REPRESENTATIONS,
+)
 from scriptconv.cangjie import (
     cangjie_code,
     to_cangjie,
@@ -107,6 +120,7 @@ __all__ = [
     "normalize_script_tag",
     # notation
     "Notation",
+    "UnknownSymbolError",
     "NotationInfo",
     "NOTATION_INFO",
     "convert",
@@ -138,12 +152,19 @@ __all__ = [
     "to_katakana",
     # conventions (orthographic decorations, orthogonal to script identity)
     "Convention",
+    "Transition",
     "CONVENTION_REGISTRY",
     "conventions_for",
     "restyle",
     "strip",
     "apply",
     "detect_convention",
+    # graph (conversion routing engine over representations)
+    "Representation",
+    "Edge",
+    "ConversionGraph",
+    "DEFAULT_GRAPH",
+    "REPRESENTATIONS",
     # cangjie (vendored Cangjie5 table)
     "cangjie_code",
     "to_cangjie",

{scriptconv-0.0.3a7 → scriptconv-0.0.3a9}/scriptconv/__main__.py

@@ -11,6 +11,7 @@ Usage
     python -m scriptconv strip <convention> <text>
     python -m scriptconv restyle <convention> <style> <text>
     python -m scriptconv conventions [--script CODE]
+    python -m scriptconv route <src> <dst>
 
 Examples
 --------
@@ -64,6 +65,10 @@ def main(argv: list[str] | None = None) -> int:
     cv = sub.add_parser("conventions", help="List orthographic conventions")
     cv.add_argument("--script", default=None, help="Filter by ISO-15924 script code")
 
+    rt = sub.add_parser("route", help="Show the conversion path between representations")
+    rt.add_argument("src", help="Source representation id")
+    rt.add_argument("dst", help="Target representation id")
+
     args = p.parse_args(argv)
 
     if args.command is None:
@@ -80,6 +85,7 @@ def main(argv: list[str] | None = None) -> int:
         "strip": lambda: _do_strip(args),
         "restyle": lambda: _do_restyle(args),
         "conventions": lambda: _do_conventions(args),
+        "route": lambda: _do_route(args),
     }
     dispatch[args.command]()
     return 0
@@ -89,9 +95,31 @@ def _do_convert(args: argparse.Namespace) -> None:
     from scriptconv.notation import Notation, convert
     try:
         print(convert(args.text, args.src, args.dst))
+        return
+    except ValueError:
+        pass
+    # not a notation pair — try any representation pair on the default graph
+    from scriptconv.graph import DEFAULT_GRAPH
+    try:
+        print(DEFAULT_GRAPH.convert(args.text, args.src, args.dst))
     except ValueError as e:
         valid = ", ".join(n.value for n in Notation)
-        raise SystemExit(f"error: {e} (valid notations: {valid})")
+        raise SystemExit(f"error: {e} (valid notations: {valid}; "
+                         f"graph nodes: {', '.join(DEFAULT_GRAPH.nodes)})")
+
+
+def _do_route(args: argparse.Namespace) -> None:
+    from scriptconv.graph import DEFAULT_GRAPH
+    try:
+        path = DEFAULT_GRAPH.route(args.src, args.dst)
+    except ValueError as e:
+        raise SystemExit(f"error: {e}")
+    if not path:
+        print("(identity)")
+    for e in path:
+        flags = "lossless" if e.lossless else "lossy"
+        extra = f", needs scriptconv[{e.requires}]" if e.requires else ""
+        print(f"  {e.src} -> {e.dst}  ({flags}, cost {e.cost:g}{extra})")
 
 
 def _do_detect(args: argparse.Namespace) -> None:

{scriptconv-0.0.3a7 → scriptconv-0.0.3a9}/scriptconv/conventions.py

@@ -43,6 +43,7 @@ repertoires and the restyle is deterministic.
 """
 from __future__ import annotations
 
+import functools
 import re
 import unicodedata
 from dataclasses import dataclass
@@ -50,6 +51,7 @@ from typing import Callable, Dict, List, Optional, Tuple
 
 __all__ = [
     "Convention",
+    "Transition",
     "CONVENTION_REGISTRY",
     "conventions_for",
     "detect",
@@ -59,98 +61,118 @@ __all__ = [
 ]
 
 
+@dataclass(frozen=True)
+class Transition:
+    """One rewrite between two styles of a convention.
+
+    ``fn`` is a pure ``str -> str`` transform.  ``requires`` names the
+    optional extra the transform needs, if any (queryable before calling —
+    the transform itself raises :class:`ImportError` with an install hint
+    when the dependency is missing).
+    """
+    frm: str
+    to: str
+    fn: Callable[[str], str]
+    lossless: bool = False
+    requires: Optional[str] = None
+
+
 @dataclass(frozen=True)
 class Convention:
-    """Metadata for one orthographic convention (NotationInfo-style: data, not prose)."""
+    """One orthographic convention: metadata plus the behavior that owns it.
+
+    Transitions and the optional detector live on the convention itself, so
+    every operation is generic — nothing in this module branches on a
+    convention's identity.
+    """
     id: str
     name: str
     scripts: Tuple[str, ...]           # ISO-15924 codes whose text it decorates
     system: Optional[str]              # sub-script system qualifier ("pinyin", "japanese")
     styles: Tuple[str, ...]            # mutually exclusive states; includes "none" if strippable
     default_style: str
-    detectable: bool                   # current style is character-evident
-    strip_lossless: bool               # can the stripped information be recovered?
-    apply_requires: Optional[str]      # optional-extra name needed to leave "none", if any
     ranges: Tuple[Tuple[int, int], ...]  # decoration codepoints (empty for spacing/variant conventions)
     reference: str
+    transitions: Tuple[Transition, ...] = ()
+    detector: Optional[Callable[[str], Optional[str]]] = None
+
+    @property
+    def detectable(self) -> bool:
+        return self.detector is not None
+
+    @property
+    def strip_lossless(self) -> bool:
+        stripping = [t for t in self.transitions if t.to == "none"]
+        return bool(stripping) and all(t.lossless for t in stripping)
+
+    @property
+    def apply_requires(self) -> Optional[str]:
+        return next((t.requires for t in self.transitions if t.frm == "none"), None)
+
+    def transition(self, frm: str, to: str) -> Optional[Transition]:
+        return next((t for t in self.transitions
+                     if t.frm == frm and t.to == to), None)
+
+    def restyle(self, text: str, to: str, frm: Optional[str] = None) -> str:
+        """Rewrite *text* from one style of this convention to another."""
+        if to not in self.styles and to != "none":
+            raise ValueError(f"{self.id!r} has styles {self.styles}, not {to!r}")
+        if frm is None:
+            frm = self._infer_source(text, to)
+        if frm == to:
+            return text
+        t = self.transition(frm, to)
+        if t is None:
+            supported = sorted(f"{x.frm}->{x.to}" for x in self.transitions)
+            raise ValueError(f"{self.id!r} does not define {frm!r}->{to!r}; "
+                             f"supported: {', '.join(supported)}")
+        return t.fn(text)
+
+    def _infer_source(self, text: str, to: str) -> str:
+        if self.detector is not None:
+            detected = self.detector(text)
+            if detected is not None and (detected == to
+                                         or self.transition(detected, to)):
+                return detected
+        sources = sorted({t.frm for t in self.transitions if t.to == to})
+        if len(sources) == 1:
+            return sources[0]
+        if self.default_style != to:
+            return self.default_style
+        raise ValueError(f"{self.id!r}: source style for ->{to!r} is ambiguous "
+                         f"({', '.join(sources)}); pass frm=")
+
+    def strip(self, text: str) -> str:
+        """Remove this convention's decoration (restyle to ``"none"``)."""
+        stripping = [t for t in self.transitions if t.to == "none"]
+        if not stripping:
+            raise ValueError(f"{self.id!r} has no unmarked style; "
+                             f"styles: {self.styles}")
+        # when every stripping transition is the same transform (e.g. one
+        # strip handles both pinyin tone spellings), the source is irrelevant
+        if len({t.fn for t in stripping}) == 1:
+            return stripping[0].fn(text)
+        return self.restyle(text, "none")
+
+    def apply(self, text: str, style: Optional[str] = None) -> str:
+        """Add this convention's decoration to unmarked text."""
+        if style is None:
+            marked = [s for s in self.styles if s != "none"]
+            style = self.default_style if self.default_style != "none" else marked[0]
+        return self.restyle(text, style, frm="none")
+
+    def detect(self, text: str) -> Optional[str]:
+        """Current style of *text*, or None when not character-evident.
+
+        For binary decorations this means "any mark present" — a single
+        shadda in a paragraph reports ``"marked"``.
+        """
+        return self.detector(text) if self.detector is not None else None
 
 
 # ---------------------------------------------------------------------------
-# Registry
+# Shared helpers
 # ---------------------------------------------------------------------------
-# Tashkeel deliberately EXCLUDES U+0653–0655 (madda above, hamza above, hamza
-# below): in NFD text آ/أ/إ decompose to alef + those marks, which are letter
-# identity — stripping them would corrupt the consonantal skeleton.
-_TASHKEEL_RANGES = ((0x064B, 0x0652), (0x0656, 0x065F), (0x0670, 0x0670),
-                    (0x08F0, 0x08F2))
-_KASHIDA_RANGES = ((0x0640, 0x0640),)
-# 06DD/06DE (end of ayah, rub el hizb) are structural signs and 06E5/06E6 are
-# small letters — kept; 06E7-06E9 (small high marks, place of sajdah) and
-# 06EA-06ED are annotation marks — stripped.
-_QURANIC_RANGES = ((0x06D6, 0x06DC), (0x06DF, 0x06E4), (0x06E7, 0x06ED))
-# Niqqud includes dagesh/mapiq U+05BC, meteg U+05BD (a masoretic stress mark,
-# but traditionally stripped with the points), rafe U+05BF and the shin/sin
-# dots U+05C1/05C2 — stripping loses the שׁ/שׂ distinction, exactly as
-# unpointed Hebrew does.  Maqaf U+05BE, sof pasuq U+05C3 and nun hafukha
-# U+05C6 are punctuation and survive.
-_NIQQUD_RANGES = ((0x05B0, 0x05BD), (0x05BF, 0x05BF), (0x05C1, 0x05C2),
-                  (0x05C7, 0x05C7))
-_TEAMIM_RANGES = ((0x0591, 0x05AF), (0x05C0, 0x05C0), (0x05C4, 0x05C5))
-
-CONVENTION_REGISTRY: Dict[str, Convention] = {c.id: c for c in (
-    Convention("tashkeel", "Arabic vocalization (harakat/tanwin/shadda/sukun)",
-               ("Arab",), None, ("marked", "none"), "marked",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_TASHKEEL_RANGES,
-               reference="Unicode 15 ch. 9.2 (Arabic); excludes letter-identity U+0653-0655"),
-    Convention("kashida", "Arabic justification elongation (tatweel)",
-               ("Arab",), None, ("marked", "none"), "none",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_KASHIDA_RANGES, reference="Unicode U+0640 ARABIC TATWEEL"),
-    Convention("quranic-marks", "Quranic annotation signs",
-               ("Arab",), None, ("marked", "none"), "none",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_QURANIC_RANGES, reference="Unicode U+06D6-06ED Quranic annotation signs"),
-    Convention("niqqud", "Hebrew vocalization points",
-               ("Hebr",), None, ("marked", "none"), "marked",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_NIQQUD_RANGES,
-               reference="Unicode 15 ch. 9.1 (Hebrew); strip loses the shin/sin dot distinction"),
-    Convention("teamim", "Hebrew cantillation marks",
-               ("Hebr",), None, ("marked", "none"), "none",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_TEAMIM_RANGES, reference="Unicode U+0591-05AF Hebrew accents (masoretic)"),
-    Convention("wakachigaki", "Japanese spaced writing (分かち書き)",
-               ("Hira", "Kana", "Hani"), "japanese", ("marked", "none"), "none",
-               detectable=False, strip_lossless=False, apply_requires="ja",
-               ranges=(),
-               reference="Spaced orthographic mode of Japanese (children's books, games)"),
-    Convention("pinyin-tone", "Pinyin tone spelling",
-               ("Latn",), "pinyin", ("mark", "number", "none"), "mark",
-               detectable=False, strip_lossless=False, apply_requires=None,
-               ranges=(),
-               reference="GB/T 16159 Basic rules of Hanyu Pinyin orthography"),
-    Convention("jamo-form", "Hangul jamo repertoire (compatibility vs conjoining)",
-               ("Hang",), None, ("compatibility", "conjoining"), "compatibility",
-               detectable=True, strip_lossless=True, apply_requires=None,
-               ranges=(),
-               reference="Unicode Hangul Compatibility Jamo U+3130 vs Hangul Jamo U+1100"),
-)}
-
-
-def conventions_for(script: str) -> List[Convention]:
-    """Conventions that decorate *script* (ISO-15924 code), registry order."""
-    return [c for c in CONVENTION_REGISTRY.values() if script in c.scripts]
-
-
-def _conv(convention_id: str) -> Convention:
-    try:
-        return CONVENTION_REGISTRY[convention_id]
-    except KeyError:
-        raise ValueError(
-            f"unknown convention {convention_id!r}; known: "
-            f"{', '.join(sorted(CONVENTION_REGISTRY))}") from None
-
 
 def _in_ranges(cp: int, ranges: Tuple[Tuple[int, int], ...]) -> bool:
     return any(lo <= cp <= hi for lo, hi in ranges)
@@ -162,6 +184,12 @@ def _range_strip(ranges: Tuple[Tuple[int, int], ...]) -> Callable[[str], str]:
     return _strip
 
 
+def _range_detector(ranges: Tuple[Tuple[int, int], ...]) -> Callable[[str], Optional[str]]:
+    def _detect(text: str) -> Optional[str]:
+        return "marked" if any(_in_ranges(ord(c), ranges) for c in text) else "none"
+    return _detect
+
+
 # ---------------------------------------------------------------------------
 # Wakachigaki
 # ---------------------------------------------------------------------------
@@ -338,6 +366,7 @@ def _pinyin_strip(text: str) -> str:
 # U+3131), so a consonant is treated as an onset when a vowel follows,
 # otherwise as a coda — deterministic over well-formed jamo sequences.
 
+@functools.lru_cache(maxsize=1)
 def _jamo_tables():
     from scriptconv.translit import _ONSETS as _CO, _VOWELS as _CV, _CODAS as _CT
     conj_to_compat = {}
@@ -357,22 +386,13 @@ def _jamo_tables():
     return conj_to_compat, compat_onset, compat_vowel, compat_coda
 
 
-_JAMO_TABLES = None
-
-
 def _jamo_conjoining_to_compat(text: str) -> str:
-    global _JAMO_TABLES
-    if _JAMO_TABLES is None:
-        _JAMO_TABLES = _jamo_tables()
-    table = _JAMO_TABLES[0]
+    table = _jamo_tables()[0]
     return "".join(table.get(c, c) for c in text)
 
 
 def _jamo_compat_to_conjoining(text: str) -> str:
-    global _JAMO_TABLES
-    if _JAMO_TABLES is None:
-        _JAMO_TABLES = _jamo_tables()
-    _, onset, vowel, coda = _JAMO_TABLES
+    _, onset, vowel, coda = _jamo_tables()
     out = []
     for i, c in enumerate(text):
         if c in vowel:
@@ -401,95 +421,116 @@ def _jamo_detect(text: str) -> Optional[str]:
 
 
 # ---------------------------------------------------------------------------
-# Transition matrix and operations
+# Registry
 # ---------------------------------------------------------------------------
 
-_TRANSITIONS: Dict[Tuple[str, str, str], Callable[[str], str]] = {
-    ("tashkeel", "marked", "none"): _range_strip(_TASHKEEL_RANGES),
-    ("kashida", "marked", "none"): _range_strip(_KASHIDA_RANGES),
-    ("quranic-marks", "marked", "none"): _range_strip(_QURANIC_RANGES),
-    ("niqqud", "marked", "none"): _range_strip(_NIQQUD_RANGES),
-    ("teamim", "marked", "none"): _range_strip(_TEAMIM_RANGES),
-    ("wakachigaki", "marked", "none"): _wakachigaki_strip,
-    ("wakachigaki", "none", "marked"): _wakachigaki_apply,
-    ("pinyin-tone", "mark", "number"): _pinyin_mark_to_number,
-    ("pinyin-tone", "number", "mark"): _pinyin_number_to_mark,
-    ("pinyin-tone", "mark", "none"): _pinyin_strip,
-    ("pinyin-tone", "number", "none"): _pinyin_strip,
-    ("jamo-form", "conjoining", "compatibility"): _jamo_conjoining_to_compat,
-    ("jamo-form", "compatibility", "conjoining"): _jamo_compat_to_conjoining,
-}
+# Tashkeel deliberately EXCLUDES U+0653–0655 (madda above, hamza above, hamza
+# below): in NFD text آ/أ/إ decompose to alef + those marks, which are letter
+# identity — stripping them would corrupt the consonantal skeleton.
+_TASHKEEL_RANGES = ((0x064B, 0x0652), (0x0656, 0x065F), (0x0670, 0x0670),
+                    (0x08F0, 0x08F2))
+_KASHIDA_RANGES = ((0x0640, 0x0640),)
+# 06DD/06DE (end of ayah, rub el hizb) are structural signs and 06E5/06E6 are
+# small letters — kept; 06E7-06E9 (small high marks, place of sajdah) and
+# 06EA-06ED are annotation marks — stripped.
+_QURANIC_RANGES = ((0x06D6, 0x06DC), (0x06DF, 0x06E4), (0x06E7, 0x06ED))
+# Niqqud includes dagesh/mapiq U+05BC, meteg U+05BD (a masoretic stress mark,
+# but traditionally stripped with the points), rafe U+05BF and the shin/sin
+# dots U+05C1/05C2 — stripping loses the שׁ/שׂ distinction, exactly as
+# unpointed Hebrew does.  Maqaf U+05BE, sof pasuq U+05C3 and nun hafukha
+# U+05C6 are punctuation and survive.
+_NIQQUD_RANGES = ((0x05B0, 0x05BD), (0x05BF, 0x05BF), (0x05C1, 0x05C2),
+                  (0x05C7, 0x05C7))
+_TEAMIM_RANGES = ((0x0591, 0x05AF), (0x05C0, 0x05C0), (0x05C4, 0x05C5))
 
 
-def restyle(text: str, convention_id: str, to: str,
-            frm: Optional[str] = None) -> str:
-    """Rewrite *text* from one style of a convention to another.
+def _marks(id: str, name: str, scripts: Tuple[str, ...],
+           ranges: Tuple[Tuple[int, int], ...], reference: str,
+           *, default: str = "marked") -> Convention:
+    """A binary decoration: strippable marks with a range-based detector."""
+    return Convention(id, name, scripts, None, ("marked", "none"), default,
+                      ranges, reference,
+                      transitions=(Transition("marked", "none", _range_strip(ranges)),),
+                      detector=_range_detector(ranges))
 
-    ``frm`` defaults to the convention's marked/default style for strips and
-    is required where the source style is not inferable.  Unsupported
-    transitions raise :class:`ValueError`; transitions that need a missing
-    optional dependency raise :class:`ImportError` with an install hint.
-    """
-    conv = _conv(convention_id)
-    if to not in conv.styles and to != "none":
-        raise ValueError(f"{convention_id!r} has styles {conv.styles}, not {to!r}")
-    if frm is None:
-        if conv.id == "jamo-form":
-            frm = _jamo_detect(text) or conv.default_style
-        else:
-            sources = sorted({f for (c, f, t) in _TRANSITIONS
-                              if c == convention_id and t == to})
-            if len(sources) == 1:
-                frm = sources[0]
-            elif conv.default_style != to:
-                frm = conv.default_style
-            else:
-                raise ValueError(
-                    f"{convention_id!r}: source style for ->{to!r} is ambiguous "
-                    f"({', '.join(sources)}); pass frm=")
-    if frm == to:
-        return text
-    fn = _TRANSITIONS.get((convention_id, frm, to))
-    if fn is None:
-        supported = sorted(f"{f}->{t}" for (c, f, t) in _TRANSITIONS
-                           if c == convention_id)
+
+CONVENTION_REGISTRY: Dict[str, Convention] = {c.id: c for c in (
+    _marks("tashkeel", "Arabic vocalization (harakat/tanwin/shadda/sukun)",
+           ("Arab",), _TASHKEEL_RANGES,
+           "Unicode 15 ch. 9.2 (Arabic); excludes letter-identity U+0653-0655"),
+    _marks("kashida", "Arabic justification elongation (tatweel)",
+           ("Arab",), _KASHIDA_RANGES, "Unicode U+0640 ARABIC TATWEEL",
+           default="none"),
+    _marks("quranic-marks", "Quranic annotation signs",
+           ("Arab",), _QURANIC_RANGES,
+           "Unicode U+06D6-06ED Quranic annotation signs", default="none"),
+    _marks("niqqud", "Hebrew vocalization points",
+           ("Hebr",), _NIQQUD_RANGES,
+           "Unicode 15 ch. 9.1 (Hebrew); strip loses the shin/sin dot distinction"),
+    _marks("teamim", "Hebrew cantillation marks",
+           ("Hebr",), _TEAMIM_RANGES,
+           "Unicode U+0591-05AF Hebrew accents (masoretic)", default="none"),
+    Convention("wakachigaki", "Japanese spaced writing (分かち書き)",
+               ("Hira", "Kana", "Hani"), "japanese", ("marked", "none"), "none",
+               (), "Spaced orthographic mode of Japanese (children's books, games)",
+               transitions=(
+                   Transition("marked", "none", _wakachigaki_strip),
+                   Transition("none", "marked", _wakachigaki_apply, requires="ja"),
+               )),
+    Convention("pinyin-tone", "Pinyin tone spelling",
+               ("Latn",), "pinyin", ("mark", "number", "none"), "mark",
+               (), "GB/T 16159 Basic rules of Hanyu Pinyin orthography",
+               transitions=(
+                   Transition("mark", "number", _pinyin_mark_to_number),
+                   Transition("number", "mark", _pinyin_number_to_mark),
+                   Transition("mark", "none", _pinyin_strip),
+                   Transition("number", "none", _pinyin_strip),
+               )),
+    Convention("jamo-form", "Hangul jamo repertoire (compatibility vs conjoining)",
+               ("Hang",), None, ("compatibility", "conjoining"), "compatibility",
+               (), "Unicode Hangul Compatibility Jamo U+3130 vs Hangul Jamo U+1100",
+               transitions=(
+                   Transition("conjoining", "compatibility",
+                              _jamo_conjoining_to_compat, lossless=True),
+                   Transition("compatibility", "conjoining",
+                              _jamo_compat_to_conjoining, lossless=True),
+               ),
+               detector=_jamo_detect),
+)}
+
+
+def conventions_for(script: str) -> List[Convention]:
+    """Conventions that decorate *script* (ISO-15924 code), registry order."""
+    return [c for c in CONVENTION_REGISTRY.values() if script in c.scripts]
+
+
+def _conv(convention_id: str) -> Convention:
+    try:
+        return CONVENTION_REGISTRY[convention_id]
+    except KeyError:
         raise ValueError(
-            f"{convention_id!r} does not define {frm!r}->{to!r}; "
-            f"supported: {', '.join(supported)}")
-    return fn(text)
+            f"unknown convention {convention_id!r}; known: "
+            f"{', '.join(sorted(CONVENTION_REGISTRY))}") from None
+
+
+# Module-level facades over the conventions' own behavior — the published API.
+
+def restyle(text: str, convention_id: str, to: str,
+            frm: Optional[str] = None) -> str:
+    """Rewrite *text* from one style of a convention to another."""
+    return _conv(convention_id).restyle(text, to, frm=frm)
 
 
 def strip(text: str, convention_id: str) -> str:
     """Remove a convention's decoration (restyle to ``"none"``)."""
-    conv = _conv(convention_id)
-    if "none" not in conv.styles:
-        raise ValueError(f"{convention_id!r} has no unmarked style; "
-                         f"styles: {conv.styles}")
-    frm = "mark" if conv.id == "pinyin-tone" else "marked"
-    if conv.id == "pinyin-tone":
-        # digits and marks are both handled by the strip transition
-        return _pinyin_strip(text)
-    return restyle(text, convention_id, "none", frm=frm)
+    return _conv(convention_id).strip(text)
 
 
 def apply(text: str, convention_id: str, style: Optional[str] = None) -> str:
     """Add a convention's decoration to unmarked text (restyle from ``"none"``)."""
-    conv = _conv(convention_id)
-    if style is None:
-        marked = [s for s in conv.styles if s != "none"]
-        style = conv.default_style if conv.default_style != "none" else marked[0]
-    return restyle(text, convention_id, style, frm="none")
+    return _conv(convention_id).apply(text, style)
 
 
 def detect(text: str, convention_id: str) -> Optional[str]:
-    """Current style of *text* under a convention, or None when not character-evident.
-
-    For binary decorations this means "any mark present" — a single shadda in
-    a paragraph reports ``"marked"``.
-    """
-    conv = _conv(convention_id)
-    if not conv.detectable:
-        return None
-    if conv.id == "jamo-form":
-        return _jamo_detect(text)
-    return "marked" if any(_in_ranges(ord(c), conv.ranges) for c in text) else "none"
+    """Current style of *text* under a convention, or None when not character-evident."""
+    return _conv(convention_id).detect(text)