texpkg 0.1.0__tar.gz → 0.2.0__tar.gz

texpkg-0.2.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: texpkg
+Version: 0.2.0
+Summary: LaTeX package management.
+Author-Email: Ilja Orlovs <ilja@release.art>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/release-art/texpkg
+Project-URL: Repository, https://github.com/release-art/texpkg
+Requires-Python: <3.16,>=3.15
+Requires-Dist: texmodel>=0.7.0
+Requires-Dist: pydantic>=2.14.1
+Provides-Extra: build
+Requires-Dist: typer>=0.27.3; extra == "build"
+Requires-Dist: pdm-backend>=2.4; extra == "build"
+Description-Content-Type: text/markdown
+
+# texpkg
+
+TeX packages published as Python packages. A texpkg package is one wheel: a [texmodel](https://github.com/release-art/texmodel)
+API and the TeX it compiles against, at one version. Installed, it is a Python module with a fixed API to load, render,
+save and check document directories, with versioned data and migrations; packages can build on each other, the base
+embedded in the dependent at build time.
+
+An author declares a package (`Distribution`, `Kind`, `Asset`) and builds it with `texpkg-build`, a pdm build hook. The
+spec, the API reference and the decisions are in [docs/texpkg-plan.md](docs/texpkg-plan.md); what texpkg does not do is in
+[docs/known-limitations.md](docs/known-limitations.md).
+
+```zsh
+pdm install
+git config core.hooksPath .githooks   # pre-commit runs ruff, pyright and import-linter
+bin/autoformat.sh
+bin/test.sh                           # pytest, 100% coverage gate
+```

texpkg-0.2.0/README.md

@@ -0,0 +1,17 @@
+# texpkg
+
+TeX packages published as Python packages. A texpkg package is one wheel: a [texmodel](https://github.com/release-art/texmodel)
+API and the TeX it compiles against, at one version. Installed, it is a Python module with a fixed API to load, render,
+save and check document directories, with versioned data and migrations; packages can build on each other, the base
+embedded in the dependent at build time.
+
+An author declares a package (`Distribution`, `Kind`, `Asset`) and builds it with `texpkg-build`, a pdm build hook. The
+spec, the API reference and the decisions are in [docs/texpkg-plan.md](docs/texpkg-plan.md); what texpkg does not do is in
+[docs/known-limitations.md](docs/known-limitations.md).
+
+```zsh
+pdm install
+git config core.hooksPath .githooks   # pre-commit runs ruff, pyright and import-linter
+bin/autoformat.sh
+bin/test.sh                           # pytest, 100% coverage gate
+```

{texpkg-0.1.0 → texpkg-0.2.0}/pyproject.toml

@@ -17,10 +17,10 @@ classifiers = [
 ]
 requires-python = ">=3.15,<3.16"
 dependencies = [
-    "texmodel>=0.4.0",
+    "texmodel>=0.7.0",
     "pydantic>=2.14.1",
 ]
-version = "0.1.0"
+version = "0.2.0"
 
 [project.optional-dependencies]
 build = [

{texpkg-0.1.0 → texpkg-0.2.0}/src/texpkg/_internal/adopt.py

@@ -7,10 +7,12 @@ left aborts with the report.
 """
 
 import copy
+import re
 from collections.abc import Iterator, Mapping, Sequence
-from typing import Any
+from typing import Any, cast
 
 from texmodel.components import Node
+from texmodel.package import Package
 
 from ..declaration import Kind
 from ..errors import MigrationError
@@ -18,10 +20,12 @@ from ..migration import DefaultChange, Migration, Unresolved
 from . import state
 from .envelope import Envelope
 from .history import problems, unplaced
+from .state import Extras
 
 UNRESOLVED = (
     "$unresolved"  # in the state a migration gets: what the earlier ones left, as `{"path", "reason", "value"}`
 )
+EXTRAS = "$extras"  # in the state a migration gets: the document's `settings`, `options` and `preamble` (D10)
 
 
 def _policy(changes: DefaultChange | Mapping[str, DefaultChange], path: str, key: str) -> DefaultChange:
@@ -76,9 +80,40 @@ def _kind_migrations(kind: Kind, boundary: int, base_data: Mapping[int, int] | N
     return [m for m in kind.migrations if low < m.to <= high]
 
 
+def _data_path(path: str) -> list[str]:
+    """The parts of a texmodel path (`settings[1].value`) as data keys (`settings`, `1`, `value`)."""
+    return [part for part in re.split(r"[.\[\]]+", path) if part]
+
+
+def _value_at(data: object, keys: list[str]) -> object:
+    for key in keys:
+        try:
+            data = (
+                cast("list[object]", data)[int(key)] if isinstance(data, list) else cast("dict[str, object]", data)[key]
+            )
+        except KeyError, IndexError, TypeError, ValueError:
+            return None
+    return data
+
+
+def _extras_problems(kind: Kind, package: Package, data: dict[str, Any]) -> tuple[Extras, list[dict[str, Any]]]:
+    """The extras `data` describes and what stops them from being the kind's: texmodel's errors and what the kind
+    does not allow, as unresolved items."""
+    try:
+        extras = state.extras_from(package, data)
+    except ExceptionGroup as group:
+        found: list[dict[str, Any]] = []
+        for e in group.exceptions:
+            keys = _data_path(str(getattr(e, "path", "")))
+            found.append({"path": "/" + "/".join(keys), "reason": str(e), "value": _value_at(data, keys), "schema": {}})
+        return Extras(), found
+    return extras, state.not_allowed(kind, extras)
+
+
 def adopt(
     *,
     kind: Kind,
+    package: Package,
     envelope: Envelope,
     current: int,
     age: int,
@@ -86,10 +121,11 @@ def adopt(
     policy: DefaultChange | Mapping[str, DefaultChange],
     saved_defaults: Mapping[str, Any] | None,
     base_data: Mapping[int, int] | None = None,
-) -> Node:
-    """The tree of `kind` that `envelope` describes at `data` version `current`, or a `MigrationError` naming everything
-    that no migration placed. Nothing is written."""
+) -> tuple[Node, Extras]:
+    """The tree and extras of `kind` that `envelope` describes at `data` version `current`, or a `MigrationError` naming
+    everything that no migration placed. Nothing is written."""
     tree = copy.deepcopy(envelope.tree)
+    extras_data = copy.deepcopy(envelope.extras)
     left: list[dict[str, Any]] = []
     if saved_defaults is not None:
         left += default_changes(tree, saved_defaults, state.defaults_table(kind.model), policy)
@@ -97,11 +133,14 @@ def adopt(
         for boundary in range(envelope.data + 1, current + 1):
             label = f"{boundary - 1} -> {boundary}"
             for migration in (*_kind_migrations(kind, boundary, base_data), *(m for m in consumer if m.to == boundary)):
-                tree[UNRESOLVED] = left
+                tree[UNRESOLVED], tree[EXTRAS] = left, extras_data
                 result = migration(tree)
                 tree = result.state
+                extras_data = tree.pop(EXTRAS, {})
                 left = [*tree.pop(UNRESOLVED, []), *({**vars(u), "boundary": label} for u in result.unresolved)]
-    schema = state.schema(kind.model, "validation")
+    schema = state.tree_schema(kind.model, "validation")
+    extras, found = _extras_problems(kind, package, extras_data)
+    left += [{**p, "boundary": "validation"} for p in found]
     left += [{**p, "boundary": "validation"} for p in unplaced(tree, schema)]
     left += [{**p, "boundary": "validation"} for p in problems(kind.model, state.given(tree), schema)]
     if left:
@@ -116,4 +155,4 @@ def adopt(
             unresolved=items,
             hint="extend the process with a migration of your own: load(path, migrations=[...])",
         )
-    return state.tree_from_state(kind.model, tree)
+    return state.tree_from_state(kind.model, tree), extras

{texpkg-0.1.0 → texpkg-0.2.0}/src/texpkg/_internal/classify.py

@@ -50,12 +50,24 @@ def _compare_property(where: str, old: dict[str, Any], new: dict[str, Any]) -> l
         out.append(Change(Level.BREAKING if tighter else Level.COMPATIBLE, where, f"{key} {was} -> {now}"))
     if old.get("items") != new.get("items") and "items" in old:
         out += _compare_items(where, old["items"], new.get("items", {}))
+    out += _compare_inline(where, old.get("properties", {}), new.get("properties", {}))
     for key in ("default", "description", "title"):
         if old.get(key) != new.get(key):
             out.append(Change(Level.REVISION, where, f"{key} changed"))
     return out
 
 
+def _compare_inline(where: str, before: dict[str, Any], after: dict[str, Any]) -> list[Change]:
+    """The properties of an object written inline in a property, not as a class of its own."""
+    out: list[Change] = []
+    for name in before:
+        if name in after:
+            out += _compare_property(f"{where}.{name}", before[name], after[name])
+        else:
+            out.append(Change(Level.BREAKING, f"{where}.{name}", "removed"))
+    return out + [Change(Level.COMPATIBLE, f"{where}.{name}", "added") for name in sorted(after.keys() - before.keys())]
+
+
 def _compare_items(where: str, old: dict[str, Any], new: dict[str, Any]) -> list[Change]:
     """The element schema of a list: a branch of a union that went is breaking, one that came is compatible."""
 

{texpkg-0.1.0 → texpkg-0.2.0}/src/texpkg/_internal/envelope.py

@@ -1,5 +1,6 @@
-"""The envelope of a stored document: `{package, kind, data, tree}` (K3). It names the package and kind the tree belongs
-to and the `data` version it was written for (V14)."""
+"""The envelope of a stored document: `{package, kind, data, tree}` (K3), and `settings`, `options` and `preamble` when
+the document has any (D10). It names the package and kind the tree belongs to and the `data` version it was written
+for (V14)."""
 
 import dataclasses
 import json
@@ -7,6 +8,8 @@ from typing import Any
 
 from ..errors import NotADocumentError
 
+EXTRA_KEYS = ("settings", "options", "preamble")
+
 
 def dumps(value: object) -> str:
     """The text of a state file: stable, readable, one trailing newline."""
@@ -19,15 +22,18 @@ class Envelope:
     kind: str
     data: int
     tree: dict[str, Any]
+    extras: dict[str, Any] = dataclasses.field(default_factory=dict[str, Any])  # `settings`, `options`, `preamble`
 
     def to_text(self) -> str:
-        return dumps({"package": self.package, "kind": self.kind, "data": self.data, "tree": self.tree})
+        head = {"package": self.package, "kind": self.kind, "data": self.data, "tree": self.tree}
+        return dumps(head | self.extras)
 
     @classmethod
     def parse(cls, text: str, where: str) -> "Envelope":
         try:
             found = json.loads(text)
-            return cls(str(found["package"]), str(found["kind"]), int(found["data"]), dict(found["tree"]))
+            extras = {key: found[key] for key in EXTRA_KEYS if key in found}
+            return cls(str(found["package"]), str(found["kind"]), int(found["data"]), dict(found["tree"]), extras)
         except (ValueError, KeyError, TypeError) as exc:
             raise NotADocumentError(
                 f"{where}: not a document state ({exc!r})",

{texpkg-0.1.0 → texpkg-0.2.0}/src/texpkg/_internal/handedits.py

@@ -8,12 +8,28 @@ import re
 from collections.abc import Sequence
 
 from texmodel.plan import Edit, Plan
+from texmodel.preamble import PreambleSlots
 
 from . import directory
 
 _NODE = re.compile(r"[A-Z][A-Za-z]*\[(\d+)\]")  # a component's name: a capital, then letters (TM-M001)
 
 
+_SETTING = re.compile(r"settings\[(\d+)\]")
+_ENTRY = re.compile(r"preamble\.(before_class|before_package|after_package)\[(\d+)\]")
+
+
+def extra_path(plan_path: str, *, locked: int, layout: PreambleSlots) -> str:
+    """The data path of a line that a setting or a preamble entry of the document wrote (D10), or `""`: the kind's own
+    `locked` settings come first in the plan, then the document's, and the layout's lines lead each preamble slot."""
+    if found := _SETTING.fullmatch(plan_path):
+        return f"/settings/{int(found[1]) - locked}" if int(found[1]) >= locked else ""
+    if found := _ENTRY.fullmatch(plan_path):
+        own = int(found[2]) - len(getattr(layout, found[1]))
+        return f"/preamble/{found[1]}/{own}" if own >= 0 else ""
+    return ""
+
+
 def data_path(plan_path: str) -> str:
     """The data path of a plan path: `Deck[0]/Card[1]/Title[0]` is `/content/1/content/0`, the root being the document.
     A line that no node wrote (`header`, `preamble.before_package[0]`, `settings[2]`) keeps its plan path."""

{texpkg-0.1.0 → texpkg-0.2.0}/src/texpkg/_internal/release.py

@@ -13,8 +13,10 @@ from collections.abc import Mapping, Sequence
 from typing import Any, cast
 
 from texmodel.components import AnyValue, Command, Environment, Node
+from texmodel.document import Document as TexDocument
 from texmodel.package import setting_line
 from texmodel.plan import Plan
+from texmodel.preamble import PreambleSlots
 
 from .. import provenance
 from ..assets import Role
@@ -27,11 +29,13 @@ from ..errors import (
     KindMismatchError,
     NewerDataError,
     NotADocumentError,
+    NotAllowedError,
 )
 from ..migration import DefaultChange, Migration
 from . import directory, export, payload, snapshots, state
 from .adopt import adopt
 from .envelope import Envelope, dumps
+from .state import Extras
 
 
 @dataclasses.dataclass(frozen=True)
@@ -67,13 +71,34 @@ class Release:
         base = self.dist.base_kind(kind)
         return (*(base.presets if base else ()), *kind.settings(variant))
 
-    def plan(self, kind: Kind, tree: Node, variant: str | None) -> Plan:
-        """The `.tex` of `tree` as lines with provenance: the kind's presets, then the variant's settings (L8).
+    def _has_graphics(self, kind: Kind) -> bool:
+        kinds = (kind.name, *([kind.over] if kind.over else []))
+        return any(r.asset.role is Role.GRAPHIC and r.asset.needed_by(kinds) for r in self.dist.resolved_assets())
+
+    def layout_preamble(self, kind: Kind) -> PreambleSlots:
+        """The lines that find the payload, which come before a document's own entries (A5)."""
+        return self.dist.layout.preamble(graphics=self._has_graphics(kind))
+
+    def plan(self, kind: Kind, tree: Node, variant: str | None, extras: Extras = Extras()) -> Plan:  # noqa: B008
+        """The `.tex` of `tree` as lines with provenance: the kind's presets, then the variant's settings (L8), then the
+        document's own settings (D10).
 
         An exposed base kind is written by the base's package; the directory's layout is this distribution's."""
         body = tree if kind.expand is None else kind.expand(tree)
         package = self.dist.owner(kind.name).package
-        return package.plan(body, settings=self.settings(kind, variant), preamble=self.dist.layout.preamble())
+        found, own = self.layout_preamble(kind), extras.preamble
+        return package.plan(
+            TexDocument(
+                body,
+                options=extras.options,
+                settings=(*self.settings(kind, variant), *extras.settings),
+                preamble=PreambleSlots(
+                    before_class=own.before_class,
+                    before_package=(*found.before_package, *own.before_package),
+                    after_package=(*found.after_package, *own.after_package),
+                ),
+            )
+        )
 
     def export(
         self, destination: pathlib.Path | str, now: datetime.datetime | None, stamp: str | None
@@ -102,11 +127,11 @@ class Release:
         files = {**self.sty, **(provenance or {})}
         return payload.build(files, tuple(self.dist.resolved_assets()), self.dist.layout, kinds)
 
-    def rendered(self, kind: Kind, tree: Node) -> dict[str, str]:
+    def rendered(self, kind: Kind, tree: Node, extras: Extras = Extras()) -> dict[str, str]:  # noqa: B008
         """Every `.tex` of the kind with the plan of it that `save` keeps (D7), by path in the directory."""
         files: dict[str, str] = {}
         for variant, name in kind.documents():
-            plan = self.plan(kind, tree, variant)
+            plan = self.plan(kind, tree, variant, extras)
             files |= {name: plan.text, directory.plan_file(variant): plan.to_json()}
         return files
 
@@ -131,9 +156,11 @@ class Release:
             "stack": self.stack(),
         }
 
-    def states(self, kind: Kind, tree: Node) -> dict[str, str]:
+    def states(self, kind: Kind, tree: Node, extras: Extras = Extras()) -> dict[str, str]:  # noqa: B008
         """The pair of states `save` and `create` write (D1)."""
-        envelope = Envelope(self.dist.name, kind.name, self.contracts.data.current, state.tree_state(tree))
+        envelope = Envelope(
+            self.dist.name, kind.name, self.contracts.data.current, state.tree_state(tree), state.extras_state(extras)
+        )
         return {directory.STATE: envelope.to_text(), directory.TEMPLATE: dumps(self.template(kind))}
 
     def read(self, path: pathlib.Path) -> Envelope:
@@ -196,7 +223,27 @@ class KindApi[T: Command | Environment]:
             )
         self.release, self.kind = release, kind
 
-    def create(self, path: pathlib.Path | str, tree: T) -> Document[T]:
+    def extras(self, settings: Sequence[AnyValue], options: Sequence[str], preamble: PreambleSlots | None) -> Extras:
+        """What a document carries besides its tree, refused whole if the kind does not allow it (D10)."""
+        found = Extras(tuple(options), tuple(settings), preamble or PreambleSlots())
+        if items := state.not_allowed(self.kind, found):
+            shown = "; ".join(f"{i['path']}: {i['reason']}" for i in items)
+            raise NotAllowedError(
+                f"kind {self.kind.name}: {shown}",
+                items=tuple(items),
+                hint="the kind lists what a document may set: Kind(settable=, options=, preamble=)",
+            )
+        return found
+
+    def create(
+        self,
+        path: pathlib.Path | str,
+        tree: T,
+        *,
+        settings: Sequence[AnyValue] = (),
+        options: Sequence[str] = (),
+        preamble: PreambleSlots | None = None,
+    ) -> Document[T]:
         """A document in `path` (made if need be) with both states written; refuses a directory that holds one."""
         path = pathlib.Path(path)
         if (path / directory.STATE).exists():
@@ -208,8 +255,9 @@ class KindApi[T: Command | Environment]:
             )
         if problems := tree.violations():
             raise ExceptionGroup("invalid document", [v.error() for v in problems])
-        directory.write(path, self.release.states(self.kind, tree))
-        return Document(tree, path, self.release, self.kind)
+        extras = self.extras(settings, options, preamble)
+        directory.write(path, self.release.states(self.kind, tree, extras))
+        return Document(tree, path, self.release, self.kind, extras)
 
     def load(
         self,
@@ -232,8 +280,9 @@ class KindApi[T: Command | Environment]:
             )
         saved = directory.read(path, directory.TEMPLATE)
         template: dict[str, Any] = json.loads(saved) if saved else {}
-        tree = adopt(
+        tree, extras = adopt(
             kind=self.kind,
+            package=self.release.dist.owner(self.kind.name).package,
             envelope=envelope,
             current=self.release.contracts.data.current,
             age=self.release.contracts.data.age,
@@ -242,10 +291,10 @@ class KindApi[T: Command | Environment]:
             saved_defaults=template.get("defaults"),
             base_data=dict(self.release.contracts.base_data) if self.kind.name in self.release.dist.expose else None,
         )
-        return Document(cast("T", tree), path, self.release, self.kind)
+        return Document(cast("T", tree), path, self.release, self.kind, extras)
 
     def schema(self, mode: state.Mode) -> dict[str, Any]:
-        return state.schema(self.kind.model, mode)
+        return state.schema(self.kind, self.release.dist.owner(self.kind.name).package, mode)
 
     def example(self) -> T:
         return cast("T", self.kind.example())

texpkg-0.2.0/src/texpkg/_internal/state.py

@@ -0,0 +1,229 @@
+"""The stored form of a document: its schemas (V26) and what it carries besides its tree (D10).
+
+Two schemas per kind, from pydantic's two modes: the input one (a field with a default is optional) and the stored one
+(every field is written, V21, so every field is required, and a node lists the fields that hold defaults in
+`$defaults`). A document's data is `{"tree": …}` and, when it has any, `settings`, `options` and `preamble` in the
+shapes texmodel writes a `Document`'s in.
+"""
+
+import copy
+import dataclasses
+import hashlib
+from collections.abc import Mapping
+from typing import Any, Literal, cast
+
+from texmodel import spec
+from texmodel.body import Comment
+from texmodel.components import AnyValue, Command, Environment, Node, Passthrough
+from texmodel.document import Document as TexDocument
+from texmodel.package import Package
+from texmodel.preamble import PreambleSlots
+
+from ..declaration import Kind, Model
+from ..errors import DeclarationError
+from .envelope import EXTRA_KEYS
+
+type Mode = Literal["validation", "serialization"]
+
+DEFAULTS = "$defaults"  # V24: the fields of a node that hold the package's defaults
+
+
+def stored(validation: dict[str, Any]) -> dict[str, Any]:
+    """The stored schema of an input schema: every property required, `$defaults` limited to the node's own defaulted
+    fields (V27)."""
+    out = copy.deepcopy(validation)
+    for node in (out, *out.get("$defs", {}).values()):
+        properties: dict[str, Any] | None = node.get("properties")
+        if not properties:
+            continue
+        defaulted = sorted(name for name, schema in properties.items() if "default" in schema)
+        node["required"] = sorted(properties)
+        properties[DEFAULTS] = (
+            {"type": "array", "items": {"enum": defaulted}, "uniqueItems": True}
+            if defaulted
+            else {"type": "array", "maxItems": 0}
+        )
+    return out
+
+
+def tree_schema(model: Model, mode: Mode) -> dict[str, Any]:
+    """The JSON Schema of the tree a kind's `model` takes (`validation`) or stores (`serialization`)."""
+    if mode not in ("validation", "serialization"):
+        raise DeclarationError(
+            f"schema mode {mode!r}", code="TP-K008", hint='use "validation" (the input) or "serialization" (the stored)'
+        )
+    validation = spec.json_schema(model)
+    return validation if mode == "validation" else stored(validation)
+
+
+@dataclasses.dataclass(frozen=True)
+class Extras:
+    """What a document carries besides its tree, within what its kind allows: class `options`, `settings` (values set
+    after the package loads) and `preamble` entries."""
+
+    options: tuple[str, ...] = ()
+    settings: tuple[AnyValue, ...] = ()
+    preamble: PreambleSlots = dataclasses.field(default_factory=PreambleSlots)
+
+
+def extras_state(extras: Extras) -> dict[str, Any]:
+    """The keys of a document's data besides `tree`, in texmodel's shapes; empty ones left out."""
+    data = spec.to_dict(TexDocument(options=extras.options, settings=extras.settings, preamble=extras.preamble))
+    return {key: data[key] for key in EXTRA_KEYS if key in data}
+
+
+def extras_from(package: Package, data: Mapping[str, Any]) -> Extras:
+    """The extras `data` describes; raises an `ExceptionGroup` of texmodel `ValidationError` for data the package does
+    not read."""
+    found = spec.from_dict(package, {"type": "Document", **data, "content": []})
+    return Extras(found.options, found.settings, found.preamble)
+
+
+def not_allowed(kind: Kind, extras: Extras) -> list[dict[str, Any]]:
+    """What `extras` holds that `kind` does not allow, as unresolved items (`path`, `reason`, `value`)."""
+    data = extras_state(extras)
+    settable = {c.__name__ for c in kind.settable}
+    entries = {c.__name__ for c in kind.preamble}
+    found = [
+        (f"/settings/{i}", f"{type(v).__name__} is not settable in kind {kind.name}", data["settings"][i])
+        for i, v in enumerate(extras.settings)
+        if type(v).__name__ not in settable
+    ]
+    found += [
+        (f"/options/{i}", f"option {o!r} is not allowed in kind {kind.name}", o)
+        for i, o in enumerate(extras.options)
+        if o not in kind.options
+    ]
+    found += [
+        (
+            f"/preamble/{slot}/{i}",
+            f"{type(item).__name__} is not an allowed preamble entry in kind {kind.name}",
+            data["preamble"][slot][i],
+        )
+        for slot, i, item in extras.preamble.items()
+        if type(item).__name__ not in entries
+    ]
+    return [{"path": path, "reason": reason, "value": value, "schema": {}} for path, reason, value in found]
+
+
+def _closure(defs: Mapping[str, Any], roots: list[str]) -> dict[str, Any]:
+    """The definitions `roots` name and the ones those name, in name order."""
+    found: dict[str, Any] = {}
+    todo = list(roots)
+    while todo:
+        name = todo.pop()
+        if name not in found:
+            found[name] = defs[name]
+            todo += [r.rsplit("/", 1)[1] for r in _refs(defs[name])]
+    return dict(sorted(found.items()))
+
+
+def _refs(node: object) -> list[str]:
+    """Every `$ref` under `node`."""
+    if isinstance(node, dict):
+        found: list[str] = []
+        for key, value in cast("dict[str, object]", node).items():
+            found += [str(value)] if key == "$ref" else _refs(value)
+        return found
+    if isinstance(node, list):
+        return [ref for item in cast("list[object]", node) for ref in _refs(item)]
+    return []
+
+
+def schema(kind: Kind, package: Package, mode: Mode) -> dict[str, Any]:
+    """The JSON Schema of the data of a document of `kind`: its `tree`, and the settings, options and preamble entries
+    the kind allows, read by `package`, the one that renders it."""
+    tree = tree_schema(kind.model, mode)
+    defs: dict[str, Any] = tree.pop("$defs", {})
+    title = str(tree["title"])
+    defs[title] = tree
+    properties: dict[str, Any] = {"tree": {"$ref": f"#/$defs/{title}"}}
+    wanted: list[str] = []
+    if kind.settable:
+        names = [f"{c.__name__}Setting" for c in kind.settable]
+        wanted += names
+        properties["settings"] = {"type": "array", "items": {"oneOf": [{"$ref": f"#/$defs/{n}"} for n in names]}}
+    if kind.options:
+        properties["options"] = {"type": "array", "uniqueItems": True, "items": {"enum": list(kind.options)}}
+    if kind.preamble:
+        names = [f"{c.__name__}Entry" for c in kind.preamble]
+        wanted += names
+        slot = {"type": "array", "items": {"oneOf": [{"$ref": f"#/$defs/{n}"} for n in names]}}
+        properties["preamble"] = {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": dict.fromkeys(("before_class", "before_package", "after_package"), slot),
+        }
+    shared: dict[str, Any] = spec.json_schema(package)["$defs"] if wanted else {}
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": kind.name,
+        "type": "object",
+        "additionalProperties": False,
+        "properties": properties,
+        "required": ["tree"],
+        "$defs": dict(sorted((defs | _closure(shared, wanted)).items())),
+    }
+
+
+def _fields(node: Command | Environment | Passthrough) -> dict[str, Any]:
+    return node.model_dump(mode="json", exclude={"content"})
+
+
+def tree_state(node: Node) -> dict[str, Any]:
+    """The state of a tree: every value written (V21), and for each node the fields that hold the package's defaults in
+    `$defaults` (V24), known from `model_fields_set`, which says what the caller passed (V25)."""
+    if isinstance(node, Comment):
+        return {"type": type(node).__name__} | {f: getattr(node, f) for f in node.__tm_fields__}
+    if isinstance(node, Passthrough):
+        return {"type": "Passthrough"} | _fields(node)
+    fields = _fields(node)
+    out: dict[str, Any] = {"type": type(node).__name__} | fields
+    if defaulted := [name for name in fields if name not in node.model_fields_set]:
+        out[DEFAULTS] = defaulted
+    if isinstance(node, Environment):
+        out["content"] = [tree_state(child) for child in node.content]
+    return out
+
+
+def given(state: dict[str, Any]) -> dict[str, Any]:
+    """`state` as the caller would have passed it: the fields marked as defaults left out, so the model fills them with
+    its current defaults and `model_fields_set` is what the author set (V27)."""
+    out = {k: v for k, v in state.items() if k not in (DEFAULTS, *state.get(DEFAULTS, ()))}
+    if "content" in out:
+        out["content"] = [given(child) for child in out["content"]]
+    return out
+
+
+def tree_from_state(model: Model, state: dict[str, Any]) -> Node:
+    """The tree a stored state describes; raises an `ExceptionGroup` of texmodel `ValidationError` for one that does not
+    fit the model."""
+    return spec.from_dict(model, given(state))
+
+
+def default_paths(node: Node, path: str = "") -> tuple[str, ...]:
+    """The data paths of the fields that hold defaults (`/content/1/accent`), in document order."""
+    if isinstance(node, Comment):
+        return ()
+    own = tuple(f"{path}/{name}" for name in _fields(node) if name not in node.model_fields_set)
+    if isinstance(node, Environment):
+        return own + tuple(
+            p for i, child in enumerate(node.content) for p in default_paths(child, f"{path}/content/{i}")
+        )
+    return own
+
+
+def defaults_table(model: Model) -> dict[str, Any]:
+    """The defaults of the classes a kind's trees are made of, by `Class.field`: what the package would fill in."""
+    validation = spec.json_schema(model)
+    table: dict[str, Any] = {}
+    for node in (validation, *validation.get("$defs", {}).values()):
+        for name, schema in node.get("properties", {}).items():
+            if "default" in schema:
+                table[f"{node['title']}.{name}"] = schema["default"]
+    return dict(sorted(table.items()))
+
+
+def sty_hashes(sty: Mapping[str, str]) -> dict[str, str]:
+    """The `.sty` files the template state records by hash, not by value (D6)."""
+    return {name: hashlib.sha256(text.encode("utf-8")).hexdigest() for name, text in sorted(sty.items())}