klein-bt 0.8.0__tar.gz

klein_bt-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johan Ubbink
+
+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.

klein_bt-0.8.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: klein-bt
+Version: 0.8.0
+Summary: Lightweight CLI telemetry dashboard for BehaviorTree.CPP v4 over ZeroMQ.
+Author-email: Johan Ubbink <25775970+johanubbink@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/johanubbink/klein-bt
+Project-URL: Issues, https://github.com/johanubbink/klein-bt/issues
+Project-URL: Changelog, https://github.com/johanubbink/klein-bt/blob/main/CHANGELOG.md
+Keywords: behaviortree,behaviortree.cpp,groot,groot2,robotics,zeromq,telemetry,dashboard,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyzmq>=25
+Requires-Dist: websockets>=14
+Requires-Dist: msgpack>=1.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: playwright; extra == "dev"
+Dynamic: license-file
+
+# klein
+
+klein lets you watch a running BehaviorTree.CPP v4 tree live in your browser.
+You see which nodes are running, succeeding or failing, plus the current
+blackboard values, as the robot ticks.
+
+![klein showing a live CrossDoor behavior tree: running nodes pulse, the blackboard updates, and the Timeline below draws each node's RUNNING spans as the robot ticks](https://raw.githubusercontent.com/johanubbink/klein-bt/main/assets/klein-demo.gif)
+
+## Install
+
+Install it from [PyPI](https://pypi.org/project/klein-bt/) with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install klein-bt
+```
+
+uv fetches a newer Python by itself if yours is older than the 3.10 klein
+needs. [pipx](https://pipx.pypa.io) works too:
+
+```bash
+pipx install klein-bt
+```
+
+This gives you two commands: `klein-bt` (the dashboard) and `klein-bt-mock`
+(a fake robot for trying it out).
+
+## Run it
+
+```bash
+klein-bt                                          # robot on 127.0.0.1:1667
+klein-bt --robot-host 10.0.0.5 --robot-port 1667  # robot somewhere else
+klein-bt --port 8080 --no-browser                 # don't open a browser
+klein-bt --open run.btlog                         # a saved recording, no robot
+```
+
+| Flag              | Default     | Meaning                              |
+| ----------------- | ----------- | ------------------------------------ |
+| `--robot-host`    | `127.0.0.1` | IP address of the robot              |
+| `--robot-port`    | `1667`      | Groot2 publisher port on the robot   |
+| `--port`          | `8080`      | port the dashboard is served on      |
+| `--no-browser`    | off         | don't open the browser automatically |
+| `--record-buffer` | `10m`       | how much recent history to record (`90s`, `30m`, `1h`); `0` turns recording off |
+| `--open FILE`     |             | show a saved `.btlog` (and `FILE.bb.jsonl` beside it) instead of a robot |
+
+klein opens `http://localhost:8080` for you. You can start it before the robot
+is up; it keeps retrying until the robot appears.
+
+## Using the dashboard
+
+- Node colours show status: green is SUCCESS, pulsing amber is RUNNING, red is
+  FAILURE, grey is IDLE.
+- Scroll to zoom and drag to pan. Click a node to fold or unfold its children.
+- Press `R` to see the whole tree again, or `F` to jump to whatever is running.
+- Hover a node to see its ports.
+- **Layout** switches between a vertical and a horizontal tree.
+- The **Blackboards** list shows every subtree's values. A value that just
+  changed gets a thin amber edge that fades; a key that changes all the time
+  (a position, a counter) gets a steady dim edge and a `~` instead. Click a
+  row to expand it, or hover a board to find its node in the tree. See
+  [docs/blackboards.md](https://github.com/johanubbink/klein-bt/blob/main/docs/blackboards.md) for how values are shown.
+- Hover a key to see which nodes use it: writers outlined solid, readers
+  dashed. Hover a node to ring its keys. Writers get a small amber dot when
+  the key changes.
+- Drag the side panel's right edge to make it wider or narrower, or fold it
+  away with its `◂` button (or a double-click on the edge) for more room.
+  klein remembers both.
+
+If the robot loads a different tree, the dashboard switches to it by itself.
+
+## Record, rewind and replay
+
+klein records everything the robot does (BehaviorTree.CPP 4.3.3 or newer),
+blackboard included, and keeps the last 10 minutes. Change that with
+`--record-buffer` (`30m`, `1h`, or `0` to turn recording off). Don't log
+from Groot2 against the same robot at the same time: each would get only
+some of the transitions.
+
+![klein rewinding a live robot: hover the minimap (its scrollbar shows), drag its box back, click a burst, scrub, step, hover a key, play, back to live](https://raw.githubusercontent.com/johanubbink/klein-bt/main/assets/klein-rewind.gif)
+
+The drawer under the tree shows the recording. Its top row works in every
+tab, even with the drawer folded:
+
+- |◀ ▶| step to the previous or next transition, and ▶ plays at 1×.
+  While live it reads ❚❚: press it to freeze the tree, the blackboard and
+  the clock right where they are.
+- The green **● Live** says you are live. In the past it turns into
+  **Go live**, which takes you back; the tree gets a thin amber edge,
+  and the clock beside the bar says which moment you see. Changes are marked
+  in the past too: stepping or clicking shows which values just changed.
+- The bar is a minimap of the recording, eight of the Timeline's windows
+  long (live, now is its right edge): amber columns show how busy the robot
+  was, hatched stretches are outages, and a pink dashed line marks where
+  the robot started another tree. Click or drag it to go to that moment;
+  hover it for the time. On the Timeline tab a box on it is the Timeline's
+  window: drag it (or turn the wheel) to pan. While the pointer is over the
+  bar, a thin scrollbar for the whole recording shows underneath.
+- The keys: ←/→ step, Space plays or pauses, Home goes to the oldest moment
+  kept, End or Esc goes live, and `\` zooms the Timeline to fit everything
+  kept (also its ⤢ button).
+
+Below it are two tabs, a filter and the recording pill:
+
+- **Log**: every transition. Click a row to see the tree and blackboard at
+  that moment.
+- **Timeline**: each node's running time as bars, so every retry shows. Drag
+  the playhead to go back in time; − and + change the window.
+- The **Filter** beside the tabs narrows both tabs, and stepping, to the
+  nodes and subtrees you name.
+- **Save**, on the recording pill (`● Recording 10 min · 148 kB`),
+  downloads one `.zip` with a `.btlog` per tree run (Groot2 opens these)
+  and its blackboard in a `.bb.jsonl` beside it.
+
+`klein-bt --open FILE.btlog` shows a saved recording without a robot, in the
+same Log and Timeline; **Go to end** takes you to its end. Unzip a saved
+`.zip` first; the `.bb.jsonl` beside the file brings its blackboard along.
+
+## Set up your robot
+
+klein talks to the Groot2 publisher that comes with BehaviorTree.CPP v4. If
+Groot2 can connect to your robot, klein can too. If not, add a publisher after
+you create the tree:
+
+```cpp
+#include "behaviortree_cpp/loggers/groot2_publisher.h"
+
+auto tree = factory.createTreeFromFile("my_tree.xml");
+BT::Groot2Publisher publisher(tree, 1667);
+```
+
+The publisher also uses the next port up (1668), so leave that one free.
+
+## Try it without a robot
+
+```bash
+klein-bt-mock --port 1777        # in one terminal
+klein-bt --robot-port 1777       # in another
+```
+
+Add `--switch-every 200` to the mock to make it swap between two trees every
+20 seconds or so.
+
+## Docs
+
+- [docs/blackboards.md](https://github.com/johanubbink/klein-bt/blob/main/docs/blackboards.md): reading blackboard values, and
+  adding a renderer for your own message types.
+- [docs/architecture.md](https://github.com/johanubbink/klein-bt/blob/main/docs/architecture.md): how klein works inside.
+- [docs/protocol.md](https://github.com/johanubbink/klein-bt/blob/main/docs/protocol.md): the Groot2 wire protocol klein speaks.
+- [docs/testing.md](https://github.com/johanubbink/klein-bt/blob/main/docs/testing.md): the test tiers and harness, and
+  `scripts/make_gifs.py`, which remakes the GIFs above.
+
+## License
+
+klein is released under the MIT License — see [LICENSE](https://github.com/johanubbink/klein-bt/blob/main/LICENSE).
+
+The dashboard bundles [D3.js](https://d3js.org) v7 (ISC License, © Mike
+Bostock), served locally so it works on air-gapped networks.
+
+## Disclaimer
+
+klein is an independent tool. It is not affiliated with, endorsed by, or
+sponsored by the BehaviorTree.CPP project or the authors of Groot / Groot2.
+"BehaviorTree.CPP", "Groot", and "Groot2" are the property of their respective
+owners. klein interoperates over the Groot2 publisher wire protocol that is part
+of the open-source, MIT-licensed BehaviorTree.CPP library; it contains no code
+copied from those projects.

klein_bt-0.8.0/README.md

@@ -0,0 +1,166 @@
+# klein
+
+klein lets you watch a running BehaviorTree.CPP v4 tree live in your browser.
+You see which nodes are running, succeeding or failing, plus the current
+blackboard values, as the robot ticks.
+
+![klein showing a live CrossDoor behavior tree: running nodes pulse, the blackboard updates, and the Timeline below draws each node's RUNNING spans as the robot ticks](https://raw.githubusercontent.com/johanubbink/klein-bt/main/assets/klein-demo.gif)
+
+## Install
+
+Install it from [PyPI](https://pypi.org/project/klein-bt/) with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install klein-bt
+```
+
+uv fetches a newer Python by itself if yours is older than the 3.10 klein
+needs. [pipx](https://pipx.pypa.io) works too:
+
+```bash
+pipx install klein-bt
+```
+
+This gives you two commands: `klein-bt` (the dashboard) and `klein-bt-mock`
+(a fake robot for trying it out).
+
+## Run it
+
+```bash
+klein-bt                                          # robot on 127.0.0.1:1667
+klein-bt --robot-host 10.0.0.5 --robot-port 1667  # robot somewhere else
+klein-bt --port 8080 --no-browser                 # don't open a browser
+klein-bt --open run.btlog                         # a saved recording, no robot
+```
+
+| Flag              | Default     | Meaning                              |
+| ----------------- | ----------- | ------------------------------------ |
+| `--robot-host`    | `127.0.0.1` | IP address of the robot              |
+| `--robot-port`    | `1667`      | Groot2 publisher port on the robot   |
+| `--port`          | `8080`      | port the dashboard is served on      |
+| `--no-browser`    | off         | don't open the browser automatically |
+| `--record-buffer` | `10m`       | how much recent history to record (`90s`, `30m`, `1h`); `0` turns recording off |
+| `--open FILE`     |             | show a saved `.btlog` (and `FILE.bb.jsonl` beside it) instead of a robot |
+
+klein opens `http://localhost:8080` for you. You can start it before the robot
+is up; it keeps retrying until the robot appears.
+
+## Using the dashboard
+
+- Node colours show status: green is SUCCESS, pulsing amber is RUNNING, red is
+  FAILURE, grey is IDLE.
+- Scroll to zoom and drag to pan. Click a node to fold or unfold its children.
+- Press `R` to see the whole tree again, or `F` to jump to whatever is running.
+- Hover a node to see its ports.
+- **Layout** switches between a vertical and a horizontal tree.
+- The **Blackboards** list shows every subtree's values. A value that just
+  changed gets a thin amber edge that fades; a key that changes all the time
+  (a position, a counter) gets a steady dim edge and a `~` instead. Click a
+  row to expand it, or hover a board to find its node in the tree. See
+  [docs/blackboards.md](https://github.com/johanubbink/klein-bt/blob/main/docs/blackboards.md) for how values are shown.
+- Hover a key to see which nodes use it: writers outlined solid, readers
+  dashed. Hover a node to ring its keys. Writers get a small amber dot when
+  the key changes.
+- Drag the side panel's right edge to make it wider or narrower, or fold it
+  away with its `◂` button (or a double-click on the edge) for more room.
+  klein remembers both.
+
+If the robot loads a different tree, the dashboard switches to it by itself.
+
+## Record, rewind and replay
+
+klein records everything the robot does (BehaviorTree.CPP 4.3.3 or newer),
+blackboard included, and keeps the last 10 minutes. Change that with
+`--record-buffer` (`30m`, `1h`, or `0` to turn recording off). Don't log
+from Groot2 against the same robot at the same time: each would get only
+some of the transitions.
+
+![klein rewinding a live robot: hover the minimap (its scrollbar shows), drag its box back, click a burst, scrub, step, hover a key, play, back to live](https://raw.githubusercontent.com/johanubbink/klein-bt/main/assets/klein-rewind.gif)
+
+The drawer under the tree shows the recording. Its top row works in every
+tab, even with the drawer folded:
+
+- |◀ ▶| step to the previous or next transition, and ▶ plays at 1×.
+  While live it reads ❚❚: press it to freeze the tree, the blackboard and
+  the clock right where they are.
+- The green **● Live** says you are live. In the past it turns into
+  **Go live**, which takes you back; the tree gets a thin amber edge,
+  and the clock beside the bar says which moment you see. Changes are marked
+  in the past too: stepping or clicking shows which values just changed.
+- The bar is a minimap of the recording, eight of the Timeline's windows
+  long (live, now is its right edge): amber columns show how busy the robot
+  was, hatched stretches are outages, and a pink dashed line marks where
+  the robot started another tree. Click or drag it to go to that moment;
+  hover it for the time. On the Timeline tab a box on it is the Timeline's
+  window: drag it (or turn the wheel) to pan. While the pointer is over the
+  bar, a thin scrollbar for the whole recording shows underneath.
+- The keys: ←/→ step, Space plays or pauses, Home goes to the oldest moment
+  kept, End or Esc goes live, and `\` zooms the Timeline to fit everything
+  kept (also its ⤢ button).
+
+Below it are two tabs, a filter and the recording pill:
+
+- **Log**: every transition. Click a row to see the tree and blackboard at
+  that moment.
+- **Timeline**: each node's running time as bars, so every retry shows. Drag
+  the playhead to go back in time; − and + change the window.
+- The **Filter** beside the tabs narrows both tabs, and stepping, to the
+  nodes and subtrees you name.
+- **Save**, on the recording pill (`● Recording 10 min · 148 kB`),
+  downloads one `.zip` with a `.btlog` per tree run (Groot2 opens these)
+  and its blackboard in a `.bb.jsonl` beside it.
+
+`klein-bt --open FILE.btlog` shows a saved recording without a robot, in the
+same Log and Timeline; **Go to end** takes you to its end. Unzip a saved
+`.zip` first; the `.bb.jsonl` beside the file brings its blackboard along.
+
+## Set up your robot
+
+klein talks to the Groot2 publisher that comes with BehaviorTree.CPP v4. If
+Groot2 can connect to your robot, klein can too. If not, add a publisher after
+you create the tree:
+
+```cpp
+#include "behaviortree_cpp/loggers/groot2_publisher.h"
+
+auto tree = factory.createTreeFromFile("my_tree.xml");
+BT::Groot2Publisher publisher(tree, 1667);
+```
+
+The publisher also uses the next port up (1668), so leave that one free.
+
+## Try it without a robot
+
+```bash
+klein-bt-mock --port 1777        # in one terminal
+klein-bt --robot-port 1777       # in another
+```
+
+Add `--switch-every 200` to the mock to make it swap between two trees every
+20 seconds or so.
+
+## Docs
+
+- [docs/blackboards.md](https://github.com/johanubbink/klein-bt/blob/main/docs/blackboards.md): reading blackboard values, and
+  adding a renderer for your own message types.
+- [docs/architecture.md](https://github.com/johanubbink/klein-bt/blob/main/docs/architecture.md): how klein works inside.
+- [docs/protocol.md](https://github.com/johanubbink/klein-bt/blob/main/docs/protocol.md): the Groot2 wire protocol klein speaks.
+- [docs/testing.md](https://github.com/johanubbink/klein-bt/blob/main/docs/testing.md): the test tiers and harness, and
+  `scripts/make_gifs.py`, which remakes the GIFs above.
+
+## License
+
+klein is released under the MIT License — see [LICENSE](https://github.com/johanubbink/klein-bt/blob/main/LICENSE).
+
+The dashboard bundles [D3.js](https://d3js.org) v7 (ISC License, © Mike
+Bostock), served locally so it works on air-gapped networks.
+
+## Disclaimer
+
+klein is an independent tool. It is not affiliated with, endorsed by, or
+sponsored by the BehaviorTree.CPP project or the authors of Groot / Groot2.
+"BehaviorTree.CPP", "Groot", and "Groot2" are the property of their respective
+owners. klein interoperates over the Groot2 publisher wire protocol that is part
+of the open-source, MIT-licensed BehaviorTree.CPP library; it contains no code
+copied from those projects.

klein_bt-0.8.0/klein/__init__.py

@@ -0,0 +1,8 @@
+"""klein — a lightweight CLI telemetry dashboard for BehaviorTree.CPP v4.
+
+Connects to a running robot node over ZeroMQ (the Groot2 publisher protocol),
+unrolls nested subtrees, and streams live status and blackboard values to an
+interactive D3.js browser dashboard. Run ``klein-bt --help`` for options.
+"""
+
+__version__ = "0.8.0"

klein_bt-0.8.0/klein/btlog.py

@@ -0,0 +1,186 @@
+"""klein.btlog — FileLogger2 ``.btlog`` files, read and written in memory.
+
+The format BehaviorTree.CPP's ``FileLogger2`` writes and Groot2 opens
+(``bt_file_logger_v2.cpp``; the header comment in ``bt_file_logger_v2.h``
+leaves out the magic and the version byte — the .cpp is authoritative).
+All little-endian::
+
+    b"BTCPP4-FileLogger2" | u8 version (1) | i32 xml_len | xml (UTF-8)
+    | i64 first_timestamp (µs since the epoch)
+    | N x 9-byte records: u48 offset_us (from first_timestamp) | u16 uid | u8 status
+
+A record is exactly a GET_TRANSITIONS record, so the packing is shared with
+``groot2_protocol``. Statuses are live NodeStatus ints (IDLE is a plain 0).
+
+``export_run`` and ``export_blackboard`` save one tree run of a ``Recording``
+(docs/protocol.md, "Saving a recording"); ``load_btlog`` turns a file and its
+sidecar back into one (``klein-bt --open``, docs/protocol.md, "Opening a file").
+"""
+
+import collections
+import itertools
+import json
+import struct
+
+from .groot2_protocol import TRANSITION_RECORD_SIZE, decode_transitions, encode_transition
+from .recording import Recording, apply_transition, diff_to_transitions
+
+MAGIC = b"BTCPP4-FileLogger2"
+VERSION = 1
+_XML_OFFSET = len(MAGIC) + 1 + 4        # the XML starts after magic, version, xml_len
+_TIMESTAMP_SIZE = 8
+
+BtlogFile = collections.namedtuple("BtlogFile", "xml first_timestamp records trailing")
+BtlogFile.__doc__ = ("A parsed ``.btlog``. ``records`` are ``(offset_us, uid, status)``; "
+                     "``trailing`` counts the bytes of an incomplete last record.")
+
+
+class BtlogError(ValueError):
+    """The data is not a FileLogger2 ``.btlog`` klein can read."""
+
+
+def read_btlog(data):
+    """Parse ``.btlog`` bytes into a ``BtlogFile``.
+
+    A trailing partial record — a robot stopped mid-write — is left out of
+    ``records`` and counted in ``trailing``, not raised.
+    """
+    if not data.startswith(MAGIC):
+        raise BtlogError("not a FileLogger2 .btlog (no BTCPP4-FileLogger2 magic)")
+    version = data[len(MAGIC):len(MAGIC) + 1]
+    if version != bytes([VERSION]):
+        shown = version[0] if version else "missing"
+        raise BtlogError(f"unknown .btlog format version {shown}")
+    xml_len = int.from_bytes(data[len(MAGIC) + 1:_XML_OFFSET], "little", signed=True)
+    if not 0 <= xml_len <= len(data) - _XML_OFFSET - _TIMESTAMP_SIZE:
+        raise BtlogError(f"XML length {xml_len} does not fit the file")
+    body = _XML_OFFSET + xml_len + _TIMESTAMP_SIZE     # where the records start
+    xml = data[_XML_OFFSET:_XML_OFFSET + xml_len].decode("utf-8")
+    (first_timestamp,) = struct.unpack_from("<q", data, body - _TIMESTAMP_SIZE)
+    records = data[body:]
+    return BtlogFile(xml, first_timestamp, decode_transitions(records),
+                     len(records) % TRANSITION_RECORD_SIZE)
+
+
+def _header(xml, first_timestamp):
+    body = xml.encode("utf-8")
+    return b"".join([MAGIC, bytes([VERSION]), struct.pack("<i", len(body)), body,
+                     struct.pack("<q", first_timestamp)])
+
+
+def write_btlog(xml, first_timestamp, records):
+    """Serialize a ``.btlog``; ``records`` are ``(offset_us, uid, status)``."""
+    return b"".join([_header(xml, first_timestamp)]
+                    + [encode_transition(*record) for record in records])
+
+
+def export_run(run, xml):
+    """One tree run (``Recording.runs()``) as ``.btlog`` bytes.
+
+    ``first_timestamp`` is the run's retained start. Replayed from all-IDLE, as
+    Groot2 and klein start a file, the file gives the recorded state at every
+    retained time: each segment opens with the transitions from the state
+    before it (all-IDLE for the first) to its retained start — the prefix at
+    offset 0, and at each restart or re-arm inside the run.
+
+    A record ``apply_transition`` ignores (an IDLE on a node already idle: an
+    arm-overlap record the baseline already held) is left out, so a reader
+    with the plain publisher rule never sees "was IDLE".
+    """
+    first = run[0].t_start
+    state = bytearray(len(run[0].baseline))     # the file's state, as written so far
+    out = bytearray(_header(xml, first))
+    for segment in run:
+        start = segment.state_at_seq(segment.start_seq)
+        opening = [(segment.t_start, uid, status)
+                   for uid, status in diff_to_transitions(state, start)]
+        recorded = ((ts, uid, status) for _seq, ts, uid, status
+                    in segment.iter_records(segment.start_seq, segment.head_seq))
+        for ts, uid, status in itertools.chain(opening, recorded):
+            if apply_transition(state, uid, status):
+                out += encode_transition(ts - first, uid, status)
+    return bytes(out)
+
+
+def export_blackboard(run, tree_id):
+    """One tree run's blackboard history as ``.bb.jsonl`` bytes: a header line,
+    then one line per change at its offset from the run's retained start.
+
+    Each segment opens with the lines that turn the previous values (none, for
+    the first) into its values at its retained start, so the file stands alone
+    after eviction and across restarts.
+    """
+    first = run[0].t_start
+    lines = [json.dumps({"klein_blackboard": 1, "first_timestamp": first, "tree_id": tree_id})]
+    values = {}                             # (board, key) -> JSON text, as of the last line
+
+    def line(t, board, key, text):
+        entry = json.dumps({"t": t - first, "board": board, "key": key})[:-1]
+        if text is None:
+            del values[board, key]
+            lines.append(f'{entry}, "removed": true}}')
+        else:
+            values[board, key] = text       # the stored JSON text goes in as it is
+            lines.append(f'{entry}, "value": {text}}}')
+
+    for segment in run:
+        track = segment.blackboard
+        if track.t_start is None:
+            continue
+        base = max(track.t_start, first)
+        at_base, later = {}, []
+        for t, board, key, text in track.changes():
+            if t <= base:
+                at_base[board, key] = text
+            else:
+                later.append((t, board, key, text))
+        for name in [name for name in values if at_base.get(name) is None]:
+            line(base, *name, None)
+        for name, text in at_base.items():
+            if text is not None and values.get(name) != text:
+                line(base, *name, text)
+        for change in later:
+            line(*change)
+    return "".join(entry + "\n" for entry in lines).encode("utf-8")
+
+
+def load_btlog(log, layout, sidecar=None):
+    """A ``Recording`` of one parsed file (``read_btlog``), as the gateway
+    would have recorded it: one ended segment from ``first_timestamp``,
+    replayed from all-IDLE as Groot2 starts a file, with its head at the last
+    record.
+
+    ``layout`` is the file's ``TreeLayout`` (``parse_layout`` of its XML),
+    the segment's layout. ``sidecar`` is the ``.bb.jsonl`` text
+    (``export_blackboard``), or None. Its lines become blackboard samples
+    holding every board in the layout's ``blackboard_names``, so a board with
+    no lines (no keys of its own) still shows, empty, as it does live. The
+    first sample is at the first line, or at the sidecar's start when it has
+    none.
+    """
+    recording = Recording()
+    segment = recording.begin_segment(layout, log.first_timestamp, bytes(layout.size))
+    recording.append([(log.first_timestamp + offset, uid, status)
+                      for offset, uid, status in log.records])
+    if sidecar is not None:
+        _load_blackboard(recording, sidecar, layout.blackboard_names)
+    recording.end_segment(segment.last_ts)
+    recording.advance_head(segment.last_ts)
+    return recording
+
+
+def _load_blackboard(recording, text, boards):
+    header, *lines = [json.loads(line) for line in text.splitlines() if line.strip()]
+    first = header["first_timestamp"]
+    values = {board: {} for board in boards}
+    by_time = collections.defaultdict(list)
+    for line in lines:
+        by_time[line["t"]].append(line)
+    for t in sorted(by_time) or [0]:
+        for line in by_time[t]:
+            entries = values.setdefault(line["board"], {})
+            if line.get("removed"):
+                entries.pop(line["key"], None)
+            else:
+                entries[line["key"]] = line["value"]
+        recording.add_blackboard(first + t, values)