chore(api): freeze 1.0 public surface; fix Fill registry-key collision

[frederikbeimgraben]

1.0 prep: public-API freeze + Fill registry collision fix

Fill registry-key collision — chosen approach

pytex.commands.lengths.Fill (the rubber length \fill) and pytex_tikz.Fill
(the TikZ \fill path command) both registered under the single registry key
"Fill". Effects:

• import-order-dependent reverse lookup (tex2py / Registry.get),
• the \iffalse{pytex(...)}\fi eval namespace resolved bare Fill to whichever
  module imported last,
• importing both logged Duplicate key in registry (overwritten): Fill.

Fix: rename the length factory Fill → Fill_len (option b — rename one
symbol + deprecation alias).

Why not option (a) namespaced keys: the pytex(...) eval namespace is a flat
dict keyed by bare name. Two distinct public callables both named Fill cannot
coexist there unambiguously regardless of the registry-key scheme — qualifying
keys only fixes the duplicate-warning/reverse-lookup, the bare-name eval stays
ambiguous. Renaming is the only fix that makes the lookup deterministic.

Why _len: the package already uses this exact convention — Arraystretch_len
exists precisely because Arraystretch (the tables command) holds that key.
Following the established convention keeps the bare Fill key with the TikZ
command (parallel to Draw), and is self-justifying. A deprecated
pytex.commands.lengths.Fill module-level alias keeps importing and emits a
DeprecationWarning (mirrors the pytex_protocol shim). The TikZ Fill is
untouched.

Public-API freeze

Every package already declares an explicit __all__, and basedpyright validates
the entries (reportUnsupportedDunderAll), so the surface was already disciplined
— no churn was needed. Added a concise Stability section to the README
stating the 1.0 SemVer contract:

• Public: names a package exports via __all__, plus the registry keys
  reachable from pytex(...) markers (renaming a registered factory is breaking).
• Internal: leading-underscore names, underscore-prefixed modules
  (pytex_api._policy, pytex_api._compile), anything outside __all__.
• Deprecated shims (pytex_protocol, the lengths.Fill alias) warn and may be
  removed in the next major.

Tests

• registry keys for Fill / Fill_len are disjoint and deterministic,
• a fresh dual import logs no duplicate-key warning (subprocess),
• the deprecated lengths.Fill alias emits a DeprecationWarning.

Status

• ruff format --check src tests ✅ · ruff check src tests ✅
• basedpyright src ✅ 0 errors (0/0 on CI's Python 3.13; locally 1 warning is a
  3.14-only artifact of the existing \fill-3.14 reportUnreachable ignore — not
  touched by this PR)
• pytest -q ✅ 910 passed, 2 skipped

🤖 Generated with Claude Code