carterkit 0.5.2__tar.gz → 0.6.0__tar.gz

{carterkit-0.5.2 → carterkit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.5.2
+Version: 0.6.0
 Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
 Author: Carter Beaudoin
 License-Expression: MIT
@@ -65,17 +65,26 @@ with Layout("Dashboard", cols=4, rows=4) as ui:
         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)
+        ui.button("refresh", label="Refresh", send="refresh")
 
 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.
+Binding sugar: `listen=`/`when=`/`event=` build a `sync`, and `send=`/`payload=` build
+an `action` — `send="refresh"` compiles to the one shape the relay actually forwards
+(`broadcast_request` tagged `msg_type: "refresh"`; `Hub.on` demuxes it back for you).
+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.
+
+> **Naming:** multi-word controls are **`snake_case` as `Layout` methods**
+> (`ui.status_light(...)`, `ui.log_console(...)`, `ui.progress_ring(...)`) but
+> **`camelCase` as the JSON `type`** and as `carterkit.build.*` functions
+> (`"statusLight"`, `build.logConsole`). Single-word controls (`gauge`, `button`) look
+> the same either way. Grid size (`cols`/`rows`) set on `Layout(...)` is the default for
+> every tab; override it per tab with `ui.tab("Name", rows=…)`.
 
 **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
@@ -89,7 +98,7 @@ class Dashboard(Screen, cols=4, rows=4):
     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)
+        refresh = Button(label="Refresh", send="refresh")
 
 Dashboard.save("dashboard.json")
 ```
@@ -121,7 +130,7 @@ Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_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;
+`codegen.generate_service_stub(layout)` emits a runnable `Hub`-based server skeleton;
 `theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
 
 ## CLI
@@ -131,29 +140,66 @@ 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 gen layout.json         # generate a runnable Hub server stub
 carterkit relay --port 8765       # run the bundled MeshSocket relay
 ```
 
-## Drive a device
+## Drive the layout you just built
+
+The layout already declares every control's wire contract, so the same object that
+authored the UI also drives it — `ctrl.push(value)` derives the broadcast from the
+control's `sync` binding, and `@ctrl.on` derives the demux from its `action`:
 
 ```python
 import asyncio
-from carterkit import CarterClient
+from carterkit import Layout
+
+with Layout("Thermostat") as ui:
+    with ui.tab("Main"):
+        temp   = ui.gauge("temp", label="Temp", min=0, max=40,
+                          listen="temp", when={"msg_type": "climate"})
+        target = ui.slider("target", min=10, max=30, send="set_target")
 
 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
+    async with ui.serve() as hub:        # zero config: embedded LocalRelay
+        print("pair the app with:", hub.qr_json())
+        await hub.wait_for_device()
+        await hub.push_layout()          # routed apply-layout; echoes what rendered
+
+        @target.on
+        async def _(data):
+            heater.set(data["value"])
+
+        while True:
+            await temp.push(read_temp())
+            await asyncio.sleep(2)
 
 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
+The same surface works cross-process off the saved JSON — the layout file is the
+contract: `Hub("dashboard.json").push("temp", 21.5)`. Dynamic groups fill with
+`hub.fill(group, fragment)`; the hub answers late joiners with the last pushed values
+(control-state authority) by default.
+
+## One connection story
+
+`Connection.parse(...)` accepts every connection artifact in the ecosystem, and
+`ui.connect(...)` / `ui.serve(...)` / `Hub(...)` all take it:
+
+| You have | Pass | Works |
+|---|---|---|
+| nothing (LAN dev) | `ui.serve()` | embedded `LocalRelay`, QR pairing |
+| a self-hosted relay | `"ws://192.168.1.50:8765"` (+ `token=`) | symmetric: same config for app & hub |
+| Connect+ | the **Add Device** JSON from the app (Members → Add Device) | token self-refresh + room E2EE automatic |
+
+The asymmetry to know: self-hosted is symmetric (one URL + shared key both sides);
+on Connect+ the app joins with its own account while the hub holds the per-device
+credential — which is the hub's identity, so it is never embedded into a layout.
+
+`CarterClient` remains the lower-level client (`on`/`broadcast`/`request`).
+End-to-end encryption (ChaCha20-Poly1305 + per-session salt) is transparent when an
+`e2ee_key` is present. Send a push to every device on a Connect+ account with
 `CarterClient.notify(...)` or the stdlib-only `carterkit.notify_http(...)`.
 
 ## Built on

{carterkit-0.5.2 → carterkit-0.6.0}/README.md

@@ -42,17 +42,26 @@ with Layout("Dashboard", cols=4, rows=4) as ui:
         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)
+        ui.button("refresh", label="Refresh", send="refresh")
 
 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.
+Binding sugar: `listen=`/`when=`/`event=` build a `sync`, and `send=`/`payload=` build
+an `action` — `send="refresh"` compiles to the one shape the relay actually forwards
+(`broadcast_request` tagged `msg_type: "refresh"`; `Hub.on` demuxes it back for you).
+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.
+
+> **Naming:** multi-word controls are **`snake_case` as `Layout` methods**
+> (`ui.status_light(...)`, `ui.log_console(...)`, `ui.progress_ring(...)`) but
+> **`camelCase` as the JSON `type`** and as `carterkit.build.*` functions
+> (`"statusLight"`, `build.logConsole`). Single-word controls (`gauge`, `button`) look
+> the same either way. Grid size (`cols`/`rows`) set on `Layout(...)` is the default for
+> every tab; override it per tab with `ui.tab("Name", rows=…)`.
 
 **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
@@ -66,7 +75,7 @@ class Dashboard(Screen, cols=4, rows=4):
     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)
+        refresh = Button(label="Refresh", send="refresh")
 
 Dashboard.save("dashboard.json")
 ```
@@ -98,7 +107,7 @@ Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_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;
+`codegen.generate_service_stub(layout)` emits a runnable `Hub`-based server skeleton;
 `theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
 
 ## CLI
@@ -108,29 +117,66 @@ 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 gen layout.json         # generate a runnable Hub server stub
 carterkit relay --port 8765       # run the bundled MeshSocket relay
 ```
 
-## Drive a device
+## Drive the layout you just built
+
+The layout already declares every control's wire contract, so the same object that
+authored the UI also drives it — `ctrl.push(value)` derives the broadcast from the
+control's `sync` binding, and `@ctrl.on` derives the demux from its `action`:
 
 ```python
 import asyncio
-from carterkit import CarterClient
+from carterkit import Layout
+
+with Layout("Thermostat") as ui:
+    with ui.tab("Main"):
+        temp   = ui.gauge("temp", label="Temp", min=0, max=40,
+                          listen="temp", when={"msg_type": "climate"})
+        target = ui.slider("target", min=10, max=30, send="set_target")
 
 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
+    async with ui.serve() as hub:        # zero config: embedded LocalRelay
+        print("pair the app with:", hub.qr_json())
+        await hub.wait_for_device()
+        await hub.push_layout()          # routed apply-layout; echoes what rendered
+
+        @target.on
+        async def _(data):
+            heater.set(data["value"])
+
+        while True:
+            await temp.push(read_temp())
+            await asyncio.sleep(2)
 
 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
+The same surface works cross-process off the saved JSON — the layout file is the
+contract: `Hub("dashboard.json").push("temp", 21.5)`. Dynamic groups fill with
+`hub.fill(group, fragment)`; the hub answers late joiners with the last pushed values
+(control-state authority) by default.
+
+## One connection story
+
+`Connection.parse(...)` accepts every connection artifact in the ecosystem, and
+`ui.connect(...)` / `ui.serve(...)` / `Hub(...)` all take it:
+
+| You have | Pass | Works |
+|---|---|---|
+| nothing (LAN dev) | `ui.serve()` | embedded `LocalRelay`, QR pairing |
+| a self-hosted relay | `"ws://192.168.1.50:8765"` (+ `token=`) | symmetric: same config for app & hub |
+| Connect+ | the **Add Device** JSON from the app (Members → Add Device) | token self-refresh + room E2EE automatic |
+
+The asymmetry to know: self-hosted is symmetric (one URL + shared key both sides);
+on Connect+ the app joins with its own account while the hub holds the per-device
+credential — which is the hub's identity, so it is never embedded into a layout.
+
+`CarterClient` remains the lower-level client (`on`/`broadcast`/`request`).
+End-to-end encryption (ChaCha20-Poly1305 + per-session salt) is transparent when an
+`e2ee_key` is present. Send a push to every device on a Connect+ account with
 `CarterClient.notify(...)` or the stdlib-only `carterkit.notify_http(...)`.
 
 ## Built on

{carterkit-0.5.2 → carterkit-0.6.0}/carterkit/__init__.py

@@ -13,7 +13,11 @@ Quick map:
   - ``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
+  - ``Connection`` — ONE parser for every connection artifact (relay URL, pairing
+    QR JSON, Connect+ Add-Device credential, layout connection block)
+  - ``Hub`` / ``Layout.serve()`` — drive the layout you built: ``ctrl.push(value)``
+    and ``@ctrl.on`` derived from the very sync/action bindings you authored
+  - ``CarterClient`` / ``notify_http`` — the lower-level client: connect, push, alerts
 """
 from importlib.resources import files
 from pathlib import Path
@@ -27,6 +31,8 @@ from .relay import LocalRelay, port_in_use, lan_ip
 from . import bind
 from .controls import build, control
 from .layout import Layout, Fragment, Control, Condition
+from .connection import Connection
+from .hub import Hub, HubError
 
 try:
     from importlib.metadata import PackageNotFoundError, version as _pkg_version
@@ -85,5 +91,6 @@ __all__ = [
     "controls", "doc", "doc_markdown", "examples", "validate_layout",
     "lint_dynamic_traffic", "format_findings", "controldocs_dir",
     "build", "control", "bind", "Layout", "Fragment", "Control", "Condition",
+    "Connection", "Hub", "HubError",
     "catalog", "grid", "codegen", "infer", "theming", "tune", "dynamic",
 ]

carterkit-0.6.0/carterkit/bind.py

@@ -0,0 +1,99 @@
+"""Helpers that build the (verbose, easy-to-get-wrong) sync / action / connection
+dicts controls use. Shapes mirror the bundled ControlDocs (sync.md, actions.md).
+
+    from carterkit import bind
+    bind.listen("cpu", filter={"msg_type": "telemetry"})
+    bind.command("set_power", payload={"state": "{{value}}"})
+    bind.connection("ws://192.168.1.50:8765", channel="home")
+
+The one wire fact everything here encodes: the relay dispatches ONLY its own verbs
+(`WIRE_VERBS` plus housekeeping like `ping`). An action whose `event` is any other
+name is silently dropped at the relay — the control does nothing. Commands therefore
+ride `broadcast_request` with the command name as the payload's `msg_type`, and the
+server demuxes on that (`Hub.on` does it automatically).
+"""
+from __future__ import annotations
+
+#: The only frame types the relay forwards between peers. An action's `event`
+#: must be one of these (or be built by :func:`command`) to go anywhere.
+WIRE_VERBS = ("broadcast_request", "route_msg", "route_msg_noreply")
+
+#: Frame types the relay itself answers (housekeeping) — legal, but not data-plane.
+#: `identify` re-identifies the sender (name/channel switching from a control).
+RELAY_SERVICE_VERBS = ("ping", "handshake", "status_request", "get_nodes", "identify")
+
+
+def listen(value_path: str, *, event: str = "broadcast", filter: dict | None = None,
+           method: str = "meshsocket") -> dict:
+    """A `sync` entry: subscribe to `event`, match `filter`, extract `value_path`
+    (dot-notation). Returns one sync dict — controls take a list of them."""
+    s: dict = {"method": method, "type": "listen", "event": event, "valuePath": value_path}
+    if filter is not None:
+        s["filter"] = filter
+    return s
+
+
+def action(event: str, *, payload: dict | None = None, mode: str = "broadcast",
+           method: str = "meshsocket") -> dict:
+    """A raw `action` dict: fire the frame `event` on tap/change. `mode` is
+    "broadcast" (fire and forget) or "request" (await reply). `payload` strings
+    support `{{value}}`.
+
+    This is the power-user escape hatch — `event` goes on the wire as the frame
+    type verbatim, so it must be a relay verb (`WIRE_VERBS`) to be forwarded.
+    For a named command, use :func:`command` instead."""
+    if mode not in ("broadcast", "request"):
+        raise ValueError(f"mode must be 'broadcast' or 'request', got {mode!r}")
+    a: dict = {"method": method, "mode": mode, "event": event}
+    if payload is not None:
+        a["payload"] = payload
+    return a
+
+
+def command(name: str, *, payload: dict | None = None, method: str = "meshsocket") -> dict:
+    """An `action` for a named command that actually crosses the relay.
+
+    Compiles to `broadcast_request` with `name` as the payload's `msg_type` — the
+    fan-out shape every server can demux on (`Hub.on(handle)` derives it back).
+    Default payload adds `{"value": "{{value}}"}` so the control's value rides
+    along; pass `payload=` to replace that (the `msg_type` key always stays the
+    command name).
+
+    There is deliberately no request/reply variant: the relay only routes replies
+    for `route_msg`, which needs a live `target_id` no layout can know at author
+    time. Use the round-trip idiom instead — fire the command, and `listen=` for
+    the state broadcast the server sends back."""
+    body = dict(payload) if payload is not None else {"value": "{{value}}"}
+    body["msg_type"] = name
+    return {"method": method, "mode": "broadcast", "event": "broadcast_request",
+            "payload": body}
+
+
+def connection(url: str | None, *, channel: str = "home", name: str = "CAR-TER",
+               role: str = "controller", token: str | None = None,
+               hub: str | None = None, mode: str | None = None,
+               e2ee_key: str | None = None, can_broadcast: bool | None = None) -> dict:
+    """A layout `connection` block (relay URL + identity). `hub` names the mesh
+    identity of the server that will drive this layout (`Layout.serve` adopts it),
+    so both sides of the contract live in one artifact.
+
+    `mode="room"` + `e2ee_key` (base64 group key, emitted as `e2eeKey`) author the
+    Connect+ room shape — see `carterkit.connection.Connection.layout_block`, whose
+    output this mirrors. In a room, `url=None` omits the URL entirely: the app dials
+    its own Connect+ relay with its own account session, and a raw url/token here
+    would make it hand the wrong credential to the wrong host (reconnect loop)."""
+    conn: dict = {"identity": {"name": name, "channel": channel, "role": role}}
+    if url is not None:
+        conn["url"] = url
+    if token is not None:
+        conn["token"] = token
+    if hub is not None:
+        conn["hub"] = hub
+    if e2ee_key is not None:
+        conn["mode"] = mode or "room"
+        conn["e2eeKey"] = e2ee_key
+    elif mode is not None:
+        conn["mode"] = mode
+    if can_broadcast is not None:
+        conn["identity"]["can_broadcast"] = can_broadcast
+    return conn

{carterkit-0.5.2 → carterkit-0.6.0}/carterkit/buffer.py

@@ -197,8 +197,44 @@ class LayoutBuffer:
             position = slot
         group["position"] = position
         children.append(group)
+        # Normalize nested children the same way add_control does for top-level ones:
+        # give each an id and an auto-placed position in the group's own grid, so the
+        # group validates instead of erroring on missing id/position. (Append first so
+        # unique_id, which scans the committed tree, sees the group's own children.)
+        self._normalize_group_children(group)
         return group
 
+    def _normalize_group_children(self, group: dict) -> None:
+        """Ensure every child of a group has an id and a position within the group's
+        grid. Auto-places (like add_control) any child missing a position, recursing
+        into nested groups. Raises if the group's grid has no room."""
+        kids = group.get("children")
+        if not isinstance(kids, list):
+            return
+        g = group.get("grid") or {}
+        cols = int(g.get("columns", g.get("cols", DEFAULT_COLUMNS)))
+        rows = int(g.get("rows", DEFAULT_ROWS))
+        # Record the grid we placed against so the device renders with the same dims.
+        group.setdefault("grid", {"columns": cols, "rows": rows})
+        placed = [c for c in kids if isinstance(c, dict) and c.get("position") is not None]
+        for child in kids:
+            if not isinstance(child, dict) or "type" not in child:
+                continue
+            if not child.get("id"):
+                child["id"] = self.unique_id(child["type"])
+            if child.get("position") is None:
+                span = child.get("span") or [1, 1]
+                slot = gridmod.find_slot(placed, cols, rows, span)
+                if slot is None:
+                    raise BufferError(
+                        f"group '{group['id']}' has no free {span} slot in its "
+                        f"{rows}x{cols} grid for child '{child['id']}' — grow the group "
+                        f"grid (cols/rows) or set the child's position.")
+                child["position"] = slot
+                placed.append(child)
+            if child.get("type") == "group":
+                self._normalize_group_children(child)
+
     # ─── views ───────────────────────────────────────────────────────────────
 
     def issues(self) -> list[dict]:

{carterkit-0.5.2 → carterkit-0.6.0}/carterkit/catalog.py

@@ -57,6 +57,10 @@ def _make_field(raw: dict[str, str]) -> dict:
         field["default"] = raw["default"]
     if raw.get("description"):
         field["description"] = raw["description"]
+    if raw.get("group"):
+        # Per-field `group:` nests the field under a config object (e.g.
+        # `sortboardConfig`) — mirrored from the Swift loader's makeField.
+        field["group"] = raw["group"]
     return field
 
 
@@ -197,7 +201,10 @@ def extract_examples(body: str) -> list[dict]:
 # ─── Catalog assembly ────────────────────────────────────────────────────────
 
 # Categories whose docs describe controls that can be placed in a layout grid.
-PLACEABLE_CATEGORIES = {"controls", "display"}
+# "layout" covers the structural placeables (divider, spacer) — real grid
+# citizens the app renders, previously missing from the catalog so typed
+# builders rejected them and servers had to inject raw dicts.
+PLACEABLE_CATEGORIES = {"controls", "display", "layout"}
 
 
 def parse_all(docs_dir) -> dict[str, dict]:

{carterkit-0.5.2 → carterkit-0.6.0}/carterkit/cli.py

@@ -63,7 +63,7 @@ def _cmd_gen(args) -> int:
     import carterkit
     with open(args.file) as f:
         layout = json.load(f)
-    print(carterkit.codegen.generate_service_stub(layout))
+    print(carterkit.codegen.generate_service_stub(layout, layout_path=args.file))
     return 0
 
 

{carterkit-0.5.2 → carterkit-0.6.0}/carterkit/client.py

@@ -106,12 +106,17 @@ def device_refresh_http(validator_url, device_id, refresh_token, *, _send=None):
 class CarterClient:
     def __init__(self, gateway_url, token, channel, role="device", name="hub", e2ee_key=None,
                  validator_url=None, session_jwt=None, room=False,
-                 device_id=None, refresh_token=None, refresh_interval=2400):
+                 device_id=None, refresh_token=None, refresh_interval=2400,
+                 can_route=False, can_monitor=False):
         if MeshSocket is None:
             raise ImportError("MeshSocket is unavailable; run `pip install meshsocket`. "
                               "(notify_http does not need it.)")
+        # can_route lets this client SEND routed requests (route_msg); can_monitor
+        # unlocks get_nodes roster reads. Both off by default — a plain data hub
+        # needs neither; Hub turns them on to resolve and push to devices.
         self._sock = MeshSocket(url=gateway_url, name=name, auth_token=token,
-                                channel=channel, role=role, can_broadcast=True, can_route=False)
+                                channel=channel, role=role, can_broadcast=True,
+                                can_route=can_route, can_monitor=can_monitor)
         # `room=True` matches the app's `mode: room`: a symmetric group cipher so the hub
         # shares an encrypted room with several members. Otherwise the directional 1:1 cipher.
         if e2ee_key:
@@ -139,6 +144,8 @@ class CarterClient:
         self._is_state_authority = False
         self._broadcast_handler = None
         self._broadcast_registered = False
+        self._join_handler = None
+        self._ack_commands = False
 
     def _open(self, payload):
         if self._session and isinstance(payload, dict) and E2EESession.is_envelope(payload):
@@ -176,17 +183,68 @@ class CarterClient:
             return None
         self._sock.on("broadcast", wrapper)
 
+    #: Broadcast msg_types that are protocol plane, not app data — consumed by
+    #: _dispatch_broadcast and never handed to on_broadcast handlers. command_ack
+    #: is app-directed (a hub's reply to a phone), so hubs must not see each
+    #: other's acks as data.
+    _PROTOCOL_BROADCASTS = ("control_sync_request", "control_snapshot", "command_ack")
+
     async def _dispatch_broadcast(self, data):
-        # Control-state sync frames are protocol, not app data — consume them here so they
-        # never reach the user's on_broadcast handler. Only an authority answers a request.
-        if isinstance(data, dict) and data.get("msg_type") in ("control_sync_request", "control_snapshot"):
-            if self._is_state_authority and data.get("msg_type") == "control_sync_request":
-                await self._answer_control_sync(data)
+        # Protocol frames are consumed here so they never reach the user's
+        # on_broadcast handler. A sync request is answered by an authority AND
+        # surfaced via on_sync_request (the join signal); snapshots/acks are for
+        # replicas (the app), not for us.
+        if isinstance(data, dict) and data.get("msg_type") in self._PROTOCOL_BROADCASTS:
+            if data.get("msg_type") == "control_sync_request":
+                if self._is_state_authority:
+                    await self._answer_control_sync(data)
+                if self._join_handler is not None:
+                    result = self._join_handler(data)
+                    if asyncio.iscoroutine(result):
+                        await result
+            return
+        if self._broadcast_handler is None:
             return
-        if self._broadcast_handler is not None:
+        # Ack'd-command layer (the app's layout `state.acks`): a `_cmd`-stamped frame
+        # is acknowledged only when the handler REPORTS it handled it (returns True) —
+        # a hub whose demux matched nothing must stay silent so the app times out and
+        # reverts (and so another hub on the channel can be the one that answers).
+        # ok:false on a raised exception, which still propagates unchanged.
+        cmd_id = data.get("_cmd") if (self._ack_commands and isinstance(data, dict)) else None
+        try:
             result = self._broadcast_handler(data)
             if asyncio.iscoroutine(result):
-                await result
+                result = await result
+        except Exception:
+            if cmd_id is not None:
+                await self.broadcast("command_ack", {
+                    "cmd_id": cmd_id, "to": data.get("_from"), "ok": False})
+            raise
+        if cmd_id is not None and result is True:
+            await self.broadcast("command_ack", {
+                "cmd_id": cmd_id, "to": data.get("_from"), "ok": True})
+
+    def on_sync_request(self, handler):
+        """Register the deterministic "a replica just joined / came back" signal: the
+        app broadcasts `control_sync_request` when a layout with synced or dynamic
+        content loads AND on every reconnect. handler(data: dict) gets the decrypted
+        frame (`{from, dynamic?: [...]}` — `dynamic` lists the layout's dynamic slot
+        events); sync or async. Use it to re-push dynamic decks and any full-state
+        snapshot a late joiner needs. (Distinct from LocalRelay.on_join, which is the
+        relay-auth join of a socket, not a layout replica asking for state.)"""
+        self._join_handler = handler
+        self._ensure_broadcast_listener()
+
+    def enable_command_acks(self):
+        """Acknowledge `_cmd`-stamped command broadcasts (the app's opt-in ack'd
+        commands, layout `state.acks: true`) with `command_ack {cmd_id, to, ok}`.
+        The on_broadcast handler must return True for frames it actually handled —
+        only those are acked ok:true; a raised exception acks ok:false; anything
+        else gets NO ack, so the app's pending control times out and reverts (and a
+        different hub on the channel may be the one that answers). Frames without
+        `_cmd` are untouched, so servers stay compatible with plain layouts."""
+        self._ack_commands = True
+        self._ensure_broadcast_listener()
 
     def set_control_state(self, control_id, value):
         """Record the authoritative current value of a control so the hub can answer a
@@ -210,7 +268,12 @@ class CarterClient:
                              {"to": to, "v": self._state_version, "controls": dict(self._control_state)})
 
     async def broadcast(self, msg_type, data):
-        await self._sock.send("broadcast_request", self._seal({**data, "msg_type": msg_type}))
+        await self.broadcast_frame({**data, "msg_type": msg_type})
+
+    async def broadcast_frame(self, frame):
+        """Broadcast a pre-assembled payload verbatim (no msg_type is forced on it) —
+        the escape hatch for frames whose shape a control's sync filter dictates."""
+        await self._sock.send("broadcast_request", self._seal(frame))
 
     async def chat(self, text, *, name="Server", role="device", channel=None, msg_id=None, **extra):
         """Send a channel chat message a chat control will display, as a bubble from `name`.
@@ -277,6 +340,18 @@ class CarterClient:
                 pass  # transient (network/5xx) — retry next interval
 
     async def connect(self):
+        # A hub that sat stopped past its short-lived token's expiry can never
+        # identify (the relay drops it with "not admitted" forever) — when we hold
+        # a refresh credential, pre-mint a fresh token so (re)starts self-heal.
+        # A transient validator error falls through to the stored token.
+        if self._device_id and self._refresh_token and self._validator_url:
+            try:
+                await self.refresh_device_token()
+            except CarterDeviceRevoked:
+                self.revoked = True
+                raise
+            except Exception:
+                pass
         await self._sock.start()
         await self._sock.wait_until_ready()
         # Auto-start the refresh loop only for a self-refreshing external device.