tassello 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,70 @@
 Tassello follows [semantic versioning](https://semver.org): before 1.0, a new minor version may
 change the plugin API (`tassello/sdk`, `tassello/server`, `tassello/vite`), as noted here.
 
+## Unreleased
+
+- Behavior Tree Inspector widget: what a BT.CPP behavior tree is doing, from its
+  `nav2_msgs/BehaviorTreeLog` (Nav2's `/behavior_tree_log`), on the tree of its XML file: the
+  running branch, each node's status, last result, counts and ports, and the latest transitions,
+  as a graph or a list. The server follows the log for every page and keeps the nodes' state.
+- The inspector records its log into rosbags (`ros2 bag record`), and plays rosbags back in the
+  widget (MCAP or SQLite, Humble's or Jazzy's), with pause, seek and speed.
+- Behavior Tree Editor widget: a BT.CPP behavior tree's XML file of the robot, edited as a graph,
+  with a palette of nodes (BT.CPP's, Nav2's, node libraries of `TreeNodesModel`, the file's own),
+  drag and drop, a side panel for the nodes' names and ports, subtrees, undo and redo, copy and
+  paste, and an XML view. Saves only what changed, keeping the file's comments and layout, and
+  never over changes made on the robot since it was read.
+- The file browser is resizable, and shows long names whole.
+- Plugins: the `behavior-tree` property kind, `connection.subscribeBehaviorTree`,
+  `recordBehaviorTree`, `subscribeBehaviorTreePlayback`, `controlBehaviorTreePlayback`,
+  `subscribeBehaviorTreeFile`, `saveBehaviorTreeFile`.
+- Uploads take behavior trees (XML) as well as images.
+- Logs widget: the ROS log (`/rosout`), as rqt_console and swri_console show it: every node's
+  messages coloured by level, the nodes running and those that logged with their counts, filters
+  by node, level and text (terms or regular expressions, to show or to hide), pause, follow,
+  clear, download, and a message's details. A widget can be for some nodes only (`amcl,
+  *_server`). The server follows the log for every page and keeps its latest 10,000 messages.
+- Plugins: `connection.subscribeRosout`, and the `LogsIcon`, `NodesIcon`, `SearchIcon`,
+  `BanIcon`, `FilterIcon`, `DownloadIcon` and `ArrowDownToLineIcon` icons.
+- Diagnostics widget: the robot's diagnostics (`diagnostic_msgs/msg/DiagnosticArray`), from every
+  node's `diagnostic_updater` (`/diagnostics`, by node) or the aggregator's tree
+  (`/diagnostics_agg`): each status's level, message, hardware ID and values, the groups with the
+  worst under them, as a tree, as a list or as the latest changes of level, filtered by level and
+  text. A widget can be for some statuses only (`Sensors, motor_*`). The server follows the
+  diagnostics for every page, marks stale the statuses no longer received, and keeps their changes
+  of level.
+- Plugins: `connection.subscribeDiagnostics`, and the `DiagnosticsIcon` and `UnfoldIcon` icons.
+- File Manager widget: the robot's files, in the behavior tree editor's look. Folders listed with
+  their entries' sizes and times, unfolded in place, sorted and filtered; places (home, the ROS
+  workspaces sourced, bookmarks) and the disks with their free space; an entry's details, its
+  permissions changed there; an overview of the disks and of what takes a folder's space (its
+  largest entries, its files by type, the largest and latest files). Entries made, renamed in
+  place, cut, copied and pasted, moved or copied by dragging them onto folders, deleted,
+  downloaded (folders as `.tar.gz`), uploaded by dropping files and folders onto the widget, with
+  their progress; names taken are asked about. Text files are edited in tabs, as gedit does: line
+  numbers, syntax highlighting (YAML, XML, Python, C++, CMake, JSON, shell, INI, Markdown, ROS
+  interfaces), search and replace, indentation, line ends kept, undo and redo, never saved over
+  changes made on the robot since they were read. Images are shown, PGM maps too. A widget can
+  stay in its folder, or be read-only. The server polls the folders and files shown.
+- Plugins: `fsApi` and `ApiError`, the `Fs*` types, and the `FolderIcon`, `FolderPlusIcon`,
+  `FileIcon`, `FileTextIcon`, `FilePlusIcon`, `UploadIcon`, `ArrowUpIcon`, `ArrowLeftIcon`,
+  `HomeIcon`, `HardDriveIcon`, `BookmarkIcon`, `SidebarIcon`, `PieChartIcon`, `InfoIcon`,
+  `WrapIcon`, `LinkIcon`, `LockIcon` and `ArchiveIcon` icons.
+- REST errors of the API reject with an `ApiError`, which has the HTTP status.
+- Terminal widget: a shell on the robot (the login shell of the server's user), or a command, in
+  a full terminal (xterm.js): colours, full screen programs and their mouse, copy and paste. It
+  outlives the page: reloaded, reconnected or shown again, it is as it was, full screen programs
+  included; hung up an hour after no page shows it. On touch screens, Termux's extra keys (Esc,
+  Tab, Ctrl, Alt, Home, End, the arrows, Page Up and Down): sticky modifiers that also apply to the
+  on-screen keyboard, keys swiped up for another character, a layout of one's own; the terminal
+  fills the screen above the on-screen keyboard while typing; one finger scrolls, two pinch the
+  text's size. Needs Python 3 (ROS 2's), no native module. Terminals open from the dashboard's own
+  pages only.
+- Plugins: `connection.subscribeTerminal`, `terminalInput`, `resizeTerminal`, `ackTerminal`,
+  `restartTerminal`, the `TerminalOutput` and `TerminalExit` types, and the `ShellIcon`,
+  `KeyboardIcon`, `MaximizeIcon`, `MinimizeIcon`, `ClipboardIcon`, `TextSmallerIcon` and
+  `TextLargerIcon` icons.
+
 ## 0.1.0
 
 The first release, from the Dieletrikbot's web dashboard.

package/README.md

@@ -1,8 +1,8 @@
 # Tassello
 
 **A web dashboard for ROS 2 robots.** Drive the robot, send it navigation goals, see it move in 3D,
-watch its cameras, run commands on it and manage its services from any browser on the network,
-phones included. Arrange it all in the browser, as panels of widgets, and extend it with plugins.
+watch its cameras, run commands on it, open a terminal on it and manage its services from any
+browser on the network, phones included. Arrange it all in the browser, as panels of widgets, and extend it with plugins.
 
 *Tassello* is Italian for a mosaic tile, and for a wall plug: the dashboard is a mosaic of widgets,
 and plugins add more.
@@ -10,7 +10,8 @@ and plugins add more.
 - **Panels of widgets** on a grid: add, move and resize them in the browser, no code or config files.
 - **Every device**: a desktop canvas, and layouts of their own for tablets and phones.
 - **Built in**: teleop pads, a Nav2 map with goals, the robot's URDF in 3D, an arm jogger, cameras,
-  images, command buttons and a systemd application manager.
+  images, command buttons, a systemd application manager, a behavior tree inspector and
+  editor, the ROS log of every node, the robot's diagnostics, a file manager and a terminal.
 - **Plugins**: widgets of your own, with server-side code if they need it, as npm or ROS packages.
 - **One process**: a ROS 2 node in Node.js. Nothing to install on the robot but Node.js.
 
@@ -20,7 +21,8 @@ Tassello runs on the robot (or any machine on its ROS network) and needs:
 
 - ROS 2: Humble, Jazzy, Kilted or Lyrical, on x64 or arm64 (e.g. a Raspberry Pi), for which
   [rclnodejs](https://github.com/RobotWebTools/rclnodejs) ships prebuilt binaries;
-- Node.js 22 or newer, and npm.
+- Node.js 22 or newer, and npm;
+- Python 3, which ROS 2 comes with: the Terminal widget's pseudo-terminals.
 
 ```bash
 npm install -g tassello
@@ -113,6 +115,12 @@ after the others on the devices already arranged.
 | **Image Viewer** | A static image: a file of the robot, typed (`/…`, `~/…`, `package://…`) or picked by browsing its folders, or an image uploaded from the page's device |
 | **Button** | Runs a bash command on the robot, showing its output. Takes its running colour until the command finishes, on every page showing it; pressing it again stops the command |
 | **Application Manager** | The robot's systemd services matching a name: their state, whether they start at boot, buttons to start, stop and restart them, and their journal |
+| **Behavior Tree Inspector** | What a BT.CPP behavior tree is doing, from its log (Nav2's `/behavior_tree_log`): the tree of its XML file with the running branch lit, each node's status, last result, counts and ports, and the latest transitions. As a graph (pan, zoom, follow the running nodes) or a list. Records the log into rosbags, and plays rosbags back at any speed |
+| **Behavior Tree Editor** | Edits a BT.CPP behavior tree's XML file of the robot as a graph: nodes from a palette (BT.CPP's, Nav2's, your libraries'), dragged where they go, moved with their children, their names and ports edited in a side panel. Subtrees, undo and redo, copy and paste, an XML view. Saves only what changed, never over changes made meanwhile |
+| **Logs** | The ROS log (`/rosout`), as rqt_console and swri_console show it: every node's messages coloured by level, the nodes running and those that logged with their counts, filtered by node, by level and by text (terms or a regular expression, to show or to hide). Pause, follow the newest, clear, download, and a message's details: where it was logged |
+| **Diagnostics** | The robot's diagnostics (`/diagnostics`, or the aggregator's `/diagnostics_agg`), as rqt_robot_monitor shows them: each status's level, the groups with the worst under them, those with problems unfolded. As a tree, as a list (the worst first) or as the latest changes of level, filtered by level and by text; a widget can be for some statuses only. A status's details: its message, hardware ID, values and latest changes. Pause, download, and forget the statuses no longer published |
+| **File Manager** | The robot's files: folders unfolded in place, places (home, the ROS workspaces, bookmarks) and the disks' free space, an entry's details and permissions, what takes a folder's space. Make, rename, cut, copy, paste, drag onto folders, delete, download (folders as `.tar.gz`) and upload (drop files and folders onto it). Text files edited in tabs as gedit does: highlighting, search and replace, undo; images and PGM maps shown |
+| **Terminal** | A shell on the robot, or a command (`htop`, `tmux attach`), in a full terminal: colours, full screen programs, the mouse. It outlives the page: reloaded, reconnected or shown again, it is as it was. On touch screens, the keys phones lack, as Termux has them: Esc, Tab, Ctrl, Alt, Home, End, the arrows, Page Up and Down, and while typing the terminal fills the screen above the on-screen keyboard |
 
 Their properties (topics, frames, speeds, colours, ...) are edited in the side panel of edit mode.
 
@@ -153,6 +161,141 @@ Notes on some of them:
 - **Image Viewer** reads only images (PNG, JPEG, GIF, WebP, BMP, SVG). Uploads are kept next to
   the panels (`~/.local/share/tassello/images`). Images are served sandboxed: an SVG cannot run
   scripts in the dashboard.
+- **Behavior Tree Inspector** follows a `nav2_msgs/BehaviorTreeLog` topic, which BT.CPP trees
+  log with Nav2's `RosTopicLogger`: Nav2's bt_navigator on `/behavior_tree_log`. Its *tree file*
+  is the XML the robot runs (`/…`, `~/…`, `package://…`, browsed or uploaded), read with its
+  includes and subtrees, and again when it changes; e.g. Nav2's default,
+  `package://nav2_bt_navigator/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml`.
+  Without it, the nodes are listed as the log names them. Since Jazzy, the log gives the nodes'
+  UIDs, which tell them apart exactly; before, nodes of the same name (a `RecoveryNode` named
+  after its action) are told apart by their statuses and their parents'. The log only says what
+  changes: the server follows it for every page, and for 10 minutes after the last one closes,
+  so that a page opened later sees the nodes as they are. A node reset to idle by its parent
+  shows how it last ended.
+
+  Its record button records the log on the robot with `ros2 bag record`, into a new folder
+  (`<recordings folder>/behavior_tree_<date>_<time>` by default), until pressed again: every
+  page showing the topic shows it recording. Its playback button opens a rosbag of the robot
+  (a bag's folder, or its `.mcap` or `.db3` file, e.g. of a whole run recorded with
+  `ros2 bag record -a`) and plays its log in the widget, on the tree of its file, without
+  publishing anything: pause, seek and choose the speed (0.1× to 16×). Bags of Humble and of
+  Jazzy are read either way; SQLite bags need Node.js 22.13, zstd compressed MCAP 22.15.
+- **Behavior Tree Editor** edits one BehaviorTree of the file at a time (its toolbar switches
+  between them, adds new ones, and double clicking a subtree opens its tree, even in an included
+  file). Add a node from the palette by dragging it where it goes (into a node, or beside one), or
+  click it to add it into the selected node, or after it. Drag nodes to move them with their
+  children. The side panel edits the selected node's name and ports, with their types, defaults
+  and descriptions from its model, and its other attributes (BT.CPP 4's `_skipIf`, `_while`…);
+  it moves, duplicates, wraps, unwraps and replaces it. What BT.CPP would refuse, such as a
+  decorator without its child, is marked. Keys: Delete, Ctrl+Z, Ctrl+Shift+Z, Ctrl+C, Ctrl+X,
+  Ctrl+V, Ctrl+D, Ctrl+S, the arrows to move the selection (Alt: the node).
+
+  The palette has BT.CPP's nodes (of the file's format, `BTCPP_format`), Nav2's (its
+  `nav2_tree_nodes.xml`, when installed), those of the file's `TreeNodesModel` and includes, and
+  those of the *node libraries*: XML files of `TreeNodesModel`, as Groot exports them, set in the
+  widget's properties or loaded from the palette. Saving writes back only the elements changed,
+  the rest of the file (comments, blank lines, indentation) as it was. The file is read again when
+  it changes on the robot: without changes in the editor it is shown at once, with changes the
+  editor asks which to keep, and a save over a file changed since it was read is refused.
+  Uploads, and files the server cannot write, are saved elsewhere with *Save as*. The editor keeps
+  its changes while the page is open, and the page asks before closing with changes not saved.
+- **Logs** follows `/rosout` (`rcl_interfaces/msg/Log`), on which every node's logger publishes.
+  Its list of nodes has those running in the ROS graph and those that logged, with their
+  warnings and errors: choose some to see only theirs. A node's logger is named after it, dots
+  for slashes (`robot1.amcl` for `/robot1/amcl`). The level buttons show and hide each level
+  (Shift+click: that level only); *Include* and *Exclude* keep or drop the messages containing any
+  of their terms, separated by `;`, or matching a regular expression. Pausing holds the list while
+  the new messages wait; clearing empties it for this page. A message clicked shows whole, with its
+  file, line and function; the arrow keys go through the list. *Download* saves the messages shown
+  as ROS prints them (`[WARN] [1729435407.512346] [robot1.amcl]: ...`). The widget's properties
+  set its nodes (names or globs, e.g. `amcl, *_server`: one widget per subsystem), the levels and
+  filters it opens with, and the time shown: the clock, ROS stamps, or none. The server follows the
+  log for every page, keeping its latest 10,000 messages, and for 10 minutes after the last page
+  closes: a page opened later sees what was logged meanwhile, and when first opened, what each
+  node logged in its last 10 seconds (rosout's own history).
+- **Diagnostics** follows a `diagnostic_msgs/msg/DiagnosticArray` topic: `/diagnostics`, on which
+  every node's `diagnostic_updater` publishes its statuses (named `node: task`, grouped by node),
+  or `/diagnostics_agg`, the aggregator's tree of them (`/Robot/Sensors/Lidar`). A group shows the
+  worst level under it; one the aggregator puts in error only because some statuses under it are
+  stale shows as stale. A status not received for 5 s, or for 3 of its periods if it is slower, is
+  stale: what published it stopped. The level buttons show and hide each level (Shift+click: that
+  level only), counting the statuses, not the groups that sum them up; *Filter* keeps the statuses
+  whose name, message or hardware ID contain any of its terms, separated by `;`, or match a
+  regular expression, and a group's with all those under it. The groups with problems unfold, and
+  stay unfolded once these are gone, until folded; the arrow keys go through the tree and fold
+  and unfold it. A status clicked shows its message, hardware ID, values and latest changes of
+  level. Pausing holds the statuses as they are; *Forget* hides those no longer published, until
+  they are again; *Download* saves the statuses shown, the worst first, with their values (or the
+  changes shown). The widget's properties set its statuses (names, paths or globs, e.g.
+  `Sensors, motor_*`: from the root if they start with `/`, else at any depth), and the levels,
+  filter and view it opens with. The server follows the diagnostics for every page, and for 10
+  minutes after the last page closes, keeping the latest status of each name and their latest
+  1,000 changes of level.
+- **File Manager** opens its *folder* (`~` by default; `/…`, `~/…`, `package://…`) and lists it
+  with its entries' sizes and times, sorted by name (naturally: `run_2` before `run_10`), size or
+  time, folders first; the chevrons unfold folders in place. Its places are home, the root, the
+  ROS installations and workspaces sourced (`AMENT_PREFIX_PATH`), its *bookmarks* (the widget's,
+  and those made in the page, kept by the browser) and the disks, with their free space. Click to
+  select (Ctrl, Shift: several), double click (on touch screens tap) to open: folders, text files
+  into the editor, images (PNG, JPEG, SVG…, and PGM maps, converted on the robot) into a viewer.
+  Right click, or the ⋯ of a row, for the rest: download (a folder, or several entries, as one
+  `.tar.gz`), cut, copy and paste (between file managers too), duplicate, move or copy to a folder
+  picked, rename (F2, in place), copy the path, details, delete (there is no trash: it asks
+  first). Drag entries onto a folder, a place or the address bar's folders to move them (Ctrl:
+  copy them); drop files or folders from the computer to upload them, with their progress. Where
+  names are taken, it asks: replace, keep both (`map (2).yaml`) or skip. *Details* show an entry's
+  kind, size (a folder's computed on demand), times, owner, mode, link and disk, an image's
+  preview, and change its permissions; *what takes the space* shows the disks (size, use, free
+  space, inodes when short) and analyzes the folder: its largest entries, its files by type, the
+  largest and the latest files under it, on its disk only, for 15 s at most. Keys: the arrows
+  (Left and Right fold), Enter, Backspace, Alt+arrows (up, back, forward), Delete, F2, Ctrl+A,
+  Ctrl+C, Ctrl+X, Ctrl+V, Ctrl+F (filter), Ctrl+L (type a path), Ctrl+H (hidden files), and typing
+  a name's first letters.
+
+  Text files (UTF-8, 5 MB at most) open in tabs, edited as with gedit: line numbers, the line of
+  the cursor lit, syntax highlighting (YAML, XML for URDF, xacro, launch and SDF, Python, C and
+  C++, CMake, JSON, shell, INI, TOML and systemd units, Markdown, ROS interfaces), search and
+  replace (case, whole words, regular expressions with `$1`), Tab and Shift+Tab indenting the lines
+  selected, new lines indented as the one before, Ctrl+/ commenting lines out, go to line (Ctrl+I),
+  undo and redo a word at a time, long lines wrapped on demand (then not highlighted). The status
+  line shows the cursor's line and column, and switches the highlighting, the indentation and the
+  line ends (kept as the file has them, LF or CRLF). As the behavior tree editor, it saves only
+  over the version read: a file changed on the robot is shown at once without changes in the
+  editor, with changes the editor asks which to keep, and a save over a file changed since it was
+  read is refused. *Save as* writes elsewhere, e.g. a file the server's user cannot write. Changes
+  are kept while the page is open, and the page asks before closing with changes not saved.
+
+  The folders shown and the files open are read again every 3 s. A widget can *stay in its
+  folder* (e.g. one for the maps, or the rosbags) or be *read-only*: these are the page's choices,
+  not a protection (see Security).
+- **Terminal** runs the login shell of the server's user (`$SHELL -l`, as SSH does: its
+  `~/.bashrc` and the ROS setup Tassello was started with), or the widget's *command* through it,
+  in its *folder* (`~` by default; `/…`, `~/…`, `package://…`), on a pseudo-terminal of its own:
+  `TERM=xterm-256color`, true colour, full screen programs (vim, htop, less) and their mouse. A
+  terminal belongs to the browser's tab: reloading the page, losing the connection or showing
+  another panel and coming back finds it as it was, what it printed meanwhile included, screens of
+  full screen programs too. A terminal no page shows is hung up after an hour (its programs get
+  SIGHUP, as when a terminal window is closed), as is the one unseen the longest when 16 are open:
+  for jobs that should outlive it, `tmux` or `nohup`. A *command* such as `tmux new -A -s robot` gives every page, and every
+  device, the same session. When the program ends, Enter or *Restart* starts it again; *Restart*
+  also hangs up a program that hangs. Changing the widget's command or folder starts it anew.
+
+  Copy with Ctrl+C while text is selected (it interrupts otherwise) or Ctrl+Shift+C, paste with
+  Ctrl+Shift+V or the toolbar's button (pages served over http cannot read the clipboard: it opens
+  a box to paste into, on phones too). The toolbar changes the size of the text for this device, as
+  pinching does, and fills the window with the terminal.
+
+  On touch screens (or always, or never: *Extra keys*) the keys phones lack are under the
+  terminal, as Termux has them: Esc, `/`, `-`, Home, ↑, End, Page Up, then Tab, Ctrl, Alt, ←, ↓,
+  →, Page Down. Tapped, they type without closing the on-screen keyboard. Ctrl, Alt and Shift
+  apply to the next key, of the row or of the keyboard (Ctrl, then `c`: interrupt); tapped twice,
+  or held, they stay until tapped again. Swiping up on a key, or holding it, types what its corner
+  shows (`\`, `|`, `~`); the arrows repeat while held. Their *layout* is a property: a line per
+  row, keys by name (`ESC TAB CTRL ALT SHIFT HOME END PGUP PGDN UP DOWN LEFT RIGHT INS DEL BKSP
+  ENTER SPACE F1`…`F12 KEYBOARD PASTE`) or what they type (`~`, `|`, `ros2`), what swiping up
+  types after a colon (`-:|`). While the on-screen keyboard is open, the terminal fills the screen
+  above it, the keys right above the keyboard (*Full screen while typing*). One finger scrolls (the
+  scrollback, or the program: less, htop), flung or not; two pinch the text's size.
 
 ## Plugins
 
@@ -180,8 +323,14 @@ and ship example panels. See **[docs/plugins.md](docs/plugins.md)**.
 ## Security
 
 Tassello has no login. **Anyone who can open the page can drive the robot, run any command as
-the server's user and read its images**: keep it on a network you trust, or behind a reverse
-proxy with authentication (it serves everything under `/`, its WebSocket at `/ws`).
+the server's user (the Terminal, a shell), and read, write, upload, move and delete any of the
+files that user can (the File Manager)**: keep it on a network you trust, or behind a reverse proxy
+with authentication (it serves everything under `/`, its WebSocket at `/ws`). Changes to the files
+are accepted from the dashboard's own pages only (they send a header that another site's page
+cannot), and the root, the home folder and the system's top folders (`/usr`, `/etc`…) are never
+deleted nor moved. Terminals open from the dashboard's own pages only too: those whose origin is
+the host they reached (the `Host` header, or the `X-Forwarded-Host` a reverse proxy sets), which
+another site's page cannot pretend.
 
 ## How it works
 
@@ -192,6 +341,7 @@ proxy with authentication (it serves everything under `/`, its WebSocket at `/ws
                                                                         ├─ rclnodejs: ROS
                                                                         ├─ sharp: raw images to JPEG, maps to PNG
                                                                         ├─ bash: the buttons' commands
+                                                                        ├─ python3: the terminals' pseudo-terminals
                                                                         └─ the plugins' server sides
 ```
 
@@ -207,7 +357,24 @@ Safety and bandwidth are the server's concern:
   of their publishers, so latched maps arrive.
 - Topics are subscribed once, whatever the number of pages, with the type and QoS of their
   publishers; TF only while a page shows the robot.
+- Behavior tree logs, streams of transitions, are followed whole, none dropped: each page gets
+  the nodes that changed, at most 10 times a second, however fast the tree ticks.
+- The ROS log is followed once for every page: each gets the new messages at most 10 times a
+  second, at most 500 at a time (a node logging faster has some skipped, which the page shows).
+  Only the rows in sight are drawn.
+- Diagnostics are followed once for every page: each gets the statuses that changed, at most 4
+  times a second, not those received the same again. Subscribed best effort, they come from
+  every publisher, whatever its QoS.
 - A button runs the command saved in its panel, never one sent by the page.
+- A terminal's pseudo-terminal is opened by a few lines of Python (ROS 2's own), no native module
+  to build. Its output is also played on a terminal of the server's own (xterm.js, headless), which
+  paces the program, never the pages: a page gets at most 256 KB ahead of what it has drawn, and a
+  page further behind (a slow phone, a hidden tab, a flood of output) gets the screen as it is
+  instead of all that led to it. A page that reconnects gets what it missed, from the last 1 MB.
+- The File Manager's folders are read again every 3 s, and answered "unchanged" while they are;
+  the largest are listed in part (5,000 entries), and only the rows in sight are drawn. Uploads
+  and downloads are streamed, folders archived by `tar` as they are sent; saves replace files at
+  once (a temporary file renamed over them).
 
 ## Developing
 

package/dist/server/behavior_tree_file.d.ts

@@ -0,0 +1,17 @@
+import type { BehaviorTreeInfo, BtNode, BtNodeKind } from '../shared/protocol.ts';
+import { type XmlElement } from '../shared/xml.ts';
+import { type Logger } from './util.ts';
+export interface BehaviorTreeFile {
+    treeId: string;
+    nodes: BtNode[];
+    warnings: string[];
+    files: string[];
+}
+export declare function resolveTreeFile(source: string, uploadsDir: string, home?: string): string;
+export declare function instantiate(trees: Map<string, XmlElement>, mainId: string, kinds: Map<string, BtNodeKind>, warnings: string[]): BtNode[];
+export declare function loadBehaviorTree(file: string): Promise<BehaviorTreeFile>;
+export type TreeInfo = Omit<BehaviorTreeInfo, 'type' | 'id'>;
+export declare function readTree(source: string, uploadsDir: string, logger: Logger): Promise<{
+    tree: TreeInfo;
+    files: string[];
+}>;

package/dist/server/behavior_tree_file.js

@@ -0,0 +1,232 @@
+// The behavior trees' XML files (BT.CPP's format, 3 and 4), for the behavior
+// tree inspector widgets: the tree the robot runs, as BT.CPP instantiates it,
+// its nodes in the order of their UIDs: depth first, from the first child of
+// the main BehaviorTree, each SubTree followed by its tree's nodes.
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { EXPLICIT, guessKind } from '../shared/bt_nodes.js';
+import { parseXml } from '../shared/xml.js';
+import { isUploadName } from './files.js';
+import { errorMessage, packageShareDirectory } from './util.js';
+// Beyond this, a file (or a recursion of subtrees missed) is not a tree to show
+const MAX_NODES = 5000;
+const PACKAGE_URL = /^package:\/\/([^/]+)\/(.+)$/;
+// The XML file a widget names: a robot path (/…, ~/…), package://… or
+// uploads/<name>. Throws for anything else: only XML files are read.
+export function resolveTreeFile(source, uploadsDir, home = os.homedir()) {
+    const value = source.trim();
+    let file;
+    if (value.startsWith('uploads/')) {
+        const name = value.slice('uploads/'.length);
+        if (!isUploadName(name)) {
+            throw new Error(`No upload "${name}"`);
+        }
+        file = path.join(uploadsDir, name);
+    }
+    else if (PACKAGE_URL.test(value)) {
+        const [, name, relative] = PACKAGE_URL.exec(value);
+        const share = packageShareDirectory(name);
+        if (!share) {
+            throw new Error(`No package "${name}": is its workspace sourced?`);
+        }
+        file = path.resolve(share, relative);
+        if (!file.startsWith(share + path.sep)) {
+            throw new Error(`"${value}" is not in its package`);
+        }
+    }
+    else {
+        const expanded = value === '~' || value.startsWith('~/') ? path.join(home, value.slice(1)) : value;
+        if (!path.isAbsolute(expanded)) {
+            throw new Error(`Not a path: "${source}" (/…, ~/…, package://…)`);
+        }
+        file = path.resolve(expanded);
+    }
+    if (path.extname(file).toLowerCase() !== '.xml') {
+        throw new Error(`Not an XML file: "${source}"`);
+    }
+    return file;
+}
+function modelKinds(root, kinds) {
+    for (const model of root.children.filter((child) => child.name === 'TreeNodesModel')) {
+        for (const node of model.children) {
+            const kind = EXPLICIT[node.name];
+            if (kind && node.attributes.ID) {
+                kinds.set(node.attributes.ID, kind);
+            }
+        }
+    }
+}
+// Nav2's node models, when installed: what its nodes are
+let nav2Kinds = null;
+function loadNav2Kinds() {
+    nav2Kinds ??= (async () => {
+        const kinds = new Map();
+        const share = packageShareDirectory('nav2_behavior_tree');
+        if (share) {
+            try {
+                modelKinds(parseXml(await fs.readFile(path.join(share, 'nav2_tree_nodes.xml'), 'utf8')), kinds);
+            }
+            catch {
+                // Not there, or not readable: the known nodes and the guesses will do
+            }
+        }
+        return kinds;
+    })();
+    return nav2Kinds;
+}
+// The tree's nodes, from the main BehaviorTree; subtrees not defined, and
+// recursions, are reported and left unexpanded
+export function instantiate(trees, mainId, kinds, warnings) {
+    const nodes = [];
+    const visit = (element, parent, expanding) => {
+        if (nodes.length >= MAX_NODES) {
+            throw new Error(`The tree has more than ${MAX_NODES} nodes`);
+        }
+        const explicit = EXPLICIT[element.name];
+        const { name, ...ports } = element.attributes;
+        let type = element.name;
+        if (explicit === 'subtree') {
+            type = 'SubTree';
+        }
+        else if (explicit && ports.ID) {
+            type = ports.ID;
+            delete ports.ID;
+        }
+        const subtreeId = explicit === 'subtree' ? (ports.ID ?? '') : '';
+        const index = nodes.length;
+        nodes.push({
+            name: name ?? (subtreeId || type),
+            type,
+            kind: explicit ?? kinds.get(type) ?? guessKind(type, element.children.length),
+            parent,
+            ports,
+        });
+        if (explicit !== 'subtree') {
+            for (const child of element.children) {
+                visit(child, index, expanding);
+            }
+            return;
+        }
+        const definition = trees.get(subtreeId);
+        if (!subtreeId) {
+            warnings.push(`A SubTree without ID, line ${element.line}`);
+        }
+        else if (expanding.includes(subtreeId)) {
+            warnings.push(`The subtree ${subtreeId} includes itself, line ${element.line}`);
+        }
+        else if (!definition) {
+            warnings.push(`No BehaviorTree ${subtreeId}, for the SubTree of line ${element.line}`);
+        }
+        else if (definition.children[0]) {
+            visit(definition.children[0], index, [...expanding, subtreeId]);
+        }
+    };
+    const main = trees.get(mainId)?.children[0];
+    if (!main) {
+        throw new Error(`The BehaviorTree ${mainId} is empty`);
+    }
+    visit(main, -1, [mainId]);
+    return nodes;
+}
+// The tree of the file, its includes followed (relative to it, or to their
+// ros_pkg's share directory). The main tree is the one main_tree_to_execute
+// names, else the first of the file that no other uses as a subtree.
+export async function loadBehaviorTree(file) {
+    const trees = new Map();
+    // The trees of the file itself, in order
+    const own = [];
+    const kinds = new Map(await loadNav2Kinds());
+    const warnings = [];
+    const files = [];
+    let mainId = '';
+    const read = async (current, top) => {
+        files.push(current);
+        let root;
+        try {
+            root = parseXml(await fs.readFile(current, 'utf8'));
+        }
+        catch (e) {
+            const code = e.code;
+            throw new Error(`Cannot read ${current}: ${code ?? errorMessage(e)}`);
+        }
+        if (root.name !== 'root') {
+            throw new Error(`${current} is not a behavior tree: its root element is <${root.name}>, not <root>`);
+        }
+        if (top) {
+            mainId = root.attributes.main_tree_to_execute ?? '';
+        }
+        modelKinds(root, kinds);
+        for (const child of root.children) {
+            if (child.name === 'include') {
+                const { ros_pkg: rosPackage, path: relative = '' } = child.attributes;
+                const share = rosPackage ? packageShareDirectory(rosPackage) : path.dirname(current);
+                if (!share) {
+                    warnings.push(`Not included: ${relative}, of the package ${rosPackage}, not found`);
+                    continue;
+                }
+                const included = path.resolve(share, relative);
+                if (files.includes(included)) {
+                    continue;
+                }
+                try {
+                    await read(included, false);
+                }
+                catch (e) {
+                    warnings.push(`Not included: ${errorMessage(e)}`);
+                }
+            }
+            else if (child.name === 'BehaviorTree') {
+                const id = child.attributes.ID ?? (trees.size === 0 ? 'MainTree' : `BehaviorTree ${trees.size + 1}`);
+                if (trees.has(id)) {
+                    warnings.push(`BehaviorTree ${id} defined twice: the first one is shown`);
+                    continue;
+                }
+                trees.set(id, child);
+                if (top) {
+                    own.push(id);
+                }
+            }
+        }
+    };
+    await read(file, true);
+    if (trees.size === 0) {
+        throw new Error(`${file} has no BehaviorTree`);
+    }
+    if (mainId && !trees.has(mainId)) {
+        warnings.push(`No BehaviorTree ${mainId}, the main_tree_to_execute`);
+        mainId = '';
+    }
+    if (!mainId) {
+        const used = new Set();
+        const collect = (element) => {
+            if (EXPLICIT[element.name] === 'subtree' && element.attributes.ID) {
+                used.add(element.attributes.ID);
+            }
+            element.children.forEach(collect);
+        };
+        trees.forEach(collect);
+        const candidates = [...own, ...trees.keys()];
+        mainId = candidates.find((id) => !used.has(id)) ?? candidates[0];
+    }
+    return { treeId: mainId, nodes: instantiate(trees, mainId, kinds, warnings), warnings, files };
+}
+// The tree a widget names (empty: none), or why it could not be read; and
+// the files read, to read it again when they change
+export async function readTree(source, uploadsDir, logger) {
+    const tree = { treeId: '', nodes: [], error: null, warnings: [] };
+    if (!source) {
+        return { tree, files: [] };
+    }
+    let files = [];
+    try {
+        const file = resolveTreeFile(source, uploadsDir);
+        files = [file];
+        const loaded = await loadBehaviorTree(file);
+        return { tree: { treeId: loaded.treeId, nodes: loaded.nodes, error: null, warnings: loaded.warnings }, files: loaded.files };
+    }
+    catch (e) {
+        logger.warn(`Behavior tree ${source}: ${errorMessage(e)}`);
+        return { tree: { ...tree, error: errorMessage(e) }, files };
+    }
+}

package/dist/server/behavior_tree_files.d.ts

@@ -0,0 +1,17 @@
+import type { BehaviorTreeFile, BehaviorTreeModels, BehaviorTreeSaved } from '../shared/protocol.ts';
+import { type Logger } from './util.ts';
+export type FileState = Omit<BehaviorTreeFile, 'type' | 'id'>;
+export type ModelsState = Omit<BehaviorTreeModels, 'type' | 'id'>;
+export interface BehaviorTreeFileWatcher {
+    onFile: (file: FileState) => void;
+    onModels: (models: ModelsState) => void;
+}
+export declare class BehaviorTreeFiles {
+    private readonly uploadsDir;
+    private readonly logger;
+    private readonly watched;
+    constructor(uploadsDir: string, logger: Logger);
+    watch(source: string, libraries: string[], watcher: BehaviorTreeFileWatcher): () => void;
+    save(source: string, text: string, base: string | null, create: boolean): Promise<BehaviorTreeSaved>;
+    stopAll(): void;
+}