cutan 0.0.2__tar.gz

cutan-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

cutan-0.0.2/.gitignore

@@ -0,0 +1,176 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+# ANCHORED. Unanchored, `parts/` matches at any depth — and this repo's
+# character rigs keep their SVGs in `assets/characters/<ref>/parts/`, so the
+# template's buildout rule silently excluded every one of them (measured:
+# `git ls-files | grep parts/` returned ZERO). That is the an#33 failure shape
+# exactly: a fixture that renders from a build product nobody tracks, and a
+# clean checkout that draws a different picture with no error. Buildout's
+# directory is at the repo root, so anchoring loses nothing.
+/parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea
+
+# an per-project ephemera (renders, intermediates, agent state)
+examples/*/output/
+examples/*/artifacts/
+examples/*/assets/
+examples/*/.an/
+examples/*/.anima/
+examples/*/an.toml
+examples/*/anima.toml
+
+# The promote_demo example's input SVG is the whole point of the example
+# — keep it tracked even though examples/*/assets/ is otherwise ignored.
+!examples/promote_demo/assets/
+!examples/promote_demo/assets/characters/
+!examples/promote_demo/assets/characters/raw_maya/
+!examples/promote_demo/assets/characters/raw_maya/*.svg
+# But re-exclude the promote target — it's regenerated by build.py.
+examples/promote_demo/assets/characters/maya-promoted/
+
+# Agent worktrees (adversarial reviewers run isolated here so they cannot
+# mutate the shared checkout). Never committed, and excluded from tooling
+# below or ruff/pytest walk three extra copies of the whole repo.
+.claude/worktrees/
+
+# Session-boundary handoffs. Local working notes, not project docs — anything
+# that should outlive a session belongs in an issue or misc/docs/ instead.
+.claude/handoffs/
+
+# an bench corpus (an#38): the fixtures are COMMITTED WHOLE — their pixels have
+# to be a function of the repo alone — so only the per-render ephemera is
+# ignored here. Note there is deliberately no `assets/` rule: that is what
+# `examples/*/assets/` has, and it is why the corpus does not live there.
+misc/bench/corpus/*/output/
+misc/bench/corpus/*/artifacts/
+misc/bench/corpus/*/.an/
+misc/bench/corpus/*/ir/
+# …except `dialogue`'s IR, which is the fixture: the bench renders with
+# `auto_audio=False`, so the visemes a speaking scene needs must already be in
+# its committed `ir/scene.json` (offline provider, deterministic), exactly as
+# `examples/single_character/ir/scene.json` does. Without this carve-out the
+# scene would be mute on a clean checkout and its "mid-line" golden a lie (an#96).
+!misc/bench/corpus/dialogue/ir/
+!misc/bench/corpus/dialogue/ir/scene.json
+
+# `misc/demos/build_demos.py`'s output. Regenerable in a couple of minutes from
+# the committed script, and the media is published as release assets rather than
+# committed — `misc/` ships in the sdist, so a megabyte of GIFs would ride along
+# with every `pip install`.
+misc/demos/out/

cutan-0.0.2/CLAUDE.md

@@ -0,0 +1,42 @@
+# Working in the cutan repo
+
+`cutan` is the cut-out animation genre of [`an`](https://github.com/thorwhalen/an), split out of it per ADR 0001 (an#225, epic an#231). It depends on `an`; `an` never imports it (except through the registered hooks, `an.genres`).
+
+## Read first
+
+- `an`'s `CLAUDE.md` and `misc/docs/architecture_as_built.md` (§0a: core and genre, the seams this package plugs into). Decisions and the plan: `misc/docs/adr/0001-core-genre-split.md` and `misc/docs/plan_core_and_cutan_2026-10.md` in `an`.
+- This repo's skills (`.claude/skills/`): `cutan` (downstream: authoring cut-out scenes), `cutan-style`, `cutan-art-package`, and `cutan-dev-{expression,lipsync,rig-contract,swap-channels}` for the areas of the same names. Read the matching `cutan-dev-*` before touching a face, lip-sync, the rig contract or swap channels; for a pixel, an encode flag or the camera, the `an-dev-render-pipeline` and `an-dev-stage` skills in `an`.
+
+## Layout
+
+```
+cutan/genre.py        CUTOUT, the Genre object (entry point cutout_animation = "cutan.genre:CUTOUT"); nw.py: the nw declaration
+cutan/characters/     descriptor schema (CharacterDescriptor), factory, play resolution, methods, vocabulary, checks, CLI
+cutan/expression/     expression presets, axes, bindings, the face provider
+cutan/compile/        passes.py (the cut-out passes over an.stage.compile), lowering.py (play/expression lowering, swap declaration), coarticulate.py, gaze.py
+cutan/audio/          lip-sync providers (offline, rhubarb, whisper, word timings)
+cutan/impacts/        impact choreography and ground truth;  cutan/verify/style.py: the style lint;  cutan/library.py: the character analyser
+cutan/runtime/        visuals.js: the procedural mouth and eye, registered through the stage runtime's anRegisterVisual
+cutan/bench.py        CUTOUT_FIXTURES and run_bench() over this repo's misc/bench/ corpus
+tests/  examples/  misc/bench/{corpus,golden}/  misc/demos/  .claude/skills/
+```
+
+## Rules
+
+- **Persisted identifiers never change** (`cutan/__init__.py` lists them): `renderer: cutout`, the genre slug `cutout_animation`, the `CharacterDescriptor` document kind and its `schema_version`, the `character` asset kind and `characters` store, the action kinds `play` and `expression`, the compiled document's wire shape, the provenance provider string `"an character factory"` (licence `cc0-1.0`), the lip-sync provider names, the swap set names (`viseme`, `eyelid`, `view`, `hands`, `body_facing`) and the visual kinds `mouth` and `eye`.
+- **The pixel gate stays with the core.** The corpus contract hashes (`tests/test_expression_compose.py`) and the blessed golden frames (`misc/bench/golden/`) must not move without a bless record that says why. A PR here that can change a pixel is exercised against `an` main in CI. Never write that a rendering behaviour is "verified in CI" without saying where.
+- **Import `an` freely; `an` imports nothing of `cutan`.** If the core needs something from this package, add a registry or hook in `an` first (a service, `ActionKind.lowering`, `EntityKind.swap_declaration`, a compile pass, a runtime script). The compile passes may import `an.stage.compile` helpers (underscore names included): a genre depending on the core is allowed.
+- **A change to any module here changes the core's shot-cache key** (`an.stage.cache_key.genre_code_modules` keys every module of this package), so a cut-out shot re-renders after an upgrade. That is intended.
+- `cutan.REQUIRED_AN_API_LEVEL` is the lowest `an.genres.API_LEVEL` this package runs against (instead of a version pin: `an`'s version is assigned by CI at merge). Raise it in the same change that uses a new seam.
+- Local packages carry no version pins: `an`, not `an>=…`.
+- One `CLI`: `cutan` adds no console script. Its commands are `an character …` and `an impacts …`.
+- Shims in `an` (`an.characters`, `an.expression`, `an.impacts`, `an.audio.*_lipsync`, `an.verify.style`, `an.library.character`, `an.genres.cutout`, `an.genre`, `an.adapters.cutout.{coarticulate,gaze}`) are removed when no package under `$PP` imports an old path and 14 days have passed (checked by a script, not by memory).
+- Decisions of the move (the lead's, 2026-10-02): the bench *runner* stays in `an` (generic); skill names `cutan-style` and `cutan-dev-*`, with stubs of the old names left in `an` for one cycle; `an.genres.API_LEVEL` instead of a version floor.
+
+## Tests
+
+`pytest` from the repo root runs the tests and the doctests (`--doctest-modules` over `cutan/`, as CI does). The render tests are gated like `an`'s (`tests/conftest.py`): they need a headless browser and `ffmpeg`, and skip with a stated reason where those are absent. Tests that load a committed project in place depend on `scene.md` and `ir/scene.json` having the same age, which a fresh checkout gives them.
+
+## Data
+
+The genre's library root is `~/.local/share/cutan` (`CUTAN_HOME` overrides it), resolved by `an.library.root.library_root(package="cutan")`. Nothing in this repository holds assets or project data beyond the committed corpus and examples.

cutan-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+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.

cutan-0.0.2/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: cutan
+Version: 0.0.2
+Summary: Cut-out animation for an: rigged characters, faces, lip-sync and styles, as a genre package on the an core.
+Project-URL: Homepage, https://github.com/thorwhalen/cutan
+Project-URL: Repository, https://github.com/thorwhalen/cutan
+Project-URL: Documentation, https://thorwhalen.github.io/cutan
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: an,animation,cut-out,cutout,lip-sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: an
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: an[stage]; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# cutan
+
+Cut-out animation for [`an`](https://github.com/thorwhalen/an): rigged characters, faces and expressions, lip-sync, swap sets and views, impacts, and cut-out styles, as a genre package on the `an` core.
+
+```bash
+pip install "an[cutout]"      # an + the stage + cutan
+an character new maya --offline
+```
+
+`an` finds `cutan` through the `an.genres` entry point and loads it with `an.genres.load()` (the CLI and `an.load(project)` do). The scene format, rendering and the asset library are `an`'s; see its README.
+
+## What is here
+
+`cutan` registers with the core:
+
+- the `character` entity kind and the `play` and `expression` actions, the `[emotion]` dialogue sugar and the semantic checks that go with them (`cutan.genre`, `cutan.characters`, `cutan.expression`);
+- the rig, face, viseme, blink, gaze and swap-pose compile passes over the `an.stage` compiler (`cutan.compile`), and the mouth and eye visuals of the stage runtime (`cutan/runtime/visuals.js`);
+- the lip-sync providers `offline`, `rhubarb` and `whisper` (`cutan.audio`);
+- locomotion, speech, blink and turn methods with their requirements and defaults, and the cut-out vocabulary;
+- the `an character …` and `an impacts …` command namespaces;
+- the style lint (`python -m cutan.verify.style`) and the style specs of the `cutan-style` skill.
+
+The cut-out bench corpus (`misc/bench/`), `examples/` and the demo gallery (`misc/demos/`) live here too; `cutan.bench.run_bench()` runs the corpus through `an`'s bench runner.
+
+## Names that never change
+
+Moving the code renamed nothing that is stored. Scenes keep `renderer: cutout`, the genre keeps its slug `cutout_animation`, character descriptors keep their document kind and version, and asset ids keep their `character.` prefix. These names are in `cutan/__init__.py`. The old `an.characters`, `an.expression`, `an.impacts`, `an.audio.offline_lipsync`-style import paths still work in `an`, with a `MovedModuleWarning`.
+
+## Where data lives
+
+The genre's asset library and agent-made projects live under `~/.local/share/cutan` by default. Set `CUTAN_HOME` to move them. The core's own library (voices, sounds, fonts) stays under `an`'s root, and a project reads both as one search path.
+
+## Working on cutan
+
+Read `CLAUDE.md`. In short: `pip install -e . --no-deps` next to an editable `an`, then `pytest`. The tests that render need a headless browser (`playwright install chromium`) and `ffmpeg`.

cutan-0.0.2/README.md

@@ -0,0 +1,35 @@
+# cutan
+
+Cut-out animation for [`an`](https://github.com/thorwhalen/an): rigged characters, faces and expressions, lip-sync, swap sets and views, impacts, and cut-out styles, as a genre package on the `an` core.
+
+```bash
+pip install "an[cutout]"      # an + the stage + cutan
+an character new maya --offline
+```
+
+`an` finds `cutan` through the `an.genres` entry point and loads it with `an.genres.load()` (the CLI and `an.load(project)` do). The scene format, rendering and the asset library are `an`'s; see its README.
+
+## What is here
+
+`cutan` registers with the core:
+
+- the `character` entity kind and the `play` and `expression` actions, the `[emotion]` dialogue sugar and the semantic checks that go with them (`cutan.genre`, `cutan.characters`, `cutan.expression`);
+- the rig, face, viseme, blink, gaze and swap-pose compile passes over the `an.stage` compiler (`cutan.compile`), and the mouth and eye visuals of the stage runtime (`cutan/runtime/visuals.js`);
+- the lip-sync providers `offline`, `rhubarb` and `whisper` (`cutan.audio`);
+- locomotion, speech, blink and turn methods with their requirements and defaults, and the cut-out vocabulary;
+- the `an character …` and `an impacts …` command namespaces;
+- the style lint (`python -m cutan.verify.style`) and the style specs of the `cutan-style` skill.
+
+The cut-out bench corpus (`misc/bench/`), `examples/` and the demo gallery (`misc/demos/`) live here too; `cutan.bench.run_bench()` runs the corpus through `an`'s bench runner.
+
+## Names that never change
+
+Moving the code renamed nothing that is stored. Scenes keep `renderer: cutout`, the genre keeps its slug `cutout_animation`, character descriptors keep their document kind and version, and asset ids keep their `character.` prefix. These names are in `cutan/__init__.py`. The old `an.characters`, `an.expression`, `an.impacts`, `an.audio.offline_lipsync`-style import paths still work in `an`, with a `MovedModuleWarning`.
+
+## Where data lives
+
+The genre's asset library and agent-made projects live under `~/.local/share/cutan` by default. Set `CUTAN_HOME` to move them. The core's own library (voices, sounds, fonts) stays under `an`'s root, and a project reads both as one search path.
+
+## Working on cutan
+
+Read `CLAUDE.md`. In short: `pip install -e . --no-deps` next to an editable `an`, then `pytest`. The tests that render need a headless browser (`playwright install chromium`) and `ffmpeg`.

cutan-0.0.2/conftest.py

@@ -0,0 +1,265 @@
+"""Repository-wide pytest setup: load the genres, as the real entry points do.
+
+Genres are discovered explicitly (ADR 0001 decision 3): importing ``an``
+registers none, and ``an.load(project)`` / the CLI call
+:func:`an.genres.load`. Most tests and doctests build scenes with the cut-out
+genre's kinds (``play``, ``expression``, ``character``, ``[emotion]``)
+without going through either, so the session calls the same
+:func:`an.genres.load` once, here — the in-distribution genres are found
+whatever the installed metadata says. Tests of the unloaded core use
+:func:`an.genres.without_genres`; the entry points themselves are held by
+subprocess tests that run with no pre-registration
+(``tests/test_open_document_model.py``).
+
+At the repository root so it reaches both ``tests/`` and the doctests under
+``an/`` (CI's ``--doctest-modules``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def pytest_configure(config):  # noqa: D103 — a pytest hook
+    from an.genres import load
+
+    load()
+    _install_real_home_guard()
+    _redirect_account_home_for_the_session()
+
+
+#: What the session guard found: stack traces of writes that reached the real
+#: account's data folder (review-269 B3).
+_REAL_HOME_WRITES: list[str] = []
+_REAL_DATA_SNAPSHOT: dict = {}
+
+
+def _real_data_dirs():
+    from an.library import registry
+    import sys
+
+    from an.library.root import POSIX_DATA_DEFAULT, WINDOWS_DATA_DEFAULT
+
+    defaults = (
+        WINDOWS_DATA_DEFAULT if sys.platform.startswith("win") else POSIX_DATA_DEFAULT
+    )
+    data = registry._account_home().joinpath(*defaults)
+    return [data / "an", data / "cutan"]
+
+
+def _snapshot(dirs) -> dict:
+    out = {}
+    for d in dirs:
+        if not d.exists():
+            continue
+        for p in d.rglob("*"):
+            try:
+                st = p.lstat()
+            except OSError:
+                continue
+            out[str(p)] = (st.st_mtime_ns, st.st_size)
+    return out
+
+
+def _install_real_home_guard() -> None:
+    """Fail the run if this process writes into the real account's data folder.
+
+    Two layers, installed before any fixture runs:
+
+    - a tripwire, in this process: every library-store write and every
+      machine-registry path that lands under the real data folder is recorded
+      with its stack, and fails the session (``pytest_sessionfinish``);
+    - a snapshot of ``<data>/an`` and ``<data>/cutan`` before and after the
+      session. On CI (``CI`` set) any difference fails the run. On a developer
+      machine other sessions (an end-to-end render, an agent publishing) write
+      there concurrently, so a difference is reported, and fails only with
+      ``AN_TEST_HOME_GUARD=strict``.
+    """
+    import traceback
+
+    from an.library import registry, stores
+
+    data_dirs = _real_data_dirs()
+    real_prefixes = tuple(str(d) for d in data_dirs)  # not their parent: on Windows
+    # the temp dir (home of the redirect) sits inside `AppData/Local`.
+    _REAL_DATA_SNAPSHOT["dirs"] = data_dirs
+    _REAL_DATA_SNAPSHOT["home"] = registry._account_home()
+    _REAL_DATA_SNAPSHOT["before"] = _snapshot(data_dirs)
+
+    def note(path) -> None:
+        if str(path).startswith(real_prefixes):
+            _REAL_HOME_WRITES.append(
+                f"{path}\n" + "".join(traceback.format_stack(limit=30))
+            )
+
+    temp, delete = stores.LocalFiles._temp, stores.LocalFiles.__delitem__
+
+    def guarded_temp(self, path, data):
+        note(path)
+        return temp(self, path, data)
+
+    def guarded_delete(self, key):
+        note(self._path(key))
+        return delete(self, key)
+
+    stores.LocalFiles._temp = guarded_temp
+    stores.LocalFiles.__delitem__ = guarded_delete
+    registry_dir = registry.machine_registry_dir
+
+    def guarded_registry_dir():
+        out = registry_dir()
+        note(out)
+        return out
+
+    registry.machine_registry_dir = guarded_registry_dir
+
+
+def pytest_collection_modifyitems(config, items):  # noqa: D103 — a pytest hook
+    # Every test gets a fresh registry, so every publish is a "first use": the
+    # RegistryWarning would fire once per publishing test and bury real
+    # warnings (review-269 N2). `pytest.warns` still sees it.
+    mark = pytest.mark.filterwarnings("ignore::an.library.registry.RegistryWarning")
+    for item in items:
+        item.add_marker(mark)
+
+
+def pytest_sessionfinish(session, exitstatus):  # noqa: D103 — a pytest hook
+    import os
+
+    reporter = session.config.pluginmanager.get_plugin("terminalreporter")
+
+    def say(text: str) -> None:
+        if reporter is not None:
+            reporter.write_line(text)
+
+    child_log = _CHILD_STATE.get("path")
+    if child_log is not None and child_log.exists() and child_log.stat().st_size:
+        say(
+            "REAL-HOME GUARD: a CHILD python process reached the real data folder "
+            "despite the redirect (an#302):\n"
+            + child_log.read_text(encoding="utf-8")[:4000]
+        )
+        session.exitstatus = 1
+    if _REAL_HOME_WRITES:
+        say(
+            f"REAL-HOME GUARD: {len(_REAL_HOME_WRITES)} write(s) or registry access(es) "
+            "reached the real data folder from this test process; first one:\n"
+            + _REAL_HOME_WRITES[0]
+        )
+        session.exitstatus = 1
+    if "before" in _REAL_DATA_SNAPSHOT:
+        after = _snapshot(_REAL_DATA_SNAPSHOT["dirs"])
+        before = _REAL_DATA_SNAPSHOT["before"]
+        changed = sorted(
+            k for k in set(before) | set(after) if before.get(k) != after.get(k)
+        )
+        if changed:
+            strict = (
+                os.environ.get("CI") or os.environ.get("AN_TEST_HOME_GUARD") == "strict"
+            )
+            say(
+                f"REAL-HOME GUARD: {len(changed)} path(s) under the real data folder "
+                "changed during the session"
+                + (
+                    ""
+                    if strict
+                    else " (another process? set AN_TEST_HOME_GUARD=strict to fail on it)"
+                )
+                + ":\n  "
+                + "\n  ".join(changed[:20])
+            )
+            if strict:
+                session.exitstatus = 1
+
+
+def _redirect_account_home_for_the_session() -> None:
+    """Point the machine registry into a temp folder for the WHOLE session.
+
+    The per-test fixture below gives each test a fresh registry, but a
+    module- or session-scoped fixture runs before it: one that draws a
+    character (the factory records what it draws, an#269) or publishes would
+    otherwise write the developer's real ``~/.local/share/an/registry``. This
+    session-wide redirect is what those fixtures see; each test still gets
+    its own fresh one.
+    """
+    import tempfile
+    from an.library import registry
+
+    home = Path(tempfile.mkdtemp(prefix="an-session-account-home-"))
+    registry._account_home = lambda: home
+    _redirect_children_too(home)
+
+
+#: Environment variable naming the redirected account home for child pythons.
+CHILD_HOME_ENV: str = "AN_TEST_ACCOUNT_HOME"
+#: Environment variable naming the file a child appends to if it reaches the real data folder.
+CHILD_LOG_ENV: str = "AN_TEST_REAL_HOME_LOG"
+#: The folder whose ``sitecustomize`` applies the redirect inside a child (an#302).
+CHILD_GUARD_DIR = Path(__file__).parent / "tests" / "_child_guard"
+
+
+def _redirect_children_too(home) -> None:
+    """Make every child python process the tests spawn honour the same redirect.
+
+    The monkeypatch above lives in THIS interpreter; a child (a CLI test, a
+    ``[sys.executable, "-c", ...]`` probe) is a new one and, left alone, would
+    write the developer's real registry (an#302). The library reads no
+    environment variable for that location, so the redirect rides on
+    ``tests/_child_guard/sitecustomize.py`` instead, put on each child's
+    ``PYTHONPATH`` by wrapping ``subprocess.Popen`` — whatever ``env=`` the
+    test built, including one that replaces ``PYTHONPATH`` wholesale.
+    A child that reaches the real folder regardless logs itself to
+    ``CHILD_LOG_ENV``, and :func:`pytest_sessionfinish` fails the run on it.
+    """
+    import os
+    import subprocess
+
+    log = home / "child-real-home-writes.log"
+    os.environ[CHILD_HOME_ENV] = str(home)
+    os.environ[CHILD_LOG_ENV] = str(log)
+    _CHILD_STATE["path"] = log
+    _CHILD_STATE["home"] = home
+    init = subprocess.Popen.__init__
+
+    def popen_init(self, *args, **kwargs):
+        env = dict(os.environ if kwargs.get("env") is None else kwargs["env"])
+        # The CURRENT home: the per-test fixture swaps it, like the in-process one.
+        env[CHILD_HOME_ENV] = str(_CHILD_STATE["home"])
+        env.setdefault(CHILD_LOG_ENV, str(log))
+        existing = env.get("PYTHONPATH")
+        env["PYTHONPATH"] = os.pathsep.join(
+            [str(CHILD_GUARD_DIR)] + ([existing] if existing else [])
+        )
+        kwargs["env"] = env
+        return init(self, *args, **kwargs)
+
+    subprocess.Popen.__init__ = popen_init
+
+
+#: Where the child-process tripwire writes (set by :func:`_redirect_children_too`).
+_CHILD_STATE: dict = {}
+
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _isolated_library_registry(tmp_path_factory, monkeypatch):
+    """Point the machine's library registry and statement memory into a fresh temp folder.
+
+    The registry (:mod:`an.library.registry`, an#249) lives under the account's
+    home as the OS records it, deliberately ignoring every environment variable,
+    so the ``AN_HOME`` / ``XDG_DATA_HOME`` redirection the library tests use
+    cannot move it. Every test and doctest that publishes would otherwise
+    append to the developer's real registry — and one test's private bytes
+    would sit in the next test's rights floor. Fresh per test, for both
+    reasons. The account home is what is replaced, so the real path logic
+    (``machine_registry_path``) still runs, and a test can hold it to its
+    independence from the environment.
+    """
+    from an.library import registry
+
+    home = tmp_path_factory.mktemp("account-home")
+    monkeypatch.setattr(registry, "_account_home", lambda: home)
+    # Children get the same fresh registry (an#302), restored afterwards.
+    monkeypatch.setitem(_CHILD_STATE, "home", home)