carterkit 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.6.0
+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
@@ -86,6 +86,40 @@ documentation, straight from the bundled docs.
 > 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):

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

@@ -63,6 +63,40 @@ documentation, straight from the bundled docs.
 > 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):

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

@@ -22,7 +22,8 @@ Quick map:
 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,
@@ -93,4 +94,5 @@ __all__ = [
     "build", "control", "bind", "Layout", "Fragment", "Control", "Condition",
     "Connection", "Hub", "HubError",
     "catalog", "grid", "codegen", "infer", "theming", "tune", "dynamic",
+    "contract", "extract_contract",
 ]

{carterkit-0.6.0 → carterkit-0.7.0}/carterkit/bind.py

@@ -69,6 +69,90 @@ def command(name: str, *, payload: dict | None = None, method: str = "meshsocket
             "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,

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

@@ -141,6 +141,16 @@ def parse_doc(content: str, node_id: str) -> Optional[dict]:
 
     if not meta["type"] or not meta["label"]:
         return None
+    # Fields tagged `group: fooConfig` live nested under that key in the JSON
+    # (the app decodes them as a config object). Synthesize the umbrella field
+    # when the doc doesn't declare it explicitly (heatmap does; the drag pack
+    # doesn't), so validators accept the nested key authors actually write.
+    declared = {f.get("name") for f in meta["fields"]}
+    for grp in dict.fromkeys(f["group"] for f in meta["fields"] if f.get("group")):
+        if grp not in declared:
+            meta["fields"].append(
+                {"name": grp, "type": "object",
+                 "description": "grouped config object (see grouped fields)"})
     meta["body"] = body
     meta["examples"] = extract_examples(body)
     return meta
@@ -204,7 +214,7 @@ def extract_examples(body: str) -> list[dict]:
 # "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"}
+PLACEABLE_CATEGORIES = {"controls", "display", "layout", "input"}
 
 
 def parse_all(docs_dir) -> dict[str, dict]:

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

@@ -67,6 +67,35 @@ def _cmd_gen(args) -> int:
     return 0
 
 
+def _cmd_explore(args) -> int:
+    import asyncio
+    import webbrowser
+    from .explore import build_explorer
+
+    overrides = {k: v for k, v in (("channel", args.channel), ("token", args.token))
+                 if v is not None}
+    explorer = build_explorer(args.source, device=args.device, port=args.port,
+                              **overrides)
+
+    def ready(ex):
+        url = f"http://127.0.0.1:{ex.port}"
+        print(f"Layout Link → {url}")
+        conn = ex.hub.connection
+        if conn.kind in ("local", "selfhosted"):
+            print(f"pair the phone (CAR-TER → Settings → Studio Session → scan):")
+            print(f"  {ex.hub.qr_json()}")
+        if ex.pull is not None and ex.hub.layout is None:
+            print("waiting for the phone to join — the layout appears the moment it does")
+        if not args.no_open:
+            webbrowser.open(url)
+
+    try:
+        asyncio.run(explorer.run(ready=ready))
+    except KeyboardInterrupt:
+        print("\nbye")
+    return 0
+
+
 def _cmd_relay(args) -> int:
     import asyncio
     from socket_server import MeshServer  # bundled with meshsocket
@@ -108,6 +137,23 @@ def build_parser() -> argparse.ArgumentParser:
     c.add_argument("file")
     c.set_defaults(fn=_cmd_gen)
 
+    c = sub.add_parser(
+        "explore",
+        help="serve a live, typed endpoint explorer for a layout (Layout Link)")
+    c.add_argument("source", nargs="?",
+                   help="a layout JSON to explore offline, a pairing/device JSON, "
+                        "or a ws:// relay URL; omit for the zero-config local relay")
+    c.add_argument("--device", nargs="?", const="current", default=None,
+                   metavar="FILE_OR_NAME",
+                   help="pull a layout off the paired phone: a saved layout's "
+                        "file/name, or (bare) whatever is live right now")
+    c.add_argument("--channel", help="mesh channel to join")
+    c.add_argument("--token", help="relay auth token / shared key")
+    c.add_argument("--port", type=int, default=8770, help="explorer web port")
+    c.add_argument("--no-open", action="store_true",
+                   help="don't auto-open the browser")
+    c.set_defaults(fn=_cmd_explore)
+
     c = sub.add_parser("relay", help="run the bundled MeshSocket relay")
     c.add_argument("--host", default="0.0.0.0")
     c.add_argument("--port", type=int, default=8765)

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

@@ -32,27 +32,159 @@ class CarterNotifyError(Exception):
         self.detail = detail
 
 
-def notify_http(validator_url, session_jwt, title, body, *, channel=None, category=None,
-                badge=None, sound="default", data=None, _send=None):
+#: interruption-levels the relay accepts; "critical" needs Apple approval and is
+#: rejected server-side, so fail fast here with the same story.
+_INTERRUPTION_LEVELS = ("passive", "active", "time-sensitive")
+
+
+def _normalize_sender(sender):
+    """Accept `"Monroe"`, `("Monroe", avatar_url)`, or `{"name": ..., "avatarURL"/
+    "avatar_url"/"avatar": ...}` → the wire `{"name", "avatarURL"?}` dict."""
+    if sender is None:
+        return None
+    if isinstance(sender, str):
+        out = {"name": sender}
+    elif isinstance(sender, (tuple, list)):
+        if not sender or len(sender) > 2:
+            raise ValueError("sender tuple must be (name,) or (name, avatar_url)")
+        out = {"name": sender[0]}
+        if len(sender) == 2 and sender[1]:
+            out["avatarURL"] = sender[1]
+    elif isinstance(sender, dict):
+        out = {"name": sender.get("name")}
+        avatar = sender.get("avatarURL") or sender.get("avatar_url") or sender.get("avatar")
+        if avatar:
+            out["avatarURL"] = avatar
+    else:
+        raise ValueError("sender must be a name, (name, avatar_url), or dict")
+    if not out.get("name") or len(out["name"]) > 64:
+        raise ValueError("sender name must be non-empty and <= 64 chars")
+    if len(out.get("avatarURL", "")) > 512:
+        raise ValueError("sender avatar URL must be <= 512 chars")
+    return out
+
+
+def _normalize_actions(actions):
+    """Accept the dict form `{"ack": "Acknowledge"}` / `{"ack": ("Acknowledge", fn)}` /
+    `{"ack": {"name"/"title": ..., "func": fn, "destructive": bool}}` or a wire-style
+    list of dicts → `(wire_actions, callbacks)` where callbacks maps action id → fn
+    (empty when none were given)."""
+    if actions is None:
+        return None, {}
+    wire, callbacks = [], {}
+    if isinstance(actions, dict):
+        items = []
+        for aid, spec in actions.items():
+            if isinstance(spec, str):
+                items.append({"id": aid, "title": spec})
+            elif callable(spec):
+                items.append({"id": aid, "title": aid})
+                callbacks[aid] = spec
+            elif isinstance(spec, (tuple, list)) and len(spec) == 2:
+                items.append({"id": aid, "title": spec[0]})
+                callbacks[aid] = spec[1]
+            elif isinstance(spec, dict):
+                item = {"id": aid, "title": spec.get("title") or spec.get("name") or aid}
+                if spec.get("destructive"):
+                    item["destructive"] = True
+                fn = spec.get("func") or spec.get("funct") or spec.get("callback")
+                if fn is not None:
+                    callbacks[aid] = fn
+                items.append(item)
+            else:
+                raise ValueError(f"action {aid!r}: expected title, callable, (title, fn), or dict")
+        wire = items
+    elif isinstance(actions, (list, tuple)):
+        for a in actions:
+            if not isinstance(a, dict) or not a.get("id") or not a.get("title"):
+                raise ValueError("wire-style actions need dicts with id and title")
+            item = {"id": a["id"], "title": a["title"]}
+            if a.get("destructive"):
+                item["destructive"] = True
+            fn = a.get("func") or a.get("callback")
+            if fn is not None:
+                callbacks[a["id"]] = fn
+            wire.append(item)
+    else:
+        raise ValueError("actions must be a dict or a list of dicts")
+    if len(wire) > 4:
+        raise ValueError("at most 4 actions per notification")
+    for a in wire:
+        if len(a["id"]) > 64 or len(a["title"]) > 48:
+            raise ValueError(f"action {a['id']!r}: id <= 64 and title <= 48 chars")
+    return wire, callbacks
+
+
+def notify_http(validator_url, session_jwt, title, body, *, subtitle=None, channel=None,
+                category=None, badge=None, sound="default", interruption=None,
+                relevance=None, thread_id=None, image=None, sender=None, actions=None,
+                notif_id=None, data=None, _send=None):
     """Send a one-shot push to every device on the account (POST /alerts/notify).
 
     Stdlib-only. `validator_url` is the Connect+ validator base URL; `session_jwt` is the
     Connect+ account session token (NOT the MeshSocket auth token). Returns the parsed
-    `{"sent": N, "stale": M}` response. Raises CarterNotifyError on an HTTP error or
-    ValueError on invalid title/body. `_send` is a test seam: a callable
-    (url, headers, body_bytes) -> dict that bypasses the network."""
+    `{"sent": N, "stale": M, "notifId"?: id}` response. Raises CarterNotifyError on an
+    HTTP error or ValueError on an invalid field. `_send` is a test seam: a callable
+    (url, headers, body_bytes) -> dict that bypasses the network.
+
+    Personalization fields (all optional): `subtitle` (2nd alert line);
+    `interruption` "passive" | "active" | "time-sensitive" ("critical" requires Apple
+    approval and is rejected); `relevance` 0..1 orders stacked notifications;
+    `thread_id` groups notifications (use one id per layout/conversation); `image` is an
+    https URL the device downloads and attaches; `sender` renders the push as a
+    Communication Notification "from" that persona — name + circular avatar (see
+    `_normalize_sender` for accepted shapes); `actions` adds up to 4 buttons (wire-style
+    list of `{"id", "title", "destructive"?}` — callback dispatch lives on
+    `CarterClient.notify`, not here); `notif_id` is echoed back by button taps. `sound`
+    is a sound file name bundled in the app, "default", or "none" (silent) — remote
+    sound URLs are not a thing APNs supports."""
     if not title or len(title) > 256:
         raise ValueError("title must be non-empty and <= 256 chars")
     if not body or len(body) > 256:
         raise ValueError("body must be non-empty and <= 256 chars")
+    if subtitle is not None and len(subtitle) > 256:
+        raise ValueError("subtitle must be <= 256 chars")
+    if interruption is not None and interruption not in _INTERRUPTION_LEVELS:
+        if interruption == "critical":
+            raise ValueError('interruption "critical" requires Apple approval and is not enabled')
+        raise ValueError(f"interruption must be one of {_INTERRUPTION_LEVELS}")
+    if relevance is not None and not (0 <= relevance <= 1):
+        raise ValueError("relevance must be within 0..1")
+    if thread_id is not None and len(thread_id) > 128:
+        raise ValueError("thread_id must be <= 128 chars")
+    if image is not None and len(image) > 512:
+        raise ValueError("image URL must be <= 512 chars")
+    if notif_id is not None and len(notif_id) > 64:
+        raise ValueError("notif_id must be <= 64 chars")
+    sender = _normalize_sender(sender)
+    wire_actions, callbacks = _normalize_actions(actions)
+    if callbacks:
+        raise ValueError("action callbacks need a mesh connection — use "
+                         "CarterClient.notify(); notify_http sends buttons only")
 
     payload = {"title": title, "body": body, "sound": sound}
+    if subtitle is not None:
+        payload["subtitle"] = subtitle
     if channel is not None:
         payload["channel"] = channel
     if category is not None:
         payload["category"] = category
     if badge is not None:
         payload["badge"] = badge
+    if interruption is not None:
+        payload["interruption"] = interruption
+    if relevance is not None:
+        payload["relevance"] = relevance
+    if thread_id is not None:
+        payload["threadId"] = thread_id
+    if image is not None:
+        payload["imageURL"] = image
+    if sender is not None:
+        payload["sender"] = sender
+    if wire_actions is not None:
+        payload["actions"] = wire_actions
+    if notif_id is not None:
+        payload["notifId"] = notif_id
     if data is not None:
         payload["data"] = data
 
@@ -117,6 +249,9 @@ class CarterClient:
         self._sock = MeshSocket(url=gateway_url, name=name, auth_token=token,
                                 channel=channel, role=role, can_broadcast=True,
                                 can_route=can_route, can_monitor=can_monitor)
+        #: The mesh channel — also the default tap-routing key notify() stamps on
+        #: pushes, so tapping one opens the pinned layout for this connection.
+        self.channel = channel
         # `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:
@@ -146,6 +281,11 @@ class CarterClient:
         self._broadcast_registered = False
         self._join_handler = None
         self._ack_commands = False
+        # Notification action-button plumbing: per-send callbacks keyed by
+        # (notifId, actionId), plus an optional catch-all. Fed by the app's flat
+        # `notif_action` broadcast when a user taps a button on a push.
+        self._notif_callbacks = {}
+        self._notif_action_handler = None
 
     def _open(self, payload):
         if self._session and isinstance(payload, dict) and E2EESession.is_envelope(payload):
@@ -190,6 +330,18 @@ class CarterClient:
     _PROTOCOL_BROADCASTS = ("control_sync_request", "control_snapshot", "command_ack")
 
     async def _dispatch_broadcast(self, data):
+        # Notification action taps (the app's flat `notif_action` frame) are kit
+        # plane, like protocol frames: dispatched to the per-send callback
+        # registered by notify(actions=...) and the on_notif_action catch-all,
+        # never to on_broadcast handlers.
+        if isinstance(data, dict) and data.get("msg_type") == "notif_action":
+            fn = self._notif_callbacks.get((data.get("notifId"), data.get("actionId")))
+            for handler in (fn, self._notif_action_handler):
+                if handler is not None:
+                    result = handler(data)
+                    if asyncio.iscoroutine(result):
+                        await result
+            return
         # 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
@@ -299,17 +451,88 @@ class CarterClient:
         reply = await self._sock.request(command, self._seal(data), timeout=timeout)
         return self._open(reply) if reply is not None else None
 
-    async def notify(self, title, body, *, channel=None, category=None,
-                     badge=None, sound="default", data=None):
+    def on_notif_action(self, handler):
+        """Catch-all for notification button taps: handler(data) gets the flat
+        `notif_action` frame `{"msg_type", "notifId", "actionId", "threadId"?}`.
+        Per-send callbacks passed via notify(actions=...) fire first."""
+        self._notif_action_handler = handler
+        self._ensure_broadcast_listener()
+
+    async def notify(self, title, body, *, subtitle=None, channel=None, category=None,
+                     badge=None, sound="default", interruption=None, criticality=None,
+                     relevance=None, thread_id=None, image=None, sender=None,
+                     actions=None, notif_id=None, data=None, encrypt=None,
+                     placeholder_title="", placeholder_body="New notification"):
         """Send a one-shot push to every device on the account. Requires `validator_url`
         and `session_jwt` to have been passed to the constructor (the mesh auth token is
-        NOT the session JWT — distinct credentials). Returns `{"sent": N, "stale": M}`."""
+        NOT the session JWT — distinct credentials). Returns
+        `{"sent": N, "stale": M, "notifId"?: id}`.
+
+        On top of `notify_http`'s fields this adds the mesh-connected conveniences:
+
+        - `channel` defaults to this client's mesh channel, so tapping the push opens
+          the pinned layout for this connection.
+        - `actions` may carry callbacks — `{"ack": ("Acknowledge", fn)}` or
+          `{"ack": {"name": "Acknowledge", "func": fn}}`; when the user taps the
+          button, the app broadcasts `notif_action` on the channel and the callback
+          fires with the flat frame. Best-effort: taps only arrive while the app holds
+          a live connection on that channel. A `notif_id` is minted per send to key
+          the dispatch (pass your own to override).
+        - `sender` (persona) defaults `thread_id` to the sender's name so avatar
+          grouping and thread grouping agree.
+        - `criticality` is an alias for `interruption`.
+        - E2EE: in a room (`room=True` + e2ee_key) the content fields — title, body,
+          subtitle, image, sender — are sealed into the `enc` envelope the app's push
+          extension decrypts on-device; APNs and the relay carry only
+          `placeholder_title`/`placeholder_body`. That is the default in a room
+          (`encrypt=None`); pass `encrypt=False` to send in the clear, `encrypt=True`
+          to fail loudly when no room cipher is available. Delivery hints
+          (interruption/relevance/thread/sound/badge/channel/actions) always ride in
+          the clear."""
         if not self._validator_url or not self._session_jwt:
             raise CarterNotifyError(0, "notify() requires validator_url and session_jwt "
                                        "on the CarterClient constructor")
+        if interruption is None:
+            interruption = criticality
+        if channel is None:
+            channel = self.channel
+        sender = _normalize_sender(sender)
+        if sender is not None and thread_id is None:
+            thread_id = sender["name"]
+        wire_actions, callbacks = _normalize_actions(actions)
+        if callbacks:
+            if notif_id is None:
+                notif_id = "n" + uuid.uuid4().hex[:16]
+            for aid, fn in callbacks.items():
+                self._notif_callbacks[(notif_id, aid)] = fn
+            self._ensure_broadcast_listener()
+
+        can_seal = self._session is not None and getattr(self._session, "is_group", False)
+        if encrypt is None:
+            encrypt = can_seal
+        elif encrypt and not can_seal:
+            raise CarterNotifyError(0, "encrypted notifications need a room cipher "
+                                       "(e2ee_key + room=True) — the push extension "
+                                       "only opens the group construction")
+        if encrypt:
+            sealed = {"title": title, "body": body}
+            if subtitle is not None:
+                sealed["subtitle"] = subtitle
+            if image is not None:
+                sealed["imageURL"] = image
+            if sender is not None:
+                sealed["sender"] = sender
+            data = dict(data or {})
+            data["enc"] = self._session.seal(sealed)
+            title, body = placeholder_title or "CAR-TER", placeholder_body
+            subtitle = image = sender = None
+
         return await asyncio.to_thread(
             notify_http, self._validator_url, self._session_jwt, title, body,
-            channel=channel, category=category, badge=badge, sound=sound, data=data)
+            subtitle=subtitle, channel=channel, category=category, badge=badge,
+            sound=sound, interruption=interruption, relevance=relevance,
+            thread_id=thread_id, image=image, sender=sender, actions=wire_actions,
+            notif_id=notif_id, data=data)
 
     async def refresh_device_token(self):
         """Re-mint this device's relay token from its refresh secret and apply it to the

{carterkit-0.6.0 → carterkit-0.7.0}/carterkit/codegen.py

@@ -60,6 +60,8 @@ def analyze_layout(layout: dict) -> dict:
         for s in ch.get("sync") or []:
             if not (isinstance(s, dict) and s.get("valuePath")):
                 continue
+            if s.get("method") in ("mqtt", "http", "sensor"):
+                continue          # app-direct (broker/REST/hardware) — no server serves it
             emits.setdefault(s.get("event") or "broadcast", set()).add(s["valuePath"])
             if not pushed and (s.get("event") or "broadcast") == "broadcast" and ch.get("id"):
                 pushes.append((ch["id"], s["valuePath"]))

{carterkit-0.6.0 → carterkit-0.7.0}/carterkit/connection.py

@@ -5,7 +5,7 @@ The ecosystem grew four shapes of "how do I connect":
   1. a layout's `connection` block (what the APP dials):
      ``{"url", "token"?, "mode"?, "e2eeKey"?, "identity": {"name","channel","role"}}``
   2. the QR pairing JSON (what the app scans): ``{"url","channel","role","token"?}``
-  3. the *Add Device* credential (what a HUB holds — the app's Members sheet emits
+  3. the *Add Hub* credential (what a HUB holds — the app's Layout hub (Hubs → Add Hub) emits
      it): ``{"url","channel","token","role","refresh","did","k"?,"validator"?}``
   4. `CarterClient` constructor kwargs.
 
@@ -190,7 +190,7 @@ class Connection:
         if self.kind == "account":
             raise ValueError(
                 "this connection is a Connect+ account-side block — it has no hub "
-                "credential. Mint one on the phone (Members → Add Device) and pass "
+                "credential. Mint one on the phone (Layout hub → Hubs → Add Hub) and pass "
                 "that JSON instead.")
         url = self.url if self.kind != "local" else f"ws://127.0.0.1:{self.port}"
         kw: dict = {