branchkit 0.1.1__tar.gz → 0.2.0__tar.gz

{branchkit-0.1.1 → branchkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: branchkit
-Version: 0.1.1
+Version: 0.2.0
 Summary: BranchKit plugin SDK for Python
 Author: BranchKit
 License-Expression: MIT

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/__init__.py

@@ -23,6 +23,7 @@ from . import proxy as _proxy
 _proxy.install_proxy_from_env()
 
 from .plugin import (
+    DetachedError,
     PluginCore,
     RecordingDisabledError,
     RpcCallError,
@@ -59,6 +60,7 @@ from .settings_route import method_post, method_url
 from .ui import (
     Expr,
     args,
+    js,
     confirm_button,
     expr,
     input_value,

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/commands.py

@@ -69,9 +69,10 @@ class CommandBuilder:
 
     def action(self, type: str, params: dict | None = None) -> "CommandBuilder":
         """Set the action fired on match. `type` is the action's type (a
-        built-in like "key" or a dotted plugin action); `params` are merged
-        into the action object."""
-        self._spec["action"] = {"type": type, **(params or {})}
+        built-in like "key" or a dotted plugin action); `params` nest under
+        the action object's `params` key — one dialect, see
+        DESIGN_ONE_PARAMS_DIALECT.md."""
+        self._spec["action"] = {"type": type, "params": params} if params else {"type": type}
         return self
 
     def requires_tags(self, *tags: str) -> "CommandBuilder":
@@ -102,9 +103,12 @@ class CommandBuilder:
         return self
 
     def discovery(self, mode: str) -> "CommandBuilder":
-        """Declare the command's prefix-discovery affordance ("prefix" or
-        "exclusive"). Valid only on a literal-prefix + single-tail-capture
-        pattern. See docs/design/DESIGN_DISCOVERABLE_PREFIX.md."""
+        """Declare the command's prefix-discovery affordance ("prefix",
+        "exclusive", or "select" — select points at entries via
+        platform-assigned alphabet codewords instead of their names). Valid
+        only on a literal-prefix + single-tail-capture pattern. See
+        docs/design/DESIGN_DISCOVERABLE_PREFIX.md and
+        DESIGN_SELECTION_PRIMITIVE.md."""
         self._spec["discovery"] = mode
         return self
 

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/contracts_gen.py

@@ -587,12 +587,15 @@ METHOD_PIPELINES_STOP = "pipelines.stop"  # since 0.1.0
 METHOD_PIPELINES_WARM = "pipelines.warm"  # since 0.1.0
 METHOD_PLUGIN_DATA_EXPORT = "plugin.data.export"  # since 0.1.0
 METHOD_PLUGIN_DEBUG = "plugin.debug"  # since 0.1.0
+METHOD_PLUGIN_REPORT_HEALTH = "plugin.report_health"  # since 0.1.0
 METHOD_PRIVACY_GET_RECORDING = "privacy.get_recording"  # stable, since 0.1.0
 METHOD_PRIVACY_SET_RECORDING = "privacy.set_recording"  # stable, since 0.1.0
 METHOD_PRIVILEGES_LIST = "privileges.list"  # since 0.1.0
 METHOD_PRIVILEGES_RELINQUISH = "privileges.relinquish"  # since 0.1.0
 METHOD_PRIVILEGES_REQUEST = "privileges.request"  # since 0.1.0
 METHOD_RECOGNITION_BIAS_APPLY = "recognition.bias.apply"  # since 0.1.0
+METHOD_RECOGNITION_BIAS_GET = "recognition.bias.get"  # since 0.1.0
+METHOD_RECOGNITION_BIAS_SET = "recognition.bias.set"  # since 0.1.0
 METHOD_RECOGNITION_REDECODE = "recognition.redecode"  # since 0.1.0
 METHOD_SELECTION_PICK = "selection.pick"  # since 0.1.0
 METHOD_SELECTION_SET = "selection.set"  # since 0.1.0

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/log_events_gen.py

@@ -108,7 +108,7 @@ LOG_EVENT_REGISTRY: dict[str, LogEventMeta] = {
     "native.window_skipped": {"name": "native.window_skipped", "summary": "World poller skipped a non-standard window (debug-level).", "since": "0.1.0", "source": "native", "severity": "debug", "redaction": "none"},
     "native.world_poller_event": {"name": "native.world_poller_event", "summary": "World poller lifecycle event (started, seeded, batch processed, idle).", "since": "0.1.0", "source": "native", "severity": "debug", "redaction": "none"},
     "operation.completed": {"name": "operation.completed", "summary": "An operation handler completed execution.", "since": "0.1.0", "source": "dispatch", "severity": "debug", "redaction": "none"},
-    "plugin.degraded": {"name": "plugin.degraded", "summary": "A managed plugin's RPC channel hit the consecutive-timeout threshold and was marked degraded.", "since": "0.1.0", "source": "plugins", "severity": "warn", "redaction": "none"},
+    "plugin.degraded": {"name": "plugin.degraded", "summary": "A plugin is running but not fully working — either its RPC channel hit the consecutive-timeout threshold (reason absent), or the plugin reported the fault itself via plugin.report_health (reason present).", "since": "0.1.0", "source": "plugins", "severity": "warn", "redaction": "none"},
     "plugin.diagnostic": {"name": "plugin.diagnostic", "summary": "A plugin emitted a warn- or error-level diagnostic via plugin.debug; cross-posted to actuator.log so plugin-level failures interleave with the actuator's view of dispatch / coordination.", "since": "0.2.0", "source": "plugins", "severity": "warn", "redaction": "none"},
     "plugin.exited": {"name": "plugin.exited", "summary": "A managed plugin process exited (clean or crashed).", "since": "0.1.0", "source": "plugins", "severity": "info", "redaction": "none"},
     "plugin.lifecycle_op": {"name": "plugin.lifecycle_op", "summary": "A plugin lifecycle operation (install, uninstall, update, reload, hot-reload, enable, disable).", "since": "0.1.0", "source": "plugins", "severity": "info", "redaction": "none"},

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/methods_gen.py

@@ -588,12 +588,15 @@ from .contracts_gen import (
     METHOD_PIPELINES_WARM,
     METHOD_PLUGIN_DATA_EXPORT,
     METHOD_PLUGIN_DEBUG,
+    METHOD_PLUGIN_REPORT_HEALTH,
     METHOD_PRIVACY_GET_RECORDING,
     METHOD_PRIVACY_SET_RECORDING,
     METHOD_PRIVILEGES_LIST,
     METHOD_PRIVILEGES_RELINQUISH,
     METHOD_PRIVILEGES_REQUEST,
     METHOD_RECOGNITION_BIAS_APPLY,
+    METHOD_RECOGNITION_BIAS_GET,
+    METHOD_RECOGNITION_BIAS_SET,
     METHOD_RECOGNITION_REDECODE,
     METHOD_SELECTION_PICK,
     METHOD_SELECTION_SET,
@@ -961,6 +964,8 @@ if TYPE_CHECKING:
         PrivilegesRequestResponse,
         ProcessInfo,
         RecognitionBiasApplyResponse,
+        RecognitionBiasGetResponse,
+        RecognitionBiasSetResponse,
         RecognitionRedecodeResponse,
         RedecodeItem,
         ReminderItem,
@@ -4198,10 +4203,11 @@ class MethodsMixin:
         result = await self.call(METHOD_PIPELINES_GRAMMAR, params)
         return result
 
-    async def pipelines_inject(self, event_type: str, name: str, data: Any | None = None) -> PipelinesInjectResponse:
+    async def pipelines_inject(self, event_type: str, name: str, stage: str, data: Any | None = None) -> PipelinesInjectResponse:
         params: dict[str, Any] = {
             "event_type": event_type,
             "name": name,
+            "stage": stage,
         }
         if data is not None:
             params["data"] = data
@@ -4261,6 +4267,14 @@ class MethodsMixin:
             params["tag"] = tag
         await self.call(METHOD_PLUGIN_DEBUG, params)
 
+    async def plugin_report_health(self, degraded: bool, reason: str | None = None) -> None:
+        params: dict[str, Any] = {
+            "degraded": degraded,
+        }
+        if reason is not None:
+            params["reason"] = reason
+        await self.call(METHOD_PLUGIN_REPORT_HEALTH, params)
+
     async def privacy_get_recording(self, name: str) -> PrivacyGetRecordingResponse:
         params: dict[str, Any] = {
             "name": name,
@@ -4304,6 +4318,20 @@ class MethodsMixin:
         result = await self.call(METHOD_RECOGNITION_BIAS_APPLY, params)
         return result
 
+    async def recognition_bias_get(self) -> RecognitionBiasGetResponse:
+        result = await self.call(METHOD_RECOGNITION_BIAS_GET)
+        return result
+
+    async def recognition_bias_set(self, enabled: bool | None = None, strength: float | None = None) -> RecognitionBiasSetResponse:
+        params: dict[str, Any] = {
+        }
+        if enabled is not None:
+            params["enabled"] = enabled
+        if strength is not None:
+            params["strength"] = strength
+        result = await self.call(METHOD_RECOGNITION_BIAS_SET, params)
+        return result
+
     async def recognition_redecode(self, items: list["RedecodeItem"], model: str, stage: str, max_active: int | None = None) -> RecognitionRedecodeResponse:
         params: dict[str, Any] = {
             "items": items,

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/plugin.py

@@ -20,7 +20,8 @@ from typing import Any, Callable
 
 from .closed_vocab_gen import ERROR_KIND_RECORDING_DISABLED
 from .contracts_gen import API_VERSION as _COMPILED_API_VERSION
-from .contracts_gen import HOOK_ON_ACTION
+from .contracts_gen import HOOK_ON_ACTION, HOOK_RENDER_SETTINGS
+
 from .actor import get_current_actor
 from .correlation import get_current_correlation, reset_correlation, set_correlation
 from .log import log
@@ -88,12 +89,28 @@ def error_kind_of(e: object) -> str | None:
     return e.kind if isinstance(e, RpcCallError) else None
 
 
+class DetachedError(RuntimeError):
+    """Raised by every call on a detached plugin (Plugin(detached=True))."""
+
+    def __init__(self, method: str) -> None:
+        super().__init__(f"detached plugin: no platform behind {method!r}")
+
+
 class PluginCore:
+
     """Transport + dispatch. The public `Plugin` class (see `__init__.py`)
     layers the generated method wrappers and the façade mixins on top."""
 
-    def __init__(self) -> None:
-        self._plugin_id: str = os.environ.get("BRANCHKIT_PLUGIN_ID", "unknown")
+    def __init__(self, *, detached: bool = False) -> None:
+        # detached: a plugin with no platform behind it, for tests. It never
+        # touches stdin or stdout: every call raises DetachedError at once,
+        # notifications go nowhere, mirrors never fetch, run() returns
+        # immediately. A host built on it exercises the plugin's own logic
+        # without a live actuator; swap a seam or a mirror for the platform
+        # behaviour a test needs.
+        self._detached = detached
+        self._plugin_id: str = "detached" if detached else os.environ.get("BRANCHKIT_PLUGIN_ID", "unknown")
+
         self._handlers: dict[str, Callable] = {}
         self._listeners: dict[str, list[Callable]] = {}
         # on_pattern registrations, in registration order. A list rather than
@@ -102,6 +119,13 @@ class PluginCore:
         self._pattern_listeners: list[tuple[str, Callable]] = []
         self._pending: dict[int, asyncio.Future] = {}
         self._action_handlers: dict[str, Callable] | None = None
+        # Non-None once settings_tab has installed the SDK's own
+        # render_settings handler; _settings_mirrors are refreshed by that
+        # handler before every render (settings.py).
+        self._settings_tabs: dict[str, Callable] | None = None
+        self._settings_css = ""
+        self._settings_mirrors: list = []
+
         self._next_id = 1
         self._closed = False
         self._loop: asyncio.AbstractEventLoop | None = None
@@ -139,7 +163,13 @@ class PluginCore:
         (`plugin.handle("m", fn)`) or as a decorator (`@plugin.handle("m")`).
 
         `handle("on_action", ...)` and `handle_action(...)` are mutually
-        exclusive — both install a handler for the same RPC method."""
+        exclusive — both install a handler for the same RPC method.
+
+        `render_settings` is not registrable here at all: the SDK owns that
+        hook and installs it through `settings_tab`, one renderer per
+        manifest tab. `handle` raises on it so a plugin cannot bypass the
+        dispatch."""
+
         if fn is None:
             def deco(f):
                 self.handle(method, f)
@@ -149,9 +179,14 @@ class PluginCore:
             raise RuntimeError(
                 'plugin-sdk-py: cannot mix handle("on_action", ...) and handle_action(...) — pick one'
             )
+        if method == HOOK_RENDER_SETTINGS:
+            raise RuntimeError(
+                "plugin-sdk-py: render_settings is the SDK's hook — register each tab with settings_tab(key, fn)"
+            )
         self._handlers[method] = fn
         return fn
 
+
     def handle_action(self, action: str, fn: Callable | None = None):
         """Register a handler for a single dispatched action type. The SDK
         installs an internal on_action handler that demuxes by
@@ -249,10 +284,13 @@ class PluginCore:
         """Send a request to the actuator and wait for the response.
         Default timeout 10s (T1); override per call (T3). Raises
         RpcCallError for wire errors, TimeoutError on expiry."""
+        if self._detached:
+            raise DetachedError(method)
         if self._closed:
             raise RuntimeError("plugin shutting down")
         loop = asyncio.get_running_loop()
         call_id = self._next_id
+
         self._next_id += 1
         fut: asyncio.Future = loop.create_future()
         self._pending[call_id] = fut
@@ -318,8 +356,12 @@ class PluginCore:
         and block until shutdown. Incoming requests are held until run()
         is called (L4)."""
         self._loop = asyncio.get_running_loop()
+        if self._detached:
+            self._ready.set()
+            return
         log(self._plugin_id, "started (JSON-RPC over stdio)")
 
+
         # Graceful SIGTERM/SIGINT (L3).
         for sig in (signal.SIGTERM, signal.SIGINT):
             try:
@@ -359,8 +401,9 @@ class PluginCore:
     # --- Internal ---
 
     def _write(self, msg: dict) -> None:
-        if self._closed:
+        if self._closed or self._detached:
             return
+
         line = json.dumps(msg, separators=(",", ":")) + "\n"
         with self._write_lock:
             try:

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/settings.py

@@ -9,16 +9,23 @@ from __future__ import annotations
 
 from typing import Any, Callable
 
+from .contracts_gen import HOOK_RENDER_SETTINGS
 from .log import log
 
 
+
 class SettingsMirror:
     def __init__(self, plugin, name: str):
         # Internal — use plugin.settings(name).
         self._plugin = plugin
         self._name = name
         self._mirror = plugin.mirror_collection(name)
+        # The SDK's render_settings hook refreshes every settings mirror
+        # before a tab draws (settings_tab) — the read-through render paths
+        # used to hand-roll.
+        plugin._settings_mirrors.append(self)
         self._val: dict | None = None
+
         self._on_change: list[Callable] = []
         self_id = plugin.id
 
@@ -82,16 +89,72 @@ class SettingsMirror:
         )
         await self.refresh()
 
-    async def load(self) -> dict | None:
-        """The composed settings via a synchronous read-through. Use at the
-        top of render paths: a render must read state at least as fresh as
-        whatever triggered it."""
-        await self.refresh()
-        return self.get()
-
 
 class SettingsMixin:
     def settings(self, name: str) -> SettingsMirror:
         """Typed mirror of a `preset: settings` collection. Must be called
         before `run()` so the initial fetch lands."""
         return SettingsMirror(self, name)
+
+    def settings_tab(self, key: str, fn: Callable | None = None):
+        """Register the renderer for the manifest-declared settings tab
+        `key`. Usable directly (`plugin.settings_tab("k", fn)`) or as a
+        decorator (`@plugin.settings_tab("k")`). The renderer takes the
+        render_settings params and returns the tab's HTML FRAGMENT — the
+        platform's frame owns the container it is morphed into — and the
+        SDK attaches the stylesheet registered with `settings_css`. Plain
+        `def` or `async def`, as with `handle`.
+
+        The first call installs the SDK's own `render_settings` handler,
+        which on every render (1) refreshes every settings mirror created
+        with `settings()`, so the render reads state at least as fresh as
+        whatever woke it; (2) dispatches on `tab_key` — a key with no
+        renderer is an error, which the platform shows as the tab's error
+        state instead of a blank body; (3) returns the fragment with the
+        registered stylesheet.
+
+        A settings method returns None. The platform's method proxy
+        refuses any result — 422 with the `settings-method-result`
+        diagnostic, shown as a banner in the tab and logged to the plugin's
+        log — and re-renders the tab: a method changes state, and the
+        re-render that follows draws it.
+
+        This is the only way to install a render_settings handler:
+        `handle("render_settings", ...)` raises, so every tab goes through
+        this dispatch."""
+        if fn is None:
+            def deco(f):
+                self.settings_tab(key, f)
+                return f
+            return deco
+        if self._settings_tabs is None:
+            self._settings_tabs = {}
+            self._handlers[HOOK_RENDER_SETTINGS] = self._render_settings_tab
+        self._settings_tabs[key] = fn
+        return fn
+
+    def settings_css(self, css: str) -> None:
+        """Register the stylesheet returned with every tab this plugin
+        renders. One sheet per plugin: the platform places it in a
+        `<style>` element it owns, outside the morph target."""
+        self._settings_css = css
+
+    async def _render_settings_tab(self, params: Any) -> dict:
+        req = params if isinstance(params, dict) else {}
+        key = req.get("tab_key", "")
+        fn = (self._settings_tabs or {}).get(key)
+        if fn is None:
+            raise RuntimeError(f'no renderer registered for settings tab "{key}"')
+        # Read through before drawing. A refresh failure is logged, not
+        # fatal: the mirror keeps its last snapshot and the tab still draws.
+        for m in list(self._settings_mirrors):
+            try:
+                await m.refresh()
+            except Exception as e:
+                log(self.id, f"settings read-through failed: {e}")
+        html = await self._invoke(fn, req)
+        resp = {"html": html}
+        if self._settings_css:
+            resp["css"] = self._settings_css
+        return resp
+

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/types_gen.py

@@ -242,6 +242,7 @@ DirectoryEntry = TypedDict("DirectoryEntry", {
 
 DiscoverItem = TypedDict("DiscoverItem", {
     "id": str,
+    "speakable": bool,
     "subtitle": NotRequired[str],
     "tag": str,
     "title": str,
@@ -4211,6 +4212,7 @@ PipelinesInjectRequest = TypedDict("PipelinesInjectRequest", {
     "data": NotRequired[Any],
     "event_type": str,
     "name": str,
+    "stage": str,
 })
 
 PipelinesInjectResponse = TypedDict("PipelinesInjectResponse", {
@@ -4272,6 +4274,15 @@ PluginDebugResponse = TypedDict("PluginDebugResponse", {
     "ok": bool,
 })
 
+PluginReportHealthRequest = TypedDict("PluginReportHealthRequest", {
+    "degraded": bool,
+    "reason": NotRequired[str],
+})
+
+PluginReportHealthResponse = TypedDict("PluginReportHealthResponse", {
+    "ok": bool,
+})
+
 PrivacyGetRecordingRequest = TypedDict("PrivacyGetRecordingRequest", {
     "name": str,
 })
@@ -4320,6 +4331,23 @@ RecognitionBiasApplyResponse = TypedDict("RecognitionBiasApplyResponse", {
     "previous_provenance": str,
 })
 
+RecognitionBiasGetResponse = TypedDict("RecognitionBiasGetResponse", {
+    "enabled": bool,
+    "provenance": str,
+    "strength": float,
+})
+
+RecognitionBiasSetRequest = TypedDict("RecognitionBiasSetRequest", {
+    "enabled": NotRequired[bool],
+    "strength": NotRequired[float],
+})
+
+RecognitionBiasSetResponse = TypedDict("RecognitionBiasSetResponse", {
+    "enabled": bool,
+    "provenance": str,
+    "strength": float,
+})
+
 RecognitionRedecodeRequest = TypedDict("RecognitionRedecodeRequest", {
     "items": list["RedecodeItem"],
     "max_active": NotRequired[int],
@@ -4738,6 +4766,7 @@ PipelineWarmedEventParams = TypedDict("PipelineWarmedEventParams", {
 PluginDegradedEventParams = TypedDict("PluginDegradedEventParams", {
     "consecutive_timeouts": int,
     "plugin_id": str,
+    "reason": NotRequired[str],
 })
 
 # Payload of the `_platform.plugin.disabled` event.

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit/ui.py

@@ -138,8 +138,11 @@ def confirm_button(
     confirm_click = f"{method_post(method, payload_str)}; {sig} = false"
     if then:
         confirm_click += f"; {then}"
-    danger_style = f"{style or ''}color:#c44;border-color:#c44;"
-    confirm = _button(confirm_text, confirm_click, class_, danger_style)
+    # The confirm click is the destructive one; `danger` is the platform
+    # stylesheet's variant class (button.danger), never an inline colour.
+    danger_class = f"{class_ or ''} danger".strip()
+    confirm = _button(confirm_text, confirm_click, danger_class, style)
+
     cancel = _button("Cancel", f"{sig} = false", class_, style)
     return (
         f'<span data-signals:c_{sig_key}__ifmissing="false">'
@@ -147,3 +150,11 @@ def confirm_button(
         f'<span data-show="{sig}" style="display:none;">{confirm}{cancel}</span>'
         f"</span>"
     )
+
+
+def js(v: Any) -> str:
+    """Marshal one value to a JavaScript literal for a Datastar expression —
+    a string becomes a quoted string, a bool ``true``, a number itself. The
+    value-position twin of ``args``: a user string spliced into
+    ``$sig = '...'`` must not be able to end the quote."""
+    return json.dumps(v)

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: branchkit
-Version: 0.1.1
+Version: 0.2.0
 Summary: BranchKit plugin SDK for Python
 Author: BranchKit
 License-Expression: MIT

{branchkit-0.1.1 → branchkit-0.2.0}/branchkit.egg-info/SOURCES.txt

@@ -30,4 +30,5 @@ branchkit.egg-info/SOURCES.txt
 branchkit.egg-info/dependency_links.txt
 branchkit.egg-info/top_level.txt
 tests/test_collection.py
-tests/test_kernel.py
+tests/test_kernel.py
+tests/test_settings_tabs.py

{branchkit-0.1.1 → branchkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "branchkit"
-version = "0.1.1"
+version = "0.2.0"
 description = "BranchKit plugin SDK for Python"
 readme = "README.md"
 license = "MIT"

{branchkit-0.1.1 → branchkit-0.2.0}/tests/test_kernel.py

@@ -42,7 +42,8 @@ class TestCommandBuilder(unittest.TestCase):
             .build()
         )
         self.assertEqual(spec["pattern"], ["open", ["tab", "window"], "<t:ts>", "<n:text>"])
-        self.assertEqual(spec["action"], {"type": "browser.open", "force": True})
+        # One params dialect: the payload nests under "params", never flat.
+        self.assertEqual(spec["action"], {"type": "browser.open", "params": {"force": True}})
         self.assertEqual(spec["requires_tags"], ["a"])
         self.assertTrue(spec["cancels_bridge"])
         self.assertEqual(spec["discovery"], "exclusive")
@@ -150,6 +151,15 @@ class TestUi(unittest.TestCase):
         html = ui.confirm_button("Delete", "del_item", payload={"id": "x"})
         self.assertIn("__ifmissing", html)
         self.assertIn("Really delete?", html)
+        self.assertIn('class="danger"', html)
+        self.assertNotIn("#c44", html)
+        self.assertIn('class="sc-btn danger"', ui.confirm_button("Delete", "d", class_="sc-btn"))
+
+    def test_js_marshals_values(self):
+        self.assertEqual(ui.js("it's"), '"it\'s"')
+        self.assertEqual(ui.js(True), "true")
+        self.assertEqual(ui.js(3), "3")
+
 
 
 class TestListOpts(unittest.TestCase):
@@ -299,3 +309,17 @@ class TestListenerHelpers(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestDetachedPlugin(unittest.IsolatedAsyncioTestCase):
+    """The no-platform contract tests build hosts on: calls raise at once,
+    notify and run are inert, a settings mirror can be constructed."""
+
+    async def test_detached_contract(self):
+        p = branchkit.Plugin(detached=True)
+        with self.assertRaises(branchkit.DetachedError):
+            await p.call("collection.get", {"name": "x"})
+        p.notify("events.emit", {"x": 1})  # goes nowhere, raises nothing
+        m = p.settings("plugin.test.config")
+        self.assertFalse(m.ready)
+        await asyncio.wait_for(p.run(), 1.0)

branchkit-0.2.0/tests/test_settings_tabs.py

@@ -0,0 +1,76 @@
+"""The SDK-owned render_settings hook: one renderer per tab key, the
+registered stylesheet on every response, an error for a key nobody
+registered, and every settings mirror refreshed before the tab draws."""
+
+import unittest
+
+import branchkit
+
+
+def fake_plugin(store: dict) -> branchkit.Plugin:
+    """A Plugin whose actuator calls are answered in-process: the composed
+    settings read serves `store`."""
+    p = branchkit.Plugin()
+
+    async def call(method, params=None, *args, **kwargs):
+        if method == "collection.get":
+            return {"name": params["name"], "data": store}
+        raise AssertionError(f"unexpected method {method}")
+
+    p.call = call  # type: ignore[method-assign]
+    return p
+
+
+class TestSettingsTabs(unittest.IsolatedAsyncioTestCase):
+    async def render(self, p, tab_key):
+        fn = p._handlers["render_settings"]
+        return await fn({"tab_key": tab_key, "search": ""})
+
+    async def test_dispatch_css_and_read_through(self):
+        store = {"editor": "stale"}
+        p = fake_plugin(store)
+        mirror = p.settings("plugin.test.config")
+        p.settings_css(".alpha{}")
+
+        @p.settings_tab("alpha")
+        def alpha(req):  # plain def — offloaded like any handler
+            return f'<p id="alpha">{(mirror.get() or {}).get("editor", "")}</p>'
+
+        @p.settings_tab("beta")
+        async def beta(req):
+            return f'<p id="beta">{req["tab_key"]}</p>'
+
+        # The store moved behind the mirror's back (no collection.updated);
+        # the render must still see the current value.
+        store["editor"] = "fresh"
+        resp = await self.render(p, "alpha")
+        self.assertEqual(resp, {"html": '<p id="alpha">fresh</p>', "css": ".alpha{}"})
+        resp = await self.render(p, "beta")
+        self.assertEqual(resp["html"], '<p id="beta">beta</p>')
+        with self.assertRaisesRegex(RuntimeError, '"nope"'):
+            await self.render(p, "nope")
+
+    async def test_renderer_error_propagates(self):
+        p = fake_plugin({})
+
+        @p.settings_tab("broken")
+        def broken(req):
+            raise ValueError("cannot draw")
+
+        with self.assertRaisesRegex(ValueError, "cannot draw"):
+            await self.render(p, "broken")
+
+    # The tab API is the only way in: a hand-written render_settings handler
+    # raises at registration whether or not a tab was registered first.
+    def test_handle_rejects_render_settings(self):
+        a = fake_plugin({})
+        with self.assertRaisesRegex(RuntimeError, "settings_tab"):
+            a.handle("render_settings", lambda params: {})
+        b = fake_plugin({})
+        b.settings_tab("x", lambda req: "")
+        with self.assertRaisesRegex(RuntimeError, "settings_tab"):
+            b.handle("render_settings", lambda params: {})
+
+
+if __name__ == "__main__":
+    unittest.main()