flyrail 0.1.0__tar.gz

flyrail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Lipinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flyrail-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: flyrail
+Version: 0.1.0
+Summary: Bring-your-own-frontend server-driven UI core (reactpy-style API, transport agnostic)
+Author-email: Aaron Lipinski <kris.lipinski@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/krisl/flyrail
+Project-URL: Repository, https://github.com/krisl/flyrail
+Keywords: ui,server-driven-ui,websocket,asgi
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flyrail
+
+Bring-your-own-frontend server-driven UI with a reactpy-style Python API.
+Python declares the UI, your React+MUI app renders it, your socket carries
+it, your tick drives it.
+
+## Why this exists
+
+`reactpy` owns the whole React tree and its own socket protocol. `rjsf`
+owns form rendering but not arbitrary layouts. flyrail splits the problem:
+
+- **Python** (`flyrail/`): declarative element helpers, per-session handler
+  registry, per-component memoisation, gated keyed-list diffing, slot
+  fast-path. Zero dependencies.
+- **JS** (`js/`, `flyrail-renderer`): namespace component registry
+  (`import * as MUI`), patch applier, client store with resync, debounced
+  inputs. Zero dependencies (React is a peer).
+
+See [docs/features.md](docs/features.md) for what each capability buys you,
+with a runnable example each.
+
+## Message flow
+
+```
+tick:   render(state) -> tree -> diff -> [] | patch ops -> {chan:ui,type:patch,seq,ops}
+click:  {chan:ui,type:action,handlerId,event?} -> dispatch -> mutate state -> next tick emits
+hot:    set_slot(name, value) -> {chan:ui,type:slot} (bypasses diff)
+gap:    seq skip -> resync-request -> snapshot(state, seq) -> {chan:ui,type:snapshot,tree}
+```
+
+## Python quickstart
+
+```python
+from flyrail import Layout, Stack, Text, Button
+from flyrail.transport import ui_envelope_patch
+
+class Panel:
+    def render(self, s):
+        return Stack(
+            Text(f"speed: {s.speed}"),
+            Button("Stop", on_click=self.stop),  # like reactpy
+        )
+    def stop(self, state, event):
+        state.speed = 0
+
+layout = Layout(Panel().render, allowed_types={"Stack", "Text", "Button"})
+seq = 0
+def on_tick(state):
+    global seq
+    if ops := layout.tick(state):  # [] on idle ticks: send nothing
+        seq += 1
+        broadcast(ui_envelope_patch(ops, seq))
+
+def on_ws(msg, state):
+    if msg.get("chan") == "ui" and msg.get("type") == "action":
+        layout.dispatch(msg["handlerId"], state, msg.get("event"))
+    elif msg.get("type") == "resync-request":
+        broadcast(layout.snapshot(state, seq + 1))
+```
+
+## JS quickstart
+
+```tsx
+import * as MUI from '@mui/material';
+import { createRenderer } from 'flyrail-renderer';
+import { createStore } from 'flyrail-renderer/store';
+
+const { ServerNode } = createRenderer({ ...MUI });  // auto-registered, no switch
+const store = createStore({ onResync: (req) => ws.send(JSON.stringify(req)) });
+ws.onmessage = (e) => store.ingest(JSON.parse(e.data));
+// render store.getTree() via <ServerNode node={tree} send={...} />
+```
+
+## Hosting (pick one)
+
+```python
+# 1. Fixed tick you own: Driver replaces the hand-rolled seq counter.
+from flyrail import Driver
+driver = Driver(layout)
+def on_tick(state, version):
+    if env := driver.flush(state, version):
+        broadcast(env)
+
+# 2. Async host: raw ASGI app, one session per connection. FastAPI:
+#    from fastapi import WebSocket; await create_ws_app(Panel().render)(scope, receive, send)
+#    (or mount in any ASGI framework; no fastapi dependency in this package)
+from flyrail import create_ws_app
+app = create_ws_app(Panel().render, state_factory=Sim,
+                    on_message=lambda data, state: handle_telemetry(data))
+
+# 3. Naive host (no loop at all): invalidate + flush around every message.
+driver.invalidate()
+if env := driver.flush(state):
+    send(env)
+```
+
+## Best practices
+
+1. **Stable keys, never indexes.** `key=item.id` on every list child, both
+   sides: Python handler ids embed the key, React reconciles by it. Reorder
+   without keys = full remount + lost focus. Keys must be unique among
+   siblings: duplicates share one handler id (last registration wins) and
+   components reject them, plain nodes do not.
+2. **Slots for tick-rate values.** Table rows, labels, progress: `Slot("rows")`
+   + `set_slot()` bypass the tree diff. Structure goes through patches (rare),
+   values through slots (every tick).
+3. **Allowlist both ends.** Python `allowed_types={...}` rejects unknown node
+   types; JS `isKnownComponent` renders only functions (filters MUI's
+   `colors`, `createTheme`, etc.). Never render `registry[arbitraryString]`.
+4. **One render per tick, send only on change.** `tick()` then `if ops:`.
+   Hash-gating makes idle ticks free.
+5. **Inputs debounce client-side** (150ms default). Server never sees
+   keystroke storms; use `flush()` on submit.
+6. **Caller-owned seq, snapshot on gaps.** The tick loop numbers patches; the
+   store drops stale/duplicates and answers gaps with one snapshot round-trip.
+7. **Keep `render(state)` pure and cheap.** No DB, no IO: derive from the
+   already-computed tick state. One `Layout` per session.
+8. **Safe event defaults, names like the DOM.** `preventDefault` is true
+   unless opted out (a reload is session death); `stopPropagation` stays
+   opt-in; `throttleMs` rate-caps sliders and guards double-submit. Same
+   names as the browser, defaults chosen for the socket.
+9. **Mark renders `@pure`, version host state.** Pure renders skip render
+   CPU when the version is unchanged (unmarked always re-render: correct by
+   default). `strict=True` double-renders in dev to catch nondeterminism.
+10. **Component-local UI state via hooks.** `use_state`/`use_memo` inside
+    `@component` bodies keeps collapsed flags and drafts out of tick state;
+    setters schedule through `invalidate()`. Distinct `key=` per instance,
+    hooks unconditional and order-stable, or it raises loudly. Effect
+    cleanups that raise abort the render instead of being swallowed.
+11. **Async handlers via `adispatch`.** Handlers may be `async def` (e.g.
+    `await db.save()` on click); sync `dispatch` refuses them loudly instead
+    of silently dropping the coroutine. Pattern: `await adispatch(...)`,
+    then `invalidate()`.
+
+## Docs
+
+- [How it works](docs/how-it-works.md) — architecture, tick/action/resync
+  sequences, render pipeline, hook slots, scheduling, message catalog.
+
+## Layout
+
+```
+flyrail/          Python core (stdlib only)
+  core.py         Stack/Text/Button/TextField/Slot, @component, @pure
+  hooks.py        use_state/use_memo keyed slots
+  layout.py       registry + diff + dispatch + slots + snapshot
+  driver.py       dirty-flag scheduling for tick/async/naive hosts
+  asgi.py         framework-free websocket sessions
+  transport.py    multiplex envelope + tick sketch
+js/               flyrail-renderer (zero-dep ESM + tsx)
+  protocol.mjs    envelopes, applyOps, debounce (node-tested)
+  store.mjs       seq tracking, gap->resync, slots (node-tested)
+  ServerNode.tsx  MUI-bound renderer (imports protocol.mjs)
+example/          hmi_demo.py runnable narrative of the wire
+tests/            focused unittest suites + public-API loopback
+```
+
+## Tests
+
+```
+PYTHONPATH=. python3 -m unittest discover -s tests -v   # 67 tests
+node --test js/protocol.test.mjs js/store.test.mjs      # 24 tests
+PYTHONPATH=. python3 example/hmi_demo.py                 # narrated wire demo
+```
+
+## Non-goals / roadmap
+
+- Not a form validator (use your backend validation + error slots), not a
+  JSON-Schema renderer (see rjsf), not a full reactpy replacement (sync
+  core with no async effects; bring your own frontend instead of an
+  owned tree).
+- Roadmap: vitest + React Testing Library for `ServerNode`, `byId/order`
+  maps for huge reorderable lists, keystroke `ackSeq` if loss-less input sync
+  is ever needed, registry packaging.

