carterkit 0.5.2__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.5.2
+Version: 0.7.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,60 @@ 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=…)`.
+
+### Beyond MeshSocket — sources, sensors, and app-side features
+
+A layout can drive itself off protocols you already run, or the phone's own hardware, with
+**no server code** — the app speaks them directly:
+
+```python
+ui.source_mqtt("broker", "mqtt://192.168.1.10:1883")   # declare a broker
+ui.source_http("api", "http://192.168.1.5:8080", interval=5)
+with ui.tab("Home", icon="house"):
+    ui.gauge("temp", label="Temp", min=0, max=40, sync=[bind.mqtt("home/temp")])
+    ui.toggle("fan", label="Fan", sync=[bind.mqtt("home/fan/state")],
+              action=bind.mqtt_publish("home/fan/set"))
+    ui.gauge("cpu", label="CPU", sync=[bind.http("/status", interval=5, valuePath="cpu")])
+    ui.compass("hdg", label="Heading", sensor="heading")   # device sensor, no backend
+```
+
+`bind.mqtt` / `bind.mqtt_publish` / `bind.http` / `bind.http_request` / `bind.sensor` build
+the sync/action dicts; the validator checks a `source:` names a declared source and that
+mqtt/http bindings carry a topic/path. These are marked **app-direct** in the contract, so a
+generated `bridge.py` never tries to serve them.
+
+Author the rest of the app's surface from Python too:
+
+```python
+ui.publisher("heading", interval=0.25)                     # stream a sensor to a hub/server
+ui.alert(event="broadcast", value_path="temp", operator="gt", value=30,
+         title="Too hot", body="Greenhouse over 30°C")     # relay-watcher push rule
+ui.glance(hero="temp", slots=["fan"], live_activity=True)  # widgets / Live Activity
+ui.poll_group("tick", event="broadcast_request", interval=10, payload={"msg_type": "poll"})
+ui.appearance(color_scheme="dark", show_header=True)
+ui.dynamic_tab("inject_tab")                               # runtime-injected tab
+ui.state(sync=True, authority="hub", acks=True)           # device-held shared state + acks
+```
 
 **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 +132,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 +164,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 +174,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.7.0/README.md

@@ -0,0 +1,221 @@
+# 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")
+
+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=`/`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=…)`.
+
+### Beyond MeshSocket — sources, sensors, and app-side features
+
+A layout can drive itself off protocols you already run, or the phone's own hardware, with
+**no server code** — the app speaks them directly:
+
+```python
+ui.source_mqtt("broker", "mqtt://192.168.1.10:1883")   # declare a broker
+ui.source_http("api", "http://192.168.1.5:8080", interval=5)
+with ui.tab("Home", icon="house"):
+    ui.gauge("temp", label="Temp", min=0, max=40, sync=[bind.mqtt("home/temp")])
+    ui.toggle("fan", label="Fan", sync=[bind.mqtt("home/fan/state")],
+              action=bind.mqtt_publish("home/fan/set"))
+    ui.gauge("cpu", label="CPU", sync=[bind.http("/status", interval=5, valuePath="cpu")])
+    ui.compass("hdg", label="Heading", sensor="heading")   # device sensor, no backend
+```
+
+`bind.mqtt` / `bind.mqtt_publish` / `bind.http` / `bind.http_request` / `bind.sensor` build
+the sync/action dicts; the validator checks a `source:` names a declared source and that
+mqtt/http bindings carry a topic/path. These are marked **app-direct** in the contract, so a
+generated `bridge.py` never tries to serve them.
+
+Author the rest of the app's surface from Python too:
+
+```python
+ui.publisher("heading", interval=0.25)                     # stream a sensor to a hub/server
+ui.alert(event="broadcast", value_path="temp", operator="gt", value=30,
+         title="Too hot", body="Greenhouse over 30°C")     # relay-watcher push rule
+ui.glance(hero="temp", slots=["fan"], live_activity=True)  # widgets / Live Activity
+ui.poll_group("tick", event="broadcast_request", interval=10, payload={"msg_type": "poll"})
+ui.appearance(color_scheme="dark", show_header=True)
+ui.dynamic_tab("inject_tab")                               # runtime-injected tab
+ui.state(sync=True, authority="hub", acks=True)           # device-held shared state + acks
+```
+
+**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")
+
+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 `Hub`-based 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 runnable Hub server stub
+carterkit relay --port 8765       # run the bundled MeshSocket relay
+```
+
+## 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 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 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())
+```
+
+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
+
+[`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.5.2 → carterkit-0.7.0}/carterkit/__init__.py

@@ -13,12 +13,17 @@ 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
 
-from . import catalog, grid, codegen, infer, theming, tune, dynamic
+from . import catalog, grid, codegen, infer, theming, tune, dynamic, contract
+from .contract import extract_contract
 from .buffer import LayoutBuffer, BufferError
 from .validate import validate_layout as _validate_layout, format_findings
 from .client import (CarterClient, notify_http, CarterNotifyError,
@@ -27,6 +32,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 +92,7 @@ __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",
+    "contract", "extract_contract",
 ]

carterkit-0.7.0/carterkit/bind.py

@@ -0,0 +1,183 @@
+"""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}
+
+
+#: Sensor pipelines the app can bind (see sensors.md). Dotted keys pick a field
+#: (`motion.roll`); a bare name is shorthand for its `.value`.
+SENSOR_PIPELINES = ("heading", "motion", "barometer", "device", "audio", "location")
+
+
+def sensor(name: str, *, value_path: str | None = None) -> dict:
+    """A `sync` entry bound to a device sensor — no backend needed (the app streams
+    the reading locally). `name` is a pipeline or dotted key (`"heading"`,
+    `"motion.roll"`, `"device.battery"`). See sensors.md."""
+    s: dict = {"method": "sensor", "sensor": name}
+    if value_path is not None:
+        s["valuePath"] = value_path
+    return s
+
+
+def mqtt(topic: str, *, value_path: str = "", filter: dict | None = None,
+         source: str | None = None) -> dict:
+    """A `sync` entry that subscribes an MQTT topic (see sources.md). `value_path`
+    extracts from a JSON payload (leave empty for bare number/bool/string payloads);
+    `source` names the declared broker (omit when the layout has exactly one)."""
+    s: dict = {"method": "mqtt", "topic": topic}
+    if value_path:
+        s["valuePath"] = value_path
+    if filter is not None:
+        s["filter"] = filter
+    if source is not None:
+        s["source"] = source
+    return s
+
+
+def mqtt_publish(topic: str, *, payload="{{value}}", retain: bool | None = None,
+                 source: str | None = None) -> dict:
+    """An `action` that publishes to an MQTT topic. String payloads publish raw bytes
+    (`ON`, not `"ON"`); objects publish as JSON. `{{value}}` rides the control value."""
+    a: dict = {"method": "mqtt", "topic": topic, "payload": payload}
+    if retain is not None:
+        a["retain"] = retain
+    if source is not None:
+        a["source"] = source
+    return a
+
+
+def http(path: str | None = None, *, url: str | None = None, interval: float | None = None,
+         value_path: str = "", filter: dict | None = None, source: str | None = None) -> dict:
+    """A `sync` entry that polls an HTTP endpoint (see sources.md). Give `path`
+    (against a source's baseURL) or an absolute `url`; `interval` is seconds."""
+    if not path and not url:
+        raise ValueError("http() needs a 'path' (against a source baseURL) or an absolute 'url'")
+    s: dict = {"method": "http"}
+    if path:
+        s["path"] = path
+    if url:
+        s["url"] = url
+    if interval is not None:
+        s["interval"] = interval
+    if value_path:
+        s["valuePath"] = value_path
+    if filter is not None:
+        s["filter"] = filter
+    if source is not None:
+        s["source"] = source
+    return s
+
+
+def http_request(path: str | None = None, *, url: str | None = None,
+                 http_method: str | None = None, payload=None, source: str | None = None) -> dict:
+    """An `action` that fires an HTTP request. `http_method` defaults to POST when a
+    payload is present, else GET. Object payloads send as JSON, strings as text."""
+    if not path and not url:
+        raise ValueError("http_request() needs a 'path' or an absolute 'url'")
+    a: dict = {"method": "http"}
+    if path:
+        a["path"] = path
+    if url:
+        a["url"] = url
+    if http_method is not None:
+        a["httpMethod"] = http_method
+    if payload is not None:
+        a["payload"] = payload
+    if source is not None:
+        a["source"] = source
+    return a
+
+
+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.7.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]: