carterkit 0.3.1__tar.gz → 0.4.0__tar.gz

{carterkit-0.3.1 → carterkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.3.1
+Version: 0.4.0
 Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
 Author: Carter Beaudoin
 License-Expression: MIT
@@ -51,25 +51,70 @@ carterkit.examples("button")    # documented example snippets
 
 ## Build a layout
 
-The fluent `Layout` builder composes **typed builders** (`build.<control>`) and
-**binding helpers** (`bind`) — all generated from / shaped by the bundled docs, so
-unknown control types and bad enum values raise instead of silently shipping a broken
-layout:
+Controls are **methods on the layout**, ids are positional, tabs and groups are context
+managers, and bindings fold into kwargs. Each control method returns a **handle** you can
+use as a binding target or patch later. Unknown control types and bad enum values raise
+instead of silently shipping a broken layout:
 
 ```python
-from carterkit import Layout, build, bind
-
-lay = (Layout("Dashboard", columns=4, rows=4)
-       .connect("ws://192.168.1.50:8765", channel="home")
-       .tab("Main", icon="gauge")
-       .add(build.gauge(id="cpu", label="CPU", min=0, max=100,
-                        sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
-            default_span=[2, 2])
-       .add(build.button(id="refresh", label="Refresh", action=bind.action("refresh"))))
-
-print(lay.findings())    # schema + grid + binding lint against the bundled catalog
-help(build.gauge)        # ← prints the gauge documentation, straight from the docs
-layout = lay.layout      # the composed dict, ready to push/save
+from carterkit import Layout
+
+with Layout("Dashboard", cols=4, rows=4) as ui:
+    ui.connect("ws://192.168.1.50:8765", channel="home")
+    with ui.tab("Main", icon="gauge"):
+        cpu = ui.gauge("cpu", label="CPU", min=0, max=100, span=(2, 2),
+                       listen="cpu", when={"msg_type": "metrics"})
+        ui.status_light("warn", visible=cpu > 90)      # handle → visibility condition
+        ui.button("refresh", label="Refresh", send="refresh", request=True)
+
+print(ui.findings())        # schema + grid + binding lint against the bundled catalog
+ui.save("dashboard.json")   # the composed layout, ready to push/load
+```
+
+Binding sugar: `listen=`/`when=`/`event=` build a `sync`, and `send=`/`request=`/`payload=`
+build an `action`; pass `sync=[...]`/`action={...}` (via `carterkit.bind`) for anything
+fancier. A handle comparison (`cpu > 90`) becomes a real visibility condition; `==`/`!=`
+stay normal Python, so use `.eq()`/`.neq()`. `help(carterkit.build.gauge)` prints any
+control's documentation, straight from the bundled docs.
+
+**Prefer a declarative style?** A class veneer compiles to the *same* layout — ids come
+from attribute names, tabs/groups are nested classes (great for fixed dashboards; the flat
+builder reads better for generated ones):
+
+```python
+from carterkit.declare import Screen, Tab, Connect, Gauge, Button, StatusLight
+
+class Dashboard(Screen, cols=4, rows=4):
+    relay = Connect("ws://192.168.1.50:8765", channel="home")
+    class Main(Tab, icon="gauge"):
+        cpu  = Gauge(label="CPU", min=0, max=100, span=(2, 2), listen="cpu")
+        warn = StatusLight(visible=cpu > 90)
+        refresh = Button(label="Refresh", send="refresh", request=True)
+
+Dashboard.save("dashboard.json")
+```
+
+### Dynamic groups
+
+Generate controls in `for`/`if` loops (auto-placed in the group's own grid), or mark a
+group `dynamic="event"` and replace its children live at runtime. Build that replacement
+payload with `Fragment`, then lint it against the broadcasts your server actually emits —
+catching events that never arrive, missing `children` arrays, and off-grid/invalid
+injected controls before they ship:
+
+```python
+import carterkit
+from carterkit import Fragment
+
+ui.group("Now Playing", span=(3, 4), cols=4, rows=3, dynamic="player_state")
+
+frag = Fragment(cols=4, rows=3)
+frag.label("title", text="Song", span=(1, 4))
+frag.button("play", label="Play", send="play")
+# your server broadcasts frag.payload("player_state") == {"msg_type": ..., "children": [...]}
+
+print(carterkit.format_findings(
+    carterkit.lint_dynamic_traffic(ui.layout, [frag.payload("player_state")])))
 ```
 
 Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`

carterkit-0.4.0/README.md

@@ -0,0 +1,141 @@
+# carterkit
+
+[![PyPI](https://img.shields.io/pypi/v/carterkit.svg)](https://pypi.org/project/carterkit/)
+[![Downloads](https://static.pepy.tech/badge/carterkit)](https://pepy.tech/project/carterkit)
+[![Python versions](https://img.shields.io/pypi/pyversions/carterkit.svg)](https://pypi.org/project/carterkit/)
+
+Build and drive [CAR-TER](https://carterbeaudoin.net/CAR-TER) layouts from Python.
+
+**The control docs are the library.** Every control's schema, fields, and examples
+are parsed at runtime from the ControlDocs markdown bundled inside the package — the
+exact same docs the CAR-TER app renders — so the catalog never drifts from the
+definitions.
+
+```bash
+pip install carterkit
+```
+
+## Explore the controls (zero config)
+
+```python
+import carterkit
+
+carterkit.controls()            # {type: schema} for every placeable control
+carterkit.doc("gauge")          # full parsed doc: fields, themeFields, examples
+print(carterkit.doc_markdown("gauge"))   # the rendered documentation prose
+carterkit.examples("button")    # documented example snippets
+```
+
+## Build a layout
+
+Controls are **methods on the layout**, ids are positional, tabs and groups are context
+managers, and bindings fold into kwargs. Each control method returns a **handle** you can
+use as a binding target or patch later. Unknown control types and bad enum values raise
+instead of silently shipping a broken layout:
+
+```python
+from carterkit import Layout
+
+with Layout("Dashboard", cols=4, rows=4) as ui:
+    ui.connect("ws://192.168.1.50:8765", channel="home")
+    with ui.tab("Main", icon="gauge"):
+        cpu = ui.gauge("cpu", label="CPU", min=0, max=100, span=(2, 2),
+                       listen="cpu", when={"msg_type": "metrics"})
+        ui.status_light("warn", visible=cpu > 90)      # handle → visibility condition
+        ui.button("refresh", label="Refresh", send="refresh", request=True)
+
+print(ui.findings())        # schema + grid + binding lint against the bundled catalog
+ui.save("dashboard.json")   # the composed layout, ready to push/load
+```
+
+Binding sugar: `listen=`/`when=`/`event=` build a `sync`, and `send=`/`request=`/`payload=`
+build an `action`; pass `sync=[...]`/`action={...}` (via `carterkit.bind`) for anything
+fancier. A handle comparison (`cpu > 90`) becomes a real visibility condition; `==`/`!=`
+stay normal Python, so use `.eq()`/`.neq()`. `help(carterkit.build.gauge)` prints any
+control's documentation, straight from the bundled docs.
+
+**Prefer a declarative style?** A class veneer compiles to the *same* layout — ids come
+from attribute names, tabs/groups are nested classes (great for fixed dashboards; the flat
+builder reads better for generated ones):
+
+```python
+from carterkit.declare import Screen, Tab, Connect, Gauge, Button, StatusLight
+
+class Dashboard(Screen, cols=4, rows=4):
+    relay = Connect("ws://192.168.1.50:8765", channel="home")
+    class Main(Tab, icon="gauge"):
+        cpu  = Gauge(label="CPU", min=0, max=100, span=(2, 2), listen="cpu")
+        warn = StatusLight(visible=cpu > 90)
+        refresh = Button(label="Refresh", send="refresh", request=True)
+
+Dashboard.save("dashboard.json")
+```
+
+### Dynamic groups
+
+Generate controls in `for`/`if` loops (auto-placed in the group's own grid), or mark a
+group `dynamic="event"` and replace its children live at runtime. Build that replacement
+payload with `Fragment`, then lint it against the broadcasts your server actually emits —
+catching events that never arrive, missing `children` arrays, and off-grid/invalid
+injected controls before they ship:
+
+```python
+import carterkit
+from carterkit import Fragment
+
+ui.group("Now Playing", span=(3, 4), cols=4, rows=3, dynamic="player_state")
+
+frag = Fragment(cols=4, rows=3)
+frag.label("title", text="Song", span=(1, 4))
+frag.button("play", label="Play", send="play")
+# your server broadcasts frag.payload("player_state") == {"msg_type": ..., "children": [...]}
+
+print(carterkit.format_findings(
+    carterkit.lint_dynamic_traffic(ui.layout, [frag.payload("player_state")])))
+```
+
+Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`
+over a held draft; `lay.buffer` exposes it.
+
+`infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
+`codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
+`theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
+
+## CLI
+
+```bash
+carterkit catalog                 # list every control type
+carterkit doc gauge               # print a control's documentation
+carterkit examples button         # list a control's examples (--name to print one)
+carterkit validate layout.json    # lint a layout (exit 1 on errors)
+carterkit gen layout.json         # generate a MeshSocket service stub
+carterkit relay --port 8765       # run the bundled MeshSocket relay
+```
+
+## Drive a device
+
+```python
+import asyncio
+from carterkit import CarterClient
+
+async def main():
+    async with CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                            channel="home", role="device", name="my-hub") as c:
+        c.on("toggle", lambda d: {"ok": True, **d})
+        await c.broadcast("reading", {"temp_c": 21.4})
+        await asyncio.sleep(60)
+    # leaving the `async with` disconnects automatically
+
+asyncio.run(main())
+```
+
+End-to-end encryption (ChaCha20-Poly1305 + per-session salt) is transparent when you
+pass an `e2ee_key`. Send a push to every device on a Connect+ account with
+`CarterClient.notify(...)` or the stdlib-only `carterkit.notify_http(...)`.
+
+## Built on
+
+[`meshsocket`](https://pypi.org/project/meshsocket/) — the WebSocket mesh transport.
+
+The ControlDocs are vendored from the CAR-TER app repo; refresh them with
+`scripts/sync-controldocs.sh`.

{carterkit-0.3.1 → carterkit-0.4.0}/carterkit/__init__.py

@@ -7,21 +7,24 @@ renders. So the docs never drift from the definitions; they are one and the same
 
 Quick map:
   - ``controls()`` / ``doc()`` / ``examples()`` — the docs-as-catalog surface
+  - ``Layout`` / ``Fragment`` — the flat builder: controls as methods, live handles,
+    context-manager tabs/groups (``declare.Screen`` is the declarative-class veneer)
   - ``LayoutBuffer`` — incrementally build a layout (auto-placement, dedupe)
   - ``validate_layout()`` — schema + grid lint against the bundled catalog
+  - ``lint_dynamic_traffic()`` — check ``dynamic=`` groups against observed broadcasts
   - ``infer`` / ``codegen`` / ``theming`` / ``tune`` — generate layouts, servers, themes
   - ``CarterClient`` / ``notify_http`` — connect over MeshSocket, push, send alerts
 """
 from importlib.resources import files
 from pathlib import Path
 
-from . import catalog, grid, codegen, infer, theming, tune
+from . import catalog, grid, codegen, infer, theming, tune, dynamic
 from .buffer import LayoutBuffer, BufferError
 from .validate import validate_layout as _validate_layout, format_findings
 from .client import CarterClient, notify_http, CarterNotifyError
 from . import bind
 from .controls import build, control
-from .layout import Layout
+from .layout import Layout, Fragment, Control, Condition
 
 try:
     from importlib.metadata import PackageNotFoundError, version as _pkg_version
@@ -66,12 +69,18 @@ def validate_layout(layout: dict, catalog_: dict = None) -> list:
     return _validate_layout(layout, catalog_ if catalog_ is not None else controls(include_theme=True))
 
 
+def lint_dynamic_traffic(layout: dict, observed, catalog_: dict = None) -> list:
+    """Lint a layout's `dynamic=` groups against observed broadcast payloads. Returns
+    `validate`-style findings (see `dynamic.lint_dynamic_traffic`)."""
+    return dynamic.lint_dynamic_traffic(layout, observed, catalog=catalog_)
+
+
 __all__ = [
     "__version__", "PROTOCOL_VERSION",
     "CarterClient", "notify_http", "CarterNotifyError",
     "LayoutBuffer", "BufferError",
     "controls", "doc", "doc_markdown", "examples", "validate_layout",
-    "format_findings", "controldocs_dir",
-    "build", "control", "bind", "Layout",
-    "catalog", "grid", "codegen", "infer", "theming", "tune",
+    "lint_dynamic_traffic", "format_findings", "controldocs_dir",
+    "build", "control", "bind", "Layout", "Fragment", "Control", "Condition",
+    "catalog", "grid", "codegen", "infer", "theming", "tune", "dynamic",
 ]

{carterkit-0.3.1 → carterkit-0.4.0}/carterkit/controldocs/index.md

@@ -133,9 +133,9 @@ Tap any node in the graph to explore the full documentation for each control typ
 
 1. **Explore the docs** — tap nodes in the graph to learn about each control
 2. **Write a layout** — create a JSON file following the [[layout-config]] schema
-3. **Run a server** — start a MeshSocket server to handle events
+3. **Run a server** — drive your layout from Python with `pip install carterkit`, or
+   speak the MeshSocket protocol directly from any language
 4. **Connect** — load your layout and watch it come alive
 
-The full MeshSocket server implementation and protocol documentation is available on GitHub:
-
-[github.com/carterbeaudoin/MeshSocket](https://github.com/carterbeaudoin/MeshSocket)
+Full developer docs — building servers, the wire protocol, and the `carterkit`
+library — live at **carterbeaudoin.net/CAR-TER**.

carterkit-0.4.0/carterkit/declare.py

@@ -0,0 +1,280 @@
+"""Declarative layouts — a class veneer over the flat builder.
+
+For static, hand-written dashboards this reads like a schema: a control's id is its
+attribute name, tabs and groups are nested classes, and cross-control visibility falls
+out of comparing handles. It compiles to exactly the same `Layout`/`LayoutBuffer` the
+flat builder uses (so `.layout` is an ordinary layout dict) — pick whichever front door
+fits: generated/dynamic UIs read better flat, fixed ones read better here.
+
+    from carterkit.declare import Screen, Tab, Group, Connect, Ref, Gauge, Button, Slider, StatusLight
+
+    class Bench(Screen, cols=4, rows=4):
+        relay = Connect("ws://192.168.1.50:8765", channel="lab")
+
+        class Main(Tab, icon="gauge"):
+            cpu  = Gauge(label="CPU", min=0, max=100, span=(2, 2),
+                         listen="cpu", when={"msg_type": "metrics"})
+            warn = StatusLight(visible=cpu > 90)          # handle -> visibility cond
+            refresh = Button(label="Refresh", send="refresh", request=True)
+
+            class Motors(Group, span=(2, 2), cols=2, rows=2):
+                m0 = Slider(min=0, max=255)
+                m1 = Slider(min=0, max=255)
+
+    layout = Bench.layout          # the dict
+    Bench.save("bench.json")
+
+Control classes (`Gauge`, `Button`, `StatusLight`, `ColorPicker`, …) are generated from
+the bundled catalog: a PascalCase name maps to its control type, so `from
+carterkit.declare import *` (or attribute access) exposes one per placeable control.
+Kwargs are the same sugar the flat builder takes (`listen=/when=/send=/request=/span=/
+visible=`). For a reference to a control by literal id (forward refs, other tabs) use
+`Ref("id") > 90`. `==`/`!=` keep normal Python semantics — use `.eq()`/`.neq()`.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from . import controls as _controls
+from .layout import Layout
+
+
+class DeclareError(Exception):
+    """Raised when a declarative Screen is shaped in a way that can't compile."""
+
+
+# ─── references & conditions ─────────────────────────────────────────────────
+class _Cmp:
+    """A pending visibility condition: a handle/Ref compared to a value, resolved to
+    `{when, operator, value}` once attribute-name ids are known."""
+
+    def __init__(self, target, op: str, value):
+        self.target, self.op, self.value = target, op, value
+
+    def resolve(self, idmap: dict) -> dict:
+        if isinstance(self.target, Ref):
+            when = self.target.id
+        else:
+            when = idmap.get(id(self.target))
+            if when is None:
+                raise DeclareError(
+                    "a visibility condition references a control that isn't a named "
+                    "attribute in this Screen — use Ref('id') to point at it by id")
+        return {"when": when, "operator": self.op, "value": self.value}
+
+
+class _Comparable:
+    def __gt__(self, o): return _Cmp(self, "gt", o)
+    def __ge__(self, o): return _Cmp(self, "gte", o)
+    def __lt__(self, o): return _Cmp(self, "lt", o)
+    def __le__(self, o): return _Cmp(self, "lte", o)
+    def eq(self, o): return _Cmp(self, "eq", o)
+    def neq(self, o): return _Cmp(self, "neq", o)
+
+
+class Ref(_Comparable):
+    """Reference another control by literal id, for visibility conditions:
+    ``hidden = Label(visible=Ref("power").eq(True))``."""
+
+    def __init__(self, id: str):
+        self.id = id
+
+
+class Connect:
+    """A connection declaration: ``relay = Connect(url, channel=..., role=..., token=...)``."""
+
+    def __init__(self, url: str, **identity):
+        self.url, self.identity = url, identity
+
+
+# ─── control specs ───────────────────────────────────────────────────────────
+class _Spec(_Comparable):
+    """A deferred control: its catalog `_ctype` plus the kwargs to build it. The id is
+    filled in from the attribute name at compile time."""
+
+    _ctype: str = ""
+
+    def __init__(self, **kwargs):
+        self._kwargs = kwargs
+
+
+@lru_cache(maxsize=None)
+def _spec_class(ctype: str, clsname: str) -> type:
+    return type(clsname, (_Spec,), {"_ctype": ctype,
+                                    "__doc__": f"Declarative {ctype} control."})
+
+
+@lru_cache(maxsize=1)
+def _catalog() -> dict:
+    from . import controldocs_dir
+    from . import catalog as _catmod
+    return _catmod.build_catalog(controldocs_dir())
+
+
+def _type_for(clsname: str):
+    """PascalCase class name -> catalog control type, or None if not a control."""
+    if not clsname[:1].isupper():
+        return None
+    ctype = clsname[0].lower() + clsname[1:]
+    return ctype if ctype in _catalog() else None
+
+
+# ─── compile helpers ─────────────────────────────────────────────────────────
+def _members(klass):
+    """Ordered (name, value) of a class body, skipping dunders and internals."""
+    for name, value in vars(klass).items():
+        if name.startswith("_"):
+            continue
+        yield name, value
+
+
+def _is_sub(value, base) -> bool:
+    return isinstance(value, type) and issubclass(value, base)
+
+
+def _collect_ids(klass, idmap: dict) -> None:
+    """Map every spec object (by identity) to its attribute-name id, recursively."""
+    for name, value in _members(klass):
+        if isinstance(value, _Spec):
+            idmap[id(value)] = name
+        elif _is_sub(value, (Tab, Group)):
+            _collect_ids(value, idmap)
+
+
+def _resolve_kwargs(kwargs: dict, idmap: dict) -> dict:
+    return {k: (v.resolve(idmap) if isinstance(v, _Cmp) else v) for k, v in kwargs.items()}
+
+
+def _populate(scope, klass, idmap: dict) -> None:
+    """Materialise a class body into a layout scope (a tab or group handle)."""
+    for name, value in _members(klass):
+        if isinstance(value, _Spec):
+            make = getattr(scope, value._ctype)
+            make(name, **_resolve_kwargs(value._kwargs, idmap))
+        elif _is_sub(value, Group):
+            gm = value._group_meta
+            gh = scope.group(gm["label"], id=name, span=gm["span"], cols=gm["cols"],
+                             rows=gm["rows"], dynamic=gm["dynamic"], pulse=gm["pulse"],
+                             hide_background=gm["hide_background"],
+                             visible=(gm["visible"].resolve(idmap)
+                                      if isinstance(gm["visible"], _Cmp) else gm["visible"]))
+            with gh:
+                _populate(gh, value, idmap)
+
+
+# ─── declarative bases ───────────────────────────────────────────────────────
+class Tab:
+    """Base for a nested tab class: ``class Main(Tab, icon="gauge", cols=4, rows=6): ...``"""
+
+    @classmethod
+    def __init_subclass__(cls, *, title: str = None, icon: str = "square.grid.2x2",
+                          cols: int = None, rows: int = 6, columns: int = None, **rest):
+        super().__init_subclass__(**rest)
+        cls._tab_meta = {"title": title or cls.__name__, "icon": icon,
+                         "cols": cols if cols is not None else (columns or 4), "rows": rows}
+
+
+class Group:
+    """Base for a nested group class. Class kwargs mirror `Layout.group`:
+    ``class Motors(Group, span=(2,2), cols=2, rows=2, dynamic="motor_state"): ...``"""
+
+    @classmethod
+    def __init_subclass__(cls, *, label: str = None, span=None, cols: int = 4, rows: int = 4,
+                          dynamic: str = None, visible=None, pulse=None,
+                          hide_background: bool = None, **rest):
+        super().__init_subclass__(**rest)
+        cls._group_meta = {"label": label if label is not None else cls.__name__,
+                           "span": span, "cols": cols, "rows": rows, "dynamic": dynamic,
+                           "visible": visible, "pulse": pulse, "hide_background": hide_background}
+
+
+class _ScreenMeta(type):
+    @property
+    def layout(cls) -> dict:
+        return cls.build().layout
+
+
+class Screen(metaclass=_ScreenMeta):
+    """Base for a declarative layout. Subclass kwargs: ``name=``, ``cols=``, ``rows=``,
+    ``accent=``. Access the result via ``.layout`` / ``.build()`` / ``.json()`` /
+    ``.save(path)`` / ``.validate()`` / ``.findings()``."""
+
+    @classmethod
+    def __init_subclass__(cls, *, name: str = None, cols: int = None, rows: int = 6,
+                          columns: int = None, accent: str = "#667eea", **rest):
+        super().__init_subclass__(**rest)
+        cls._screen_meta = {"name": name or cls.__name__,
+                            "cols": cols if cols is not None else (columns or 4),
+                            "rows": rows, "accent": accent}
+        cls._compiled = None
+
+    @classmethod
+    def _compile(cls) -> Layout:
+        meta = cls._screen_meta
+        lay = Layout(meta["name"], cols=meta["cols"], rows=meta["rows"], accent=meta["accent"])
+
+        idmap: dict = {}
+        _collect_ids(cls, idmap)
+
+        for _n, value in _members(cls):
+            if isinstance(value, Connect):
+                lay.connect(value.url, **value.identity)
+
+        tabs = [(n, v) for n, v in _members(cls) if _is_sub(v, Tab)]
+        loose = [(n, v) for n, v in _members(cls)
+                 if isinstance(v, _Spec) or _is_sub(v, Group)]
+        if tabs:
+            if any(isinstance(v, _Spec) for _n, v in loose):
+                raise DeclareError(
+                    "controls are defined directly on the Screen alongside Tab classes — "
+                    "move them inside a Tab (controls must live in a tab)")
+            for _n, tabcls in tabs:
+                tm = tabcls._tab_meta
+                handle = lay.tab(tm["title"], icon=tm["icon"], cols=tm["cols"], rows=tm["rows"])
+                with handle:
+                    _populate(handle, tabcls, idmap)
+        else:
+            _populate(lay, cls, idmap)
+        return lay
+
+    @classmethod
+    def build(cls) -> Layout:
+        """Compile (once) to a `Layout`. Cached on the class."""
+        if cls.__dict__.get("_compiled") is None:
+            cls._compiled = cls._compile()
+        return cls._compiled
+
+    @classmethod
+    def json(cls, indent: int = 2) -> str:
+        return cls.build().json(indent)
+
+    @classmethod
+    def save(cls, path: str, indent: int = 2) -> str:
+        return cls.build().save(path, indent)
+
+    @classmethod
+    def validate(cls) -> list:
+        return cls.build().validate()
+
+    @classmethod
+    def findings(cls) -> str:
+        return cls.build().findings()
+
+
+# ─── module-level control-class access (PEP 562) ─────────────────────────────
+_STATIC = {"Screen", "Tab", "Group", "Connect", "Ref", "DeclareError"}
+
+
+def __getattr__(name: str):
+    ctype = _type_for(name)
+    if ctype is not None:
+        return _spec_class(ctype, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    pascal = [t[0].upper() + t[1:] for t in _catalog()]
+    return sorted(_STATIC | set(pascal))
+
+
+__all__ = sorted(_STATIC | {t[0].upper() + t[1:] for t in _catalog()})