flyrail-0.1.0/README.md

@@ -0,0 +1,174 @@
+# flyrail
+
+Bring-your-own-frontend server-driven UI with a reactpy-style Python API.
+Python declares the UI, your React+MUI app renders it, your socket carries
+it, your tick drives it.
+
+## Why this exists
+
+`reactpy` owns the whole React tree and its own socket protocol. `rjsf`
+owns form rendering but not arbitrary layouts. flyrail splits the problem:
+
+- **Python** (`flyrail/`): declarative element helpers, per-session handler
+  registry, per-component memoisation, gated keyed-list diffing, slot
+  fast-path. Zero dependencies.
+- **JS** (`js/`, `flyrail-renderer`): namespace component registry
+  (`import * as MUI`), patch applier, client store with resync, debounced
+  inputs. Zero dependencies (React is a peer).
+
+See [docs/features.md](docs/features.md) for what each capability buys you,
+with a runnable example each.
+
+## Message flow
+
+```
+tick:   render(state) -> tree -> diff -> [] | patch ops -> {chan:ui,type:patch,seq,ops}
+click:  {chan:ui,type:action,handlerId,event?} -> dispatch -> mutate state -> next tick emits
+hot:    set_slot(name, value) -> {chan:ui,type:slot} (bypasses diff)
+gap:    seq skip -> resync-request -> snapshot(state, seq) -> {chan:ui,type:snapshot,tree}
+```
+
+## Python quickstart
+
+```python
+from flyrail import Layout, Stack, Text, Button
+from flyrail.transport import ui_envelope_patch
+
+class Panel:
+    def render(self, s):
+        return Stack(
+            Text(f"speed: {s.speed}"),
+            Button("Stop", on_click=self.stop),  # like reactpy
+        )
+    def stop(self, state, event):
+        state.speed = 0
+
+layout = Layout(Panel().render, allowed_types={"Stack", "Text", "Button"})
+seq = 0
+def on_tick(state):
+    global seq
+    if ops := layout.tick(state):  # [] on idle ticks: send nothing
+        seq += 1
+        broadcast(ui_envelope_patch(ops, seq))
+
+def on_ws(msg, state):
+    if msg.get("chan") == "ui" and msg.get("type") == "action":
+        layout.dispatch(msg["handlerId"], state, msg.get("event"))
+    elif msg.get("type") == "resync-request":
+        broadcast(layout.snapshot(state, seq + 1))
+```
+
+## JS quickstart
+
+```tsx
+import * as MUI from '@mui/material';
+import { createRenderer } from 'flyrail-renderer';
+import { createStore } from 'flyrail-renderer/store';
+
+const { ServerNode } = createRenderer({ ...MUI });  // auto-registered, no switch
+const store = createStore({ onResync: (req) => ws.send(JSON.stringify(req)) });
+ws.onmessage = (e) => store.ingest(JSON.parse(e.data));
+// render store.getTree() via <ServerNode node={tree} send={...} />
+```
+
+## Hosting (pick one)
+
+```python
+# 1. Fixed tick you own: Driver replaces the hand-rolled seq counter.
+from flyrail import Driver
+driver = Driver(layout)
+def on_tick(state, version):
+    if env := driver.flush(state, version):
+        broadcast(env)
+
+# 2. Async host: raw ASGI app, one session per connection. FastAPI:
+#    from fastapi import WebSocket; await create_ws_app(Panel().render)(scope, receive, send)
+#    (or mount in any ASGI framework; no fastapi dependency in this package)
+from flyrail import create_ws_app
+app = create_ws_app(Panel().render, state_factory=Sim,
+                    on_message=lambda data, state: handle_telemetry(data))
+
+# 3. Naive host (no loop at all): invalidate + flush around every message.
+driver.invalidate()
+if env := driver.flush(state):
+    send(env)
+```
+
+## Best practices
+
+1. **Stable keys, never indexes.** `key=item.id` on every list child, both
+   sides: Python handler ids embed the key, React reconciles by it. Reorder
+   without keys = full remount + lost focus. Keys must be unique among
+   siblings: duplicates share one handler id (last registration wins) and
+   components reject them, plain nodes do not.
+2. **Slots for tick-rate values.** Table rows, labels, progress: `Slot("rows")`
+   + `set_slot()` bypass the tree diff. Structure goes through patches (rare),
+   values through slots (every tick).
+3. **Allowlist both ends.** Python `allowed_types={...}` rejects unknown node
+   types; JS `isKnownComponent` renders only functions (filters MUI's
+   `colors`, `createTheme`, etc.). Never render `registry[arbitraryString]`.
+4. **One render per tick, send only on change.** `tick()` then `if ops:`.
+   Hash-gating makes idle ticks free.
+5. **Inputs debounce client-side** (150ms default). Server never sees
+   keystroke storms; use `flush()` on submit.
+6. **Caller-owned seq, snapshot on gaps.** The tick loop numbers patches; the
+   store drops stale/duplicates and answers gaps with one snapshot round-trip.
+7. **Keep `render(state)` pure and cheap.** No DB, no IO: derive from the
+   already-computed tick state. One `Layout` per session.
+8. **Safe event defaults, names like the DOM.** `preventDefault` is true
+   unless opted out (a reload is session death); `stopPropagation` stays
+   opt-in; `throttleMs` rate-caps sliders and guards double-submit. Same
+   names as the browser, defaults chosen for the socket.
+9. **Mark renders `@pure`, version host state.** Pure renders skip render
+   CPU when the version is unchanged (unmarked always re-render: correct by
+   default). `strict=True` double-renders in dev to catch nondeterminism.
+10. **Component-local UI state via hooks.** `use_state`/`use_memo` inside
+    `@component` bodies keeps collapsed flags and drafts out of tick state;
+    setters schedule through `invalidate()`. Distinct `key=` per instance,
+    hooks unconditional and order-stable, or it raises loudly. Effect
+    cleanups that raise abort the render instead of being swallowed.
+11. **Async handlers via `adispatch`.** Handlers may be `async def` (e.g.
+    `await db.save()` on click); sync `dispatch` refuses them loudly instead
+    of silently dropping the coroutine. Pattern: `await adispatch(...)`,
+    then `invalidate()`.
+
+## Docs
+
+- [How it works](docs/how-it-works.md) — architecture, tick/action/resync
+  sequences, render pipeline, hook slots, scheduling, message catalog.
+
+## Layout
+
+```
+flyrail/          Python core (stdlib only)
+  core.py         Stack/Text/Button/TextField/Slot, @component, @pure
+  hooks.py        use_state/use_memo keyed slots
+  layout.py       registry + diff + dispatch + slots + snapshot
+  driver.py       dirty-flag scheduling for tick/async/naive hosts
+  asgi.py         framework-free websocket sessions
+  transport.py    multiplex envelope + tick sketch
+js/               flyrail-renderer (zero-dep ESM + tsx)
+  protocol.mjs    envelopes, applyOps, debounce (node-tested)
+  store.mjs       seq tracking, gap->resync, slots (node-tested)
+  ServerNode.tsx  MUI-bound renderer (imports protocol.mjs)
+example/          hmi_demo.py runnable narrative of the wire
+tests/            focused unittest suites + public-API loopback
+```
+
+## Tests
+
+```
+PYTHONPATH=. python3 -m unittest discover -s tests -v   # 67 tests
+node --test js/protocol.test.mjs js/store.test.mjs      # 24 tests
+PYTHONPATH=. python3 example/hmi_demo.py                 # narrated wire demo
+```
+
+## Non-goals / roadmap
+
+- Not a form validator (use your backend validation + error slots), not a
+  JSON-Schema renderer (see rjsf), not a full reactpy replacement (sync
+  core with no async effects; bring your own frontend instead of an
+  owned tree).
+- Roadmap: vitest + React Testing Library for `ServerNode`, `byId/order`
+  maps for huge reorderable lists, keystroke `ackSeq` if loss-less input sync
+  is ever needed, registry packaging.

flyrail-0.1.0/flyrail/__init__.py

@@ -0,0 +1,13 @@
+"""flyrail - BYOF server-driven UI core.
+
+Python API is reactpy-style but transport/V DOM agnostic:
+  - you build dict trees with helpers (Stack, Text, Button, ...)
+  - Layout.render(state) replaces callables with {"handlerId": ...} descriptors
+"""
+from .core import component, pure, Slot, Stack, Text, Button, TextField
+from .layout import Layout
+from .driver import Driver
+from .hooks import use_state, use_memo, use_effect
+from .asgi import create_ws_app
+
+__all__ = ["component", "pure", "Slot", "Stack", "Text", "Button", "TextField", "Layout", "Driver", "use_state", "use_memo", "use_effect", "create_ws_app"]

flyrail-0.1.0/flyrail/asgi.py

@@ -0,0 +1,77 @@
+"""Framework-free ASGI websocket adapter: the async-host recipe.
+
+One state + Driver + Layout per connection; no dependency beyond stdlib.
+FastAPI/Starlette/Django-Channels users mount this where they handle
+websockets (see README Hosting); everyone else copies the 30-line shape.
+"""
+from __future__ import annotations
+import asyncio
+import inspect
+import json
+from typing import Any, Callable
+
+from .driver import Driver
+from .layout import Layout
+
+
+def create_ws_app(
+    render_fn: Callable[[Any], dict],
+    *,
+    state_factory: Callable[[], Any] = dict,
+    version_fn: Callable[[], Any] | None = None,
+    allowed_types: set[str] | None = None,
+    strict: bool = False,
+    on_message: Callable[[dict, Any], Any] | None = None,
+):
+    """Return an ASGI websocket app serving one flyrail session per connection."""
+    _version_of = version_fn or (lambda: None)
+
+    async def app(scope, receive, send):
+        if scope["type"] != "websocket":
+            raise RuntimeError("flyrail ASGI app handles websocket scope only")
+        layout = Layout(render_fn, allowed_types=allowed_types, strict=strict)
+        driver = Driver(layout)
+        state = state_factory()
+
+        async def send_json(env: dict) -> None:
+            await send({"type": "websocket.send", "text": json.dumps(env)})
+
+        await send({"type": "websocket.accept"})
+        snap = layout.snapshot(state, seq=1)
+        driver.seq = 1
+        await send_json(snap)
+
+        run_task = asyncio.create_task(
+            driver.run(lambda: state, send_json, _version_of)
+        )
+        try:
+            while True:
+                msg = await receive()
+                if msg["type"] == "websocket.disconnect":
+                    break
+                if msg["type"] != "websocket.receive":
+                    continue
+                data = json.loads(msg.get("text") or msg.get("bytes") or "{}")
+                if data.get("chan") != "ui":
+                    if on_message is not None:
+                        res = on_message(data, state)
+                        if inspect.isawaitable(res):
+                            await res
+                    continue
+                kind = data.get("type")
+                if kind == "action":
+                    await layout.adispatch(
+                        data["handlerId"], state, data.get("event"))
+                    driver.invalidate()
+                elif kind == "resync-request":
+                    driver.seq += 1
+                    await send_json(layout.snapshot(state, driver.seq))
+                # Unknown ui subtypes ignored (forward-compat, mirrors store).
+        finally:
+            run_task.cancel()
+            try:
+                await run_task
+            except asyncio.CancelledError:
+                pass
+
+    return app

flyrail-0.1.0/flyrail/core.py

@@ -0,0 +1,107 @@
+"""Declarative element constructors. No VDOM dependency."""
+from __future__ import annotations
+import functools
+from typing import Any, Callable
+
+
+def component(fn=None, *, key_arg: str | None = None):
+    """Declare a component. Calling it returns a lazy node that Layout
+    expands with per-instance hook state (keyed by key=, else position).
+    """
+    def wrap(f):
+        @functools.wraps(f)
+        def invoke(*args, **kwargs):
+            key = kwargs.pop("key", None)
+            return {"type": "__Component__", "fn": f, "key": key,
+                    "args": args, "kwargs": kwargs}
+        invoke._is_flyrail_component = True
+        invoke._key_arg = key_arg
+        invoke._component_fn = f
+        return invoke
+    return wrap(fn) if fn else wrap
+
+
+def pure(fn=None):
+    """Opt-in contract: output is a pure function of (arguments, hook slots).
+
+    Declares, not verifies: Layout may skip re-renders when the host version
+    is unchanged or when a component's arguments are unchanged, and strict mode
+    double-renders to spot-check. Unmarked renders always re-render. If you lie,
+    the stale UI is your bug.
+
+    Marks both sides of @component so either decorator order works: Layout
+    expands the inner function, while a host reading the flag off the name it
+    was given sees the wrapper.
+    """
+    def wrap(f):
+        f._flyrail_pure = True
+        inner = getattr(f, "_component_fn", None)
+        if inner is not None:
+            inner._flyrail_pure = True
+        return f
+    return wrap(fn) if fn else wrap
+
+
+def _opts(event: str, prevent_default: bool, stop_propagation: bool,
+          throttle_ms: int | None) -> dict:
+    """Per-event wire options. throttleMs is omitted when unset (minimal wire)."""
+    opts: dict[str, Any] = {"preventDefault": prevent_default,
+                            "stopPropagation": stop_propagation}
+    if throttle_ms is not None:
+        opts["throttleMs"] = throttle_ms
+    return {event: opts}
+
+
+def _el(type_: str, *children: Any, key: Any = None, on_click: Callable | None = None,
+        event_options: dict | None = None, **props: Any) -> dict:
+    node: dict[str, Any] = {"type": type_, "props": props}
+    if key is not None:
+        node["key"] = key
+    if children:
+        # flatten one level of lists (for [... for ...] splats)
+        flat: list[Any] = []
+        for c in children:
+            if isinstance(c, list):
+                flat.extend(c)
+            else:
+                flat.append(c)
+        node["children"] = flat
+    if on_click is not None:
+        node["on_click"] = on_click
+    if event_options:
+        node["event_options"] = event_options
+    return node
+
+
+def Stack(*children: Any, key: Any = None, **props: Any) -> dict:
+    return _el("Stack", *children, key=key, **props)
+
+
+def Text(value: str, key: Any = None, **props: Any) -> dict:
+    return _el("Text", key=key, value=value, **props)
+
+
+def Button(label: str, on_click: Callable | None = None, key: Any = None, *,
+           prevent_default: bool = True, stop_propagation: bool = False,
+           throttle_ms: int | None = None, **props: Any) -> dict:
+    return _el("Button", key=key, on_click=on_click,
+               event_options=_opts("on_click", prevent_default,
+                                   stop_propagation, throttle_ms) if on_click else None,
+               label=label, **props)
+
+
+def TextField(key: Any = None, on_change: Callable | None = None, *,
+              prevent_default: bool = True, stop_propagation: bool = False,
+              throttle_ms: int | None = None, **props: Any) -> dict:
+    node = _el("TextField", key=key, **props)
+    if on_change is not None:
+        node["on_change"] = on_change
+        node["event_options"] = _opts("on_change", prevent_default,
+                                      stop_propagation, throttle_ms)
+    return node
+
+
+def Slot(name: str, default: Any = None) -> dict:
+    """Hot-path placeholder. Renderer subscribes by name; tick sends slot values
+    directly instead of diffing the whole tree."""
+    return {"type": "__Slot__", "props": {"name": name, "default": default}}

flyrail-0.1.0/flyrail/driver.py

@@ -0,0 +1,55 @@
+"""Host scheduling seam: one primitive for tick, async, and naive hosts."""
+from __future__ import annotations
+import asyncio
+from typing import Any, Callable
+
+from .layout import Layout
+
+
+class Driver:
+    """Wraps Layout with dirty-flag scheduling and caller-owned seq.
+
+    Tick hosts:   invalidate() per tick (or on sim change); flush(state, version).
+    Async hosts:  invalidate() from event handlers; await run(state_fn, send).
+    Naive hosts:  invalidate() + flush() around every message.
+    Thread-safe invalidate: safe to call from any thread; the run loop
+    (single asyncio loop assumption) wakes via call_soon_threadsafe.
+    """
+
+    def __init__(self, layout: Layout):
+        self.layout = layout
+        self.seq = 0
+        self._event = asyncio.Event()
+
+    def invalidate(self) -> None:
+        self.layout.invalidate()
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+        if loop is None:
+            self._event.set()
+        else:
+            loop.call_soon_threadsafe(self._event.set)
+
+    def flush(self, state: Any, version: Any = None) -> dict | None:
+        """Render+diff if dirty/version-changed; seq-numbered envelope or None."""
+        ops = self.layout.tick(state, version)
+        if not ops:
+            return None
+        self.seq += 1
+        return {"chan": "ui", "type": "patch", "seq": self.seq, "ops": ops}
+
+    async def run(
+        self,
+        state_fn: Callable[[], Any],
+        send: Callable[[dict], Any],
+        version_fn: Callable[[], Any] = lambda: None,
+    ) -> None:
+        """Never returns; cancel to stop. Bursts coalesce into one flush."""
+        while True:
+            await self._event.wait()
+            self._event.clear()
+            env = self.flush(state_fn(), version_fn())
+            if env is not None:
+                await send(env)