pysual 0.1.2__py3-none-any.whl

pysual/__init__.py

@@ -0,0 +1,154 @@
+"""Pysual: typed Python controls with shared desktop and web behavior."""
+
+from .app import App as App, Window as Window
+from ._config import configure as configure
+from ._engine import shutdown as shutdown
+from .runtime import wait as wait, wait_async as wait_async
+from .backends.terminal import terminal as terminal
+
+__version__ = "0.1.2"
+from .controls import (
+    Button as Button,
+    Container as Container,
+    Control as Control,
+    Label as Label,
+)
+from .controls import register_control as register_control
+from .controls import registered_controls as registered_controls
+from .events import (
+    ClickEvent as ClickEvent,
+    ClosingEvent as ClosingEvent,
+    Event as Event,
+    UiEvent as UiEvent,
+)
+from .schema import Dirty as Dirty, prop as prop
+from .behaviors import PressBehavior as PressBehavior
+
+from .widgets import (
+    CheckBox as CheckBox,
+    Slider as Slider,
+    TextBox as TextBox,
+    ScrollArea as ScrollArea,
+    ListView as ListView,
+    Image as Image,
+    SubWindow as SubWindow,
+)
+from .events import (
+    ChangeEvent as ChangeEvent,
+    PointerEvent as PointerEvent,
+    KeyEvent as KeyEvent,
+)
+from .theme import (
+    Theme as Theme,
+    Tokens as Tokens,
+    Style as Style,
+    Rule as Rule,
+    dark as dark,
+    get_theme as get_theme,
+    theme_names as theme_names,
+    light as light,
+    load_theme as load_theme,
+    save_theme as save_theme,
+)
+from .geometry import Rect as Rect
+from .painting import Painter as Painter
+
+from .host import CapabilityError as CapabilityError
+from .host import TextFile as TextFile
+from .host import RenderDiagnostics as RenderDiagnostics
+from .runtime import FrameTiming as FrameTiming
+from .tree import TreeNode as TreeNode, TreeView as TreeView, TreeEvent as TreeEvent
+from .popup import Popup as Popup
+from .charts import LineChart as LineChart, ChartSeries as ChartSeries
+from .data_grid import (
+    DataGrid as DataGrid,
+    GridColumn as GridColumn,
+    GridRow as GridRow,
+    CellValue as CellValue,
+    GridCellEvent as GridCellEvent,
+    GridEditEvent as GridEditEvent,
+)
+from .commands import (
+    MenuItem as MenuItem,
+    MenuGroup as MenuGroup,
+    CommandEvent as CommandEvent,
+)
+from .menus import Menu as Menu, MenuBar as MenuBar
+from .composition import (
+    TabControl as TabControl,
+    TabPage as TabPage,
+    SplitPane as SplitPane,
+)
+from .selection import (
+    Dropdown as Dropdown,
+    ComboBox as ComboBox,
+    Toggle as Toggle,
+    RadioButton as RadioButton,
+    ProgressBar as ProgressBar,
+    Rating as Rating,
+)
+
+from .icons import icon_names as icon_names
+
+from .render_cache import CacheStats as CacheStats
+
+from .editors import NumericInput as NumericInput, ColorPicker as ColorPicker
+
+from .extras import GroupBox as GroupBox, Separator as Separator, Hyperlink as Hyperlink
+from .charts import DonutChart as DonutChart, ChartSlice as ChartSlice
+from .events import DragPayload as DragPayload, DragEvent as DragEvent
+from .host import Viewport as Viewport
+from .inspection import (
+    ControlSnapshot as ControlSnapshot,
+    HandlerSnapshot as HandlerSnapshot,
+    TaskSnapshot as TaskSnapshot,
+)
+
+from .controls import blueprint as blueprint
+from ._blueprint import Blueprint as Blueprint
+
+from .image_resources import image_source as image_source, package_image as package_image
+from .editing import EditorContent as EditorContent, EditorPopup as EditorPopup
+from .editors import NumericEditor as NumericEditor, ColorEditor as ColorEditor
+from .fields import SearchField as SearchField
+from .dates import DatePicker as DatePicker, CalendarEditor as CalendarEditor
+from ._controls.indicators import (
+    RangeSlider as RangeSlider, CircularProgress as CircularProgress,
+)
+from .navigation import (
+    SegmentedControl as SegmentedControl, Breadcrumb as Breadcrumb,
+    BreadcrumbEvent as BreadcrumbEvent, Pagination as Pagination,
+)
+from .cards import ChoiceCard as ChoiceCard, Disclosure as Disclosure
+from .feedback import Badge as Badge, AlertBanner as AlertBanner, Meter as Meter
+
+from ._catalog import install_builtin_controls as _install_builtin_controls
+
+_install_builtin_controls()
+
+# Keep loaded implementation modules out of wildcard imports. Argument
+# processing remains an explicit opt-in through pysual.autoconfig.
+__all__ = (
+    "App", "Window", "configure", "shutdown", "wait", "wait_async", "terminal",
+    "Control", "Container", "Button", "Label", "register_control",
+    "registered_controls", "blueprint", "Blueprint", "Dirty", "prop", "PressBehavior",
+    "CheckBox", "Slider", "TextBox", "ScrollArea", "ListView", "Image",
+    "SubWindow", "Popup", "TreeNode", "TreeView", "TreeEvent",
+    "MenuItem", "MenuGroup", "Menu", "MenuBar", "TabControl", "TabPage",
+    "SplitPane", "Dropdown", "ComboBox", "Toggle", "RadioButton", "ProgressBar", "Rating",
+    "NumericInput", "ColorPicker", "GroupBox", "Separator", "Hyperlink",
+    "EditorContent", "EditorPopup", "NumericEditor", "ColorEditor",
+    "SearchField", "DatePicker", "CalendarEditor",
+    "RangeSlider", "CircularProgress", "SegmentedControl", "Breadcrumb",
+    "BreadcrumbEvent", "Pagination",
+    "ChoiceCard", "Disclosure", "Badge", "AlertBanner", "Meter",
+    "LineChart", "ChartSeries", "DonutChart", "ChartSlice", "DataGrid",
+    "GridColumn", "GridRow", "CellValue", "GridCellEvent", "GridEditEvent",
+    "Event", "UiEvent", "ClickEvent", "ClosingEvent", "ChangeEvent",
+    "PointerEvent", "KeyEvent", "CommandEvent", "DragPayload", "DragEvent",
+    "Theme", "Tokens", "Style", "Rule", "dark", "light", "get_theme",
+    "theme_names", "load_theme", "save_theme", "icon_names",
+    "Rect", "Painter", "CapabilityError", "TextFile", "Viewport",
+    "FrameTiming", "RenderDiagnostics", "CacheStats", "ControlSnapshot", "HandlerSnapshot",
+    "TaskSnapshot", "image_source", "package_image",
+)

pysual/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m pysual` builds or runs an application; see `pysual --help`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pysual/_blueprint.py

@@ -0,0 +1,102 @@
+"""Immutable construction descriptors; live controls remain in their ordinary tree."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+import keyword
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, Generic, Mapping, TypeVar, overload
+
+from .errors import BindingError, LifecycleError
+
+if TYPE_CHECKING:
+    from .controls import Container, Control
+
+C = TypeVar("C", bound="Control")
+
+
+@dataclass(frozen=True, eq=False)
+class Blueprint(Generic[C]):
+    """A typed per-instance declaration, created with pysual.blueprint()."""
+
+    control_type: type[C]
+    _properties: tuple[tuple[str, object], ...]
+    parent_name: str | None = None
+    _name: str | None = field(default=None, init=False, repr=False)
+
+    @property
+    def properties(self) -> Mapping[str, object]:
+        return MappingProxyType(dict(self._properties))
+
+    def under(self, parent_name: str) -> Blueprint[C]:
+        """Use a Container declaration in the same owner as the visual parent."""
+        if (
+            not isinstance(parent_name, str)
+            or not parent_name.isidentifier()
+            or parent_name.startswith("_")
+            or keyword.iskeyword(parent_name)
+        ):
+            raise BindingError("Blueprint parent must be a public declaration name")
+        return replace(self, parent_name=parent_name)
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        if self._name is not None:
+            raise BindingError("Create a fresh blueprint for each class declaration")
+        if (
+            not name.isidentifier()
+            or name.startswith("_")
+            or keyword.iskeyword(name)
+            or name == owner.__name__
+            or any(
+                name in vars(base) and not isinstance(vars(base)[name], Blueprint)
+                for base in owner.__mro__[1:]
+            )
+        ):
+            raise BindingError(f"Blueprint {name!r} collides with a framework member")
+        object.__setattr__(self, "_name", name)
+
+    @overload
+    def __get__(self, instance: None, owner: type | None = None) -> Blueprint[C]: ...
+
+    @overload
+    def __get__(self, instance: Container, owner: type | None = None) -> C: ...
+
+    def __get__(
+        self, instance: Container | None, owner: type | None = None
+    ) -> Blueprint[C] | C:
+        if instance is None:
+            return self
+        from ._engine import call, is_ui_thread
+
+        if not is_ui_thread():
+            return call(self.__get__, instance, owner)
+        instance._check_live()
+        assert self._name is not None
+        value = vars(instance).get(self._name)
+        if not isinstance(value, self.control_type):
+            raise LifecycleError(
+                f"Blueprint {self._name!r} is available after construction completes"
+            )
+        return value
+
+    def __set__(self, instance: Container, value: C) -> None:
+        if not isinstance(value, self.control_type):
+            raise TypeError(
+                f"Blueprint {self._name!r} requires {self.control_type.__name__}"
+            )
+        assert self._name is not None
+        vars(instance)[self._name] = value
+
+
+def declarations(owner_type: type) -> dict[str, Blueprint[Any]]:
+    """Resolve inherited declarations without evaluating descriptors or user code."""
+    result: dict[str, Blueprint[Any]] = {}
+    for base in reversed(owner_type.__mro__):
+        for name, value in vars(base).items():
+            if isinstance(value, Blueprint):
+                result[name] = value
+            elif name in result:
+                raise BindingError(
+                    f"Override inherited blueprint {name!r} with a blueprint"
+                )
+    return result

pysual/_build_assets.py

@@ -0,0 +1,53 @@
+"""Validate application assets without traversing filesystem redirects."""
+
+from pathlib import Path
+import os
+import stat
+
+
+def _checked_path(root: Path, path: Path) -> tuple[os.stat_result, Path]:
+    # Check every component: an explicitly included file can itself have a
+    # junction/symlink parent. st_file_attributes works on Python 3.11 too.
+    current = root
+    for part in path.relative_to(root).parts:
+        current /= part
+        info = current.lstat()
+        if stat.S_ISLNK(info.st_mode) or getattr(info, "st_file_attributes", 0) & 0x400:
+            raise ValueError(f"Included symlinks and reparse points are unsupported: {current}")
+    resolved = path.resolve(strict=True)
+    if not resolved.is_relative_to(root):
+        raise ValueError(f"Included files must be inside the application directory: {path}")
+    return path.lstat(), resolved
+
+
+def include_files(root: Path, item: str | Path, output: Path) -> tuple[Path, list[Path]]:
+    """Return a validated include root and its regular files, in stable order.
+
+    Inputs must remain unchanged while a build runs. This is a packaging
+    boundary, not a sandbox against concurrent hostile filesystem mutation.
+    """
+    relative = Path(item)
+    if relative.is_absolute() or ".." in relative.parts:
+        raise ValueError("Included files must be inside the application directory, using relative paths")
+    candidate = root / relative
+    try:
+        info, resolved = _checked_path(root, candidate)
+        # Windows accepts aliases such as a trailing dot or an 8.3 short name.
+        # Compare canonical paths only after checking lexical redirect parents.
+        if output == resolved or stat.S_ISDIR(info.st_mode) and output.is_relative_to(resolved):
+            raise ValueError("The generated output cannot be inside an included path")
+        pending: list[Path] = [candidate]
+        files: list[Path] = []
+        while pending:
+            path = pending.pop()
+            info, _ = _checked_path(root, path)
+            if stat.S_ISDIR(info.st_mode):
+                # Validate before descending, so junction cycles cannot recurse.
+                pending.extend(reversed(sorted(path.iterdir())))
+            elif stat.S_ISREG(info.st_mode):
+                files.append(path)
+            else:
+                raise ValueError(f"Included path must be a regular file or directory: {path}")
+    except OSError as error:
+        raise ValueError(f"Cannot read included path {item}: {error}") from error
+    return candidate, files

pysual/_catalog.py

@@ -0,0 +1,91 @@
+"""Built-in catalog metadata and installation, independent of implementation files.
+
+New entries default to constructor/create-only registration. The historical
+factory aliases are explicit compatibility choices, not an ever-growing set of
+reserved Container members. Public Python exports remain explicit for typing.
+"""
+
+from dataclasses import dataclass
+
+from .controls import Button, Container, Control, Label
+from .widgets import CheckBox, Image, ListView, ScrollArea, Slider, SubWindow, TextBox
+from .selection import ComboBox, Dropdown, ProgressBar, RadioButton, Rating, Toggle
+from .composition import SplitPane, TabControl, TabPage
+from .charts import DonutChart, LineChart
+from .data_grid import DataGrid
+from .editors import ColorPicker, NumericInput
+from .fields import SearchField
+from .dates import DatePicker
+from ._controls.indicators import RangeSlider, CircularProgress
+from .navigation import SegmentedControl, Breadcrumb, Pagination
+from .cards import ChoiceCard, Disclosure
+from .feedback import Badge, AlertBanner, Meter
+from .extras import GroupBox, Hyperlink, Separator
+from .menus import Menu, MenuBar
+from .popup import Popup
+from .tree import TreeView
+from ._registry import register_control
+
+
+@dataclass(frozen=True)
+class BuiltinControl:
+    name: str
+    control_type: type[Control]
+    family: str
+    legacy_factory: bool = False
+    authorable: bool = True
+
+
+BUILTIN_CONTROLS = (
+    BuiltinControl("label", Label, "basic", legacy_factory=True),
+    BuiltinControl("button", Button, "basic", legacy_factory=True),
+    BuiltinControl("panel", Container, "layout", legacy_factory=True),
+    BuiltinControl("check_box", CheckBox, "actions", legacy_factory=True),
+    BuiltinControl("slider", Slider, "ranges", legacy_factory=True),
+    BuiltinControl("text_box", TextBox, "text", legacy_factory=True),
+    BuiltinControl("scroll_area", ScrollArea, "viewports", legacy_factory=True),
+    BuiltinControl("list_view", ListView, "collections", legacy_factory=True),
+    BuiltinControl("image", Image, "media", legacy_factory=True),
+    BuiltinControl("sub_window", SubWindow, "windows", legacy_factory=True),
+    BuiltinControl("tree_view", TreeView, "collections", legacy_factory=True),
+    BuiltinControl("popup", Popup, "overlays", legacy_factory=True),
+    BuiltinControl("line_chart", LineChart, "charts", legacy_factory=True),
+    BuiltinControl("donut_chart", DonutChart, "charts", legacy_factory=True),
+    BuiltinControl("data_grid", DataGrid, "collections", legacy_factory=True),
+    BuiltinControl("menu", Menu, "commands", legacy_factory=True),
+    BuiltinControl("menu_bar", MenuBar, "commands", legacy_factory=True),
+    BuiltinControl("tab_page", TabPage, "layout", legacy_factory=True),
+    BuiltinControl("tab_control", TabControl, "layout", legacy_factory=True),
+    BuiltinControl("split_pane", SplitPane, "layout", legacy_factory=True),
+    BuiltinControl("toggle", Toggle, "actions", legacy_factory=True),
+    BuiltinControl("radio_button", RadioButton, "actions", legacy_factory=True),
+    BuiltinControl("progress_bar", ProgressBar, "ranges", legacy_factory=True),
+    BuiltinControl("dropdown", Dropdown, "choices", legacy_factory=True),
+    BuiltinControl("combo_box", ComboBox, "choices", legacy_factory=True),
+    BuiltinControl("numeric_input", NumericInput, "editors", legacy_factory=True),
+    BuiltinControl("color_picker", ColorPicker, "editors", legacy_factory=True),
+    BuiltinControl("group_box", GroupBox, "layout", legacy_factory=True),
+    BuiltinControl("separator", Separator, "layout", legacy_factory=True),
+    BuiltinControl("hyperlink", Hyperlink, "actions", legacy_factory=True),
+    BuiltinControl("rating", Rating, "ranges"),
+    BuiltinControl("search_field", SearchField, "text"),
+    BuiltinControl("date_picker", DatePicker, "dates"),
+    BuiltinControl("range_slider", RangeSlider, "ranges"),
+    BuiltinControl("circular_progress", CircularProgress, "ranges"),
+    BuiltinControl("segmented_control", SegmentedControl, "actions"),
+    BuiltinControl("breadcrumb", Breadcrumb, "navigation"),
+    BuiltinControl("pagination", Pagination, "navigation"),
+    BuiltinControl("choice_card", ChoiceCard, "actions"),
+    BuiltinControl("disclosure", Disclosure, "layout"),
+    BuiltinControl("badge", Badge, "feedback"),
+    BuiltinControl("alert_banner", AlertBanner, "feedback"),
+    BuiltinControl("meter", Meter, "feedback"),
+)
+
+
+def install_builtin_controls() -> None:
+    for entry in BUILTIN_CONTROLS:
+        register_control(
+            entry.control_type, name=entry.name, authorable=entry.authorable,
+            factory=entry.legacy_factory,
+        )

pysual/_config.py

@@ -0,0 +1,236 @@
+"""Validated startup defaults; external configuration is explicitly opt-in."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import os
+import sys
+from threading import RLock
+from typing import TYPE_CHECKING, cast
+
+from .backends import BACKEND_NAMES, BackendName
+from .errors import LifecycleError
+
+if TYPE_CHECKING:
+    from .host import Host
+
+
+@dataclass(frozen=True)
+class Settings:
+    backend: str | None = None
+    terminal_renderer: str | None = None
+    theme: str | None = None
+    ui_scale: float | None = None
+
+
+@dataclass(frozen=True)
+class Option:
+    field: str
+    flag: str
+    environment: str
+    description: str
+
+
+OPTIONS = (
+    Option(
+        "backend",
+        "--backend",
+        "PYSUAL_BACKEND",
+        "UI backend: " + ", ".join(BACKEND_NAMES),
+    ),
+    Option(
+        "terminal_renderer",
+        "--terminal",
+        "PYSUAL_TERMINAL",
+        "Terminal renderer: auto, c, or python",
+    ),
+    Option(
+        "theme",
+        "--pysual-theme",
+        "PYSUAL_THEME",
+        "Default window theme (catalog name)",
+    ),
+    Option(
+        "ui_scale",
+        "--pysual-scale",
+        "PYSUAL_SCALE",
+        "Default window scale (finite number, at least 0.25)",
+    ),
+)
+_BY_FLAG = {option.flag: option for option in OPTIONS}
+_defaults: dict[str, object] = {}
+_environment: dict[str, object] = {}
+_command_line: dict[str, object] = {}
+_activated = False
+_frozen: Settings | None = None
+_lock = RLock()
+
+
+def _validate(name: str, value: object) -> object:
+    if name == "backend":
+        if value is not None and (
+            not isinstance(value, str) or value not in BACKEND_NAMES
+        ):
+            raise ValueError("backend must be one of: " + ", ".join(BACKEND_NAMES))
+    elif name == "terminal_renderer":
+        if value is not None and value not in ("auto", "c", "python"):
+            raise ValueError("terminal renderer must be auto, c, or python")
+    elif name == "theme":
+        from .theme import theme_names
+
+        if value is not None and value not in theme_names():
+            raise ValueError("theme must be a built-in theme name")
+    elif name == "ui_scale":
+        if value is not None:
+            if type(value) is int or type(value) is float:
+                if not math.isfinite(value) or value < 0.25:
+                    raise ValueError("ui_scale must be a finite number of at least 0.25")
+            else:
+                raise ValueError("ui_scale must be a finite number of at least 0.25")
+    else:
+        raise TypeError(f"Unknown startup setting {name!r}")
+    return value
+
+
+def configure(
+    *,
+    backend: str | None = None,
+    terminal_renderer: str | None = None,
+    theme: str | None = None,
+    ui_scale: float | None = None,
+) -> Settings:
+    """Set startup defaults before constructing UI objects; never read argv/env.
+
+    Opted-in command-line values override these defaults. Theme and scale defaults
+    do not replace an explicit window constructor argument.
+    """
+    values = {name: value for name, value in locals().items() if value is not None}
+    values = {name: _validate(name, value) for name, value in values.items()}
+    with _lock:
+        if _frozen is not None:
+            raise LifecycleError("Configure Pysual before constructing UI objects")
+        _defaults.update(values)
+        return current()
+
+
+def current() -> Settings:
+    with _lock:
+        if _frozen is not None:
+            return _frozen
+        values = {**_environment, **_defaults, **_command_line}
+        return Settings(
+            backend=cast(str | None, values.get("backend")),
+            terminal_renderer=cast(str | None, values.get("terminal_renderer")),
+            theme=cast(str | None, values.get("theme")),
+            ui_scale=cast(float | None, values.get("ui_scale")),
+        )
+
+
+def freeze() -> Settings:
+    global _frozen
+    with _lock:
+        if _frozen is None:
+            _frozen = current()
+        return _frozen
+
+
+def window_defaults() -> dict[str, object]:
+    settings = current()
+    defaults: dict[str, object] = {}
+    if settings.ui_scale is not None:
+        defaults["ui_scale"] = settings.ui_scale
+    if settings.theme is not None:
+        from .theme import get_theme
+
+        defaults["theme"] = get_theme(settings.theme)
+    return defaults
+
+
+def _convert(option: Option, value: str) -> object:
+    if option.field == "ui_scale":
+        try:
+            parsed = float(value)
+        except (ValueError, TypeError):
+            raise ValueError(f"{option.flag} requires a number") from None
+        return _validate(option.field, parsed)
+    return _validate(option.field, value)
+
+
+def activate() -> None:
+    """Consume only recognized arguments, transactionally and once per process."""
+    global _activated
+    with _lock:
+        if _activated:
+            return
+        if _frozen is not None:
+            raise LifecycleError(
+                "Import pysual.autoconfig before constructing UI objects"
+            )
+        arguments = list(sys.argv)
+        remaining = arguments[:1]
+        selected: dict[str, object] = {}
+        help_requested = False
+        index = 1
+        while index < len(arguments):
+            token = arguments[index]
+            if token == "--":
+                remaining.extend(arguments[index:])
+                break
+            flag, separator, value = token.partition("=")
+            if flag == "--pysual-help":
+                if separator:
+                    raise ValueError("--pysual-help does not take a value")
+                help_requested = True
+                index += 1
+                continue
+            option = _BY_FLAG.get(flag)
+            if option is None:
+                if flag.startswith("--pysual-"):
+                    raise ValueError(
+                        f"Unknown Pysual option {flag!r}; use --pysual-help"
+                    )
+                remaining.append(token)
+                index += 1
+                continue
+            if option.field in selected:
+                raise ValueError(f"Repeated Pysual option {flag}")
+            if not separator:
+                index += 1
+                if index >= len(arguments) or arguments[index].startswith("--"):
+                    raise ValueError(f"{flag} requires a value")
+                value = arguments[index]
+            if not value:
+                raise ValueError(f"{flag} requires a value")
+            selected[option.field] = _convert(option, value)
+            index += 1
+        environment = {
+            option.field: _convert(option, os.environ[option.environment])
+            for option in OPTIONS
+            if option.environment in os.environ
+            and option.field not in selected
+            and option.field not in _defaults
+        }
+        if help_requested:
+            print("Pysual options (opt in with 'from pysual import autoconfig'):")
+            for option in OPTIONS:
+                print(f"  {option.flag} VALUE  {option.description}")
+            print("  --pysual-help  Show this help; application --help is untouched")
+            raise SystemExit(0)
+        _environment.update(environment)
+        _command_line.update(selected)
+        sys.argv[:] = remaining
+        _activated = True
+
+
+def resolved_backend(
+    preference: Host | BackendName | None = None,
+) -> Host | BackendName | None:
+    """CLI overrides a named preference; concrete test Hosts remain explicit."""
+    if preference is not None and not isinstance(preference, str):
+        return preference
+    with _lock:
+        return cast(
+            BackendName | None,
+            _command_line.get("backend") or preference or current().backend,
+        )

pysual/_controls/__init__.py

@@ -0,0 +1,5 @@
+"""Focused control implementations; public modules provide stable imports.
+
+New families belong here or in an existing focused module. Registration is
+owned by the built-in catalog, not implementation-module side effects.
+"""