bytesim 0.1.0__tar.gz

bytesim-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test and tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+
+# Editors and OS
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# ByteSim's default save file
+bytesim.json

bytesim-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release.
+
+- Gateways, routers, switches and computers with any number of ports or NICs;
+  cabling by typing device ids.
+- Automatic layered layout; moving devices with the keyboard or mouse; panning.
+- Nestable groups drawn as frames.
+- Addressing as (network, 8-bit host); MACs named after their port; router
+  autoconfiguration, animated DHCP, ad-hoc fallback, static addresses.
+- Routing through gateways and between routers (cheapest path in cable hops),
+  with ARP shown for each hop and MAC learning on switches.
+- Ping, unicast and multicast with packet animation; graph mode for pure
+  connectivity.
+- Cable roles (data, control, fabric) and failure injection.
+- HA router clusters: virtual gateways, failover, split-brain detection,
+  quorum and witness policies.
+- BFS/DFS renumbering, one-shot or automatic (`renumber [auto] bfs|dfs [root]`).
+- Spanning tree (root bridges, blocked ports, failover, priorities), real
+  flooding, and broadcast storms with MAC flapping; `broadcast`, `stp`,
+  `demo loop`.
+- `clone <group>`: copy a group's devices, nested groups and internal cables.
+- Declarative YAML topologies (`bytesim/topology-v1`): templates, instances,
+  link macros; `load` reads them and `export` writes them (compact or exact).
+- Auto-numbering with `prefix(n)` (`s(2)`, `fab(1)`) in topology files and in
+  `group` / `clone`.
+- `ports copy a(x, y) b(y, z)`: give a group another group's outside cabling onto new
+  endpoints; `copy a(x, y) b(y, z)` does it while cloning.
+- `export script [readable|shortest|explicit] [file]`: synthesize the console commands that
+  rebuild the network, reusing repeated groups with clone / copy / ports copy; every
+  script is verified by replaying it. `run <file>` replays scripts.
+- Multi-level undo and redo (`undo [n]`, `redo [n]`, `history`, `u` / `U`), up to 100 steps.
+- JSON save and load; a `bytesim` command with `--demo` and `--run`.

bytesim-0.1.0/LICENSE

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

bytesim-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: bytesim
+Version: 0.1.0
+Summary: A text-mode network simulator: cable up gateways, routers, switches and computers, then watch DHCP, routing, multicast and HA failover in your terminal.
+Project-URL: Homepage, https://github.com/BytesAndCoffee/bytesim
+Project-URL: Documentation, https://github.com/BytesAndCoffee/bytesim/tree/main/docs
+Project-URL: Repository, https://github.com/BytesAndCoffee/bytesim
+Project-URL: Issues, https://github.com/BytesAndCoffee/bytesim/issues
+Project-URL: Changelog, https://github.com/BytesAndCoffee/bytesim/blob/main/CHANGELOG.md
+Author: Michael Yazdani
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dhcp,education,network,networking,routing,simulator,textual,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Education
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: textual>=6.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pyflakes; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ByteSim
+
+[![CI](https://github.com/BytesAndCoffee/bytesim/actions/workflows/ci.yml/badge.svg)](https://github.com/BytesAndCoffee/bytesim/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/bytesim)](https://pypi.org/project/bytesim/)
+[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)](https://pypi.org/project/bytesim/)
+
+**A network simulator that runs in your terminal.** Add gateways, routers,
+switches and computers, cable them together by typing device ids, and watch
+DHCP, routing, multicast and router failover happen packet by packet.
+
+```
+                     ╭┄ rfab1 · HA ┄┄┄┄┄┄┄┄┄┄┄┄╮
+                     ┆ ┌────────┐    ┌────────┐ ┆
+                     ┆ │   r1   │    │   r2   │ ┆
+                     ┆ │ ●●○●●● │    │ ●●○●●● │ ┆
+                     ┆ └─┬┬─┬┬┬─┘    └─┬┬─┬┬┬─┘ ┆
+                     ╰┄┄┄││┄┃║║┄┄┄┄┄┄┄┄││┄┃║║┄┄┄╯
+          ┌──────────────┘└─┴┴┼──────────┼┼─┴┤║
+          │             ┌─────┴──────────┴┴──┼┴────────────┐
+     ╭┄┄┄┄│ fab1 ┄┄┄┄┄┄┄│┄┄┄┄┄┄┄╮      ╭┄┄┄┄│ fab2 ┄┄┄┄┄┄┄│┄┄┄┄┄┄┄╮
+     ┆ ┌──┴─────┐    ┌──┴─────┐ ┆      ┆ ┌──┴─────┐    ┌──┴─────┐ ┆
+     ┆ │   s1   │    │   s2   │ ┆      ┆ │   s3   │    │   s4   │ ┆
+     ┆ │ ●●●●○○ │    │ ●●●○○○ │ ┆      ┆ │ ●●●●○○ │    │ ●●●○○○ │ ┆
+     ┆ └─┬─┬┬───┘    └─┬─┬────┘ ┆      ┆ └─┬─┬┬───┘    └─┬─┬────┘ ┆
+     ╰┄┄┄│┄││┄┄┄┄┄┄┄┄┄┄│┄│┄┄┄┄┄┄╯      ╰┄┄┄│┄││┄┄┄┄┄┄┄┄┄┄│┄│┄┄┄┄┄┄╯
+         └─●•••─────┬─┘ │                  │ ││          │ └─────┐
+         ┌─┴──┐    ┌┴───┐    ┌────┐      ┌─┴──┐    ┌────┐    ┌────┐
+         │ c1 │    │ c2 │    │ c3 │      │ c4 │    │ c5 │    │ c6 │
+         └────┘    └────┘    └────┘      └────┘    └────┘    └────┘
+         (1,10)    (1,11)    (1,12)      (2,10)    (2,11)    (2,12)
+```
+
+ByteSim keeps what matters about networking (graphs, broadcast domains,
+forwarding, failure) and leaves out the detail that gets in the way:
+
+- **Devices with real ports.** Routers and switches can have any number of
+  ports, and computers can have several network cards. Every port shows on
+  the device as `○` (free) or `●` (in use).
+- **Cabling by typing.** `r1 s2` connects two devices using their first free
+  ports. `r1:3 s2:8` picks the ports.
+- **Automatic layout**, with arrow keys or the mouse to move things yourself.
+- **Simple addressing.** An address is a pair: a network id and an 8-bit host
+  number, like `(2,14)`. MAC addresses name the physical port: `R1A` is port 1
+  of router r1.
+- **DHCP and ad-hoc addressing**, animated as broadcast-then-reply.
+- **Routing** through gateways and between routers, with ARP shown for every hop.
+- **Unicast, ping and multicast.** With multicast you can see the packet copied
+  wherever the paths split.
+- **Cable roles** (data, control, fabric) and failures you can trigger by hand.
+- **Switching loops**: spanning tree with root bridges and blocked ports, and
+  real broadcast storms (frames multiplying, MAC tables flapping) when STP is off.
+- **HA router clusters** with a shared virtual gateway, failover, split-brain,
+  and quorum or witness policies.
+- **Nested groups** drawn as labelled frames, which you can **clone** along with
+  their internal cables.
+- **BFS/DFS renumbering**, once or automatically after every change, so ids
+  follow the network's shape.
+- **Graph mode**, which ignores addressing so you can explore pure connectivity.
+- **Topology files.** Describe networks in YAML with reusable templates and link
+  macros (`mesh: [routers, switches]`), then load or export them.
+- **Construction scripts.** `export script` writes the console commands that
+  rebuild your network, reusing repeated parts with `clone` and `copy`. Each
+  script is checked by replaying it before you get it, and `run` replays it.
+
+## Install
+
+```sh
+pip install bytesim
+```
+
+Requires Python 3.10+ and a terminal with Unicode and colour support.
+
+## Quick start
+
+```sh
+bytesim --demo basic        # a small routed network
+bytesim --demo ha           # a clustered router pair between two fabrics
+bytesim --demo loop         # a switch loop with STP off: set off a storm
+bytesim mynet.json          # open a saved network
+bytesim campus.yaml         # build one from a topology file
+```
+
+Then, at the command line at the bottom of the screen:
+
+```text
+add r 4            add a router with 4 ports        → r1
+add s 8            add an 8-port switch             → s1
+add c 1 3          add three computers with 1 NIC   → c1 c2 c3
+r1 s1              cable r1 to s1
+s1 c1              cable s1 to c1 (c1 gets an address by DHCP)
+ping c1 c2         watch the echo request and reply
+```
+
+Type `help` for every command. Press `Esc` to switch from the command line to
+the canvas, where the arrow keys move the selected device and `Tab` cycles
+through devices.
+
+## Documentation
+
+- [User guide](docs/guide.md): concepts, every command, keys, worked examples
+- [Architecture](docs/architecture.md): how the code is organised, and how to add a command
+- [Topology format](docs/topology-format.md): templates and link macros in YAML
+- [Construction scripts](docs/scripts.md): `export script` and `run`, with a tutorial
+- [Save file format](docs/file-format.md)
+- [Changelog](CHANGELOG.md)
+
+## Using the model from Python
+
+The simulation is a plain Python model with no UI dependency:
+
+```python
+from bytesim import Network
+
+net = Network()
+net.add("r"); net.add("s"); net.add("c"); net.add("c")
+net.connect("r1", None, "s1", None)
+net.connect("s1", None, "c1", None)
+net.connect("s1", None, "c2", None)
+net.reconcile()                       # router autoconfig + DHCP
+
+print(net.iface("c1", 1).addr)        # (1, 10)
+for src, dst, frames in net.route("c1", ("c2", 1)):
+    print(src, "→", dst, [d for d, _ in frames])
+```
+
+## Development
+
+```sh
+git clone https://github.com/BytesAndCoffee/bytesim
+cd bytesim
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python -m build && twine check dist/*
+```
+
+## License
+
+MIT © Michael Yazdani. See [LICENSE](LICENSE).

bytesim-0.1.0/README.md

@@ -0,0 +1,139 @@
+# ByteSim
+
+[![CI](https://github.com/BytesAndCoffee/bytesim/actions/workflows/ci.yml/badge.svg)](https://github.com/BytesAndCoffee/bytesim/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/bytesim)](https://pypi.org/project/bytesim/)
+[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)](https://pypi.org/project/bytesim/)
+
+**A network simulator that runs in your terminal.** Add gateways, routers,
+switches and computers, cable them together by typing device ids, and watch
+DHCP, routing, multicast and router failover happen packet by packet.
+
+```
+                     ╭┄ rfab1 · HA ┄┄┄┄┄┄┄┄┄┄┄┄╮
+                     ┆ ┌────────┐    ┌────────┐ ┆
+                     ┆ │   r1   │    │   r2   │ ┆
+                     ┆ │ ●●○●●● │    │ ●●○●●● │ ┆
+                     ┆ └─┬┬─┬┬┬─┘    └─┬┬─┬┬┬─┘ ┆
+                     ╰┄┄┄││┄┃║║┄┄┄┄┄┄┄┄││┄┃║║┄┄┄╯
+          ┌──────────────┘└─┴┴┼──────────┼┼─┴┤║
+          │             ┌─────┴──────────┴┴──┼┴────────────┐
+     ╭┄┄┄┄│ fab1 ┄┄┄┄┄┄┄│┄┄┄┄┄┄┄╮      ╭┄┄┄┄│ fab2 ┄┄┄┄┄┄┄│┄┄┄┄┄┄┄╮
+     ┆ ┌──┴─────┐    ┌──┴─────┐ ┆      ┆ ┌──┴─────┐    ┌──┴─────┐ ┆
+     ┆ │   s1   │    │   s2   │ ┆      ┆ │   s3   │    │   s4   │ ┆
+     ┆ │ ●●●●○○ │    │ ●●●○○○ │ ┆      ┆ │ ●●●●○○ │    │ ●●●○○○ │ ┆
+     ┆ └─┬─┬┬───┘    └─┬─┬────┘ ┆      ┆ └─┬─┬┬───┘    └─┬─┬────┘ ┆
+     ╰┄┄┄│┄││┄┄┄┄┄┄┄┄┄┄│┄│┄┄┄┄┄┄╯      ╰┄┄┄│┄││┄┄┄┄┄┄┄┄┄┄│┄│┄┄┄┄┄┄╯
+         └─●•••─────┬─┘ │                  │ ││          │ └─────┐
+         ┌─┴──┐    ┌┴───┐    ┌────┐      ┌─┴──┐    ┌────┐    ┌────┐
+         │ c1 │    │ c2 │    │ c3 │      │ c4 │    │ c5 │    │ c6 │
+         └────┘    └────┘    └────┘      └────┘    └────┘    └────┘
+         (1,10)    (1,11)    (1,12)      (2,10)    (2,11)    (2,12)
+```
+
+ByteSim keeps what matters about networking (graphs, broadcast domains,
+forwarding, failure) and leaves out the detail that gets in the way:
+
+- **Devices with real ports.** Routers and switches can have any number of
+  ports, and computers can have several network cards. Every port shows on
+  the device as `○` (free) or `●` (in use).
+- **Cabling by typing.** `r1 s2` connects two devices using their first free
+  ports. `r1:3 s2:8` picks the ports.
+- **Automatic layout**, with arrow keys or the mouse to move things yourself.
+- **Simple addressing.** An address is a pair: a network id and an 8-bit host
+  number, like `(2,14)`. MAC addresses name the physical port: `R1A` is port 1
+  of router r1.
+- **DHCP and ad-hoc addressing**, animated as broadcast-then-reply.
+- **Routing** through gateways and between routers, with ARP shown for every hop.
+- **Unicast, ping and multicast.** With multicast you can see the packet copied
+  wherever the paths split.
+- **Cable roles** (data, control, fabric) and failures you can trigger by hand.
+- **Switching loops**: spanning tree with root bridges and blocked ports, and
+  real broadcast storms (frames multiplying, MAC tables flapping) when STP is off.
+- **HA router clusters** with a shared virtual gateway, failover, split-brain,
+  and quorum or witness policies.
+- **Nested groups** drawn as labelled frames, which you can **clone** along with
+  their internal cables.
+- **BFS/DFS renumbering**, once or automatically after every change, so ids
+  follow the network's shape.
+- **Graph mode**, which ignores addressing so you can explore pure connectivity.
+- **Topology files.** Describe networks in YAML with reusable templates and link
+  macros (`mesh: [routers, switches]`), then load or export them.
+- **Construction scripts.** `export script` writes the console commands that
+  rebuild your network, reusing repeated parts with `clone` and `copy`. Each
+  script is checked by replaying it before you get it, and `run` replays it.
+
+## Install
+
+```sh
+pip install bytesim
+```
+
+Requires Python 3.10+ and a terminal with Unicode and colour support.
+
+## Quick start
+
+```sh
+bytesim --demo basic        # a small routed network
+bytesim --demo ha           # a clustered router pair between two fabrics
+bytesim --demo loop         # a switch loop with STP off: set off a storm
+bytesim mynet.json          # open a saved network
+bytesim campus.yaml         # build one from a topology file
+```
+
+Then, at the command line at the bottom of the screen:
+
+```text
+add r 4            add a router with 4 ports        → r1
+add s 8            add an 8-port switch             → s1
+add c 1 3          add three computers with 1 NIC   → c1 c2 c3
+r1 s1              cable r1 to s1
+s1 c1              cable s1 to c1 (c1 gets an address by DHCP)
+ping c1 c2         watch the echo request and reply
+```
+
+Type `help` for every command. Press `Esc` to switch from the command line to
+the canvas, where the arrow keys move the selected device and `Tab` cycles
+through devices.
+
+## Documentation
+
+- [User guide](docs/guide.md): concepts, every command, keys, worked examples
+- [Architecture](docs/architecture.md): how the code is organised, and how to add a command
+- [Topology format](docs/topology-format.md): templates and link macros in YAML
+- [Construction scripts](docs/scripts.md): `export script` and `run`, with a tutorial
+- [Save file format](docs/file-format.md)
+- [Changelog](CHANGELOG.md)
+
+## Using the model from Python
+
+The simulation is a plain Python model with no UI dependency:
+
+```python
+from bytesim import Network
+
+net = Network()
+net.add("r"); net.add("s"); net.add("c"); net.add("c")
+net.connect("r1", None, "s1", None)
+net.connect("s1", None, "c1", None)
+net.connect("s1", None, "c2", None)
+net.reconcile()                       # router autoconfig + DHCP
+
+print(net.iface("c1", 1).addr)        # (1, 10)
+for src, dst, frames in net.route("c1", ("c2", 1)):
+    print(src, "→", dst, [d for d, _ in frames])
+```
+
+## Development
+
+```sh
+git clone https://github.com/BytesAndCoffee/bytesim
+cd bytesim
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python -m build && twine check dist/*
+```
+
+## License
+
+MIT © Michael Yazdani. See [LICENSE](LICENSE).

bytesim-0.1.0/docs/architecture.md

@@ -0,0 +1,186 @@
+# Architecture
+
+ByteSim has two halves: a pure-Python **model** that knows nothing about the
+screen, and a **Textual UI** that draws the model and turns typed commands
+into model calls.
+
+```
+src/bytesim/
+├── __init__.py          version, re-exports Network & friends
+├── __main__.py          python -m bytesim
+├── cli.py               argument parsing, starts the app
+├── constants.py         device kinds, sizes, token regexes, address constants
+├── demos.py             ready-made networks (basic, ha, loop)
+├── topology.py          the YAML topology format: load_topology(), dump_topology()
+├── scripting.py         ScriptRunner / replay(): run command scripts headlessly
+├── synthesis.py         export script: plan, find reuse, render, verify by replay
+├── model/               ── no UI imports below this line ──
+│   ├── types.py         Device, Link, Iface, NetError, fmt()
+│   ├── base.py          NetworkBase: the state + basic lookups
+│   ├── groups.py        nestable groups, frame bounds
+│   ├── cloning.py       clone_group(): devices, nested groups, internal cables
+│   ├── layer2.py        usable cables, broadcast domains, frame paths, MAC learning, graph-mode BFS
+│   ├── addressing.py    router autoconfig, DHCP, ad-hoc, reconcile()
+│   ├── routing.py       host → gateway → cheapest router path
+│   ├── ha.py            clusters: partitions, policies, virtual-gateway owners
+│   ├── layout.py        automatic arrangement
+│   ├── naming.py        BFS/DFS traversal, renumber()
+│   ├── stp.py           spanning tree, loop detection, flooding, storms
+│   ├── equivalence.py   canonical form of a network; differences()
+│   └── network.py       Network = all mixins + editing + JSON
+└── tui/
+    ├── app.py           ByteSimApp: layout, dispatch(), changed()
+    ├── canvas.py        NetCanvas: drawing, mouse/keys, packet animation
+    ├── cables.py        where cables run, line glyphs
+    ├── inspector.py     side-panel text
+    ├── command_input.py the command line with history
+    ├── help.py          `help` text
+    ├── theme.py         colours
+    └── commands/
+        ├── registry.py  @command decorator, collect()
+        ├── base.py      CommandHost: what handlers may use
+        ├── topology.py  add, link, del, ports, role, fail, files, mode…
+        ├── groups.py    group, ungroup, clone, cluster…
+        ├── addressing.py ip, dhcp, release, adhoc, dhcpd (+ animated DHCP)
+        ├── naming.py    renumber (one-shot and auto mode)
+        ├── switching.py broadcast, stp, storm reporting + flood animation
+        ├── scripting.py export script, run
+        ├── history.py   undo / redo (snapshot per changing command)
+        ├── interpreter.py tokens + dispatch (shared by the app and ScriptRunner)
+        └── traffic.py   ping, unicast, multicast
+```
+
+## The model
+
+`Network` (in `model/network.py`) is assembled from mixins that each own one
+concern and share the state defined in `NetworkBase`:
+
+| State | Meaning |
+|---|---|
+| `devices: dict[str, Device]` | `"r1"` → kind, number, port count, position, up/down |
+| `links: list[Link]` | cables: two (device, port) ends, role, up/down |
+| `groups: dict[str, list[str]]` | group → members (device ids or group names) |
+| `ifaces: dict[str, Iface]` | `"c1:1"` → mode, network, host, gateway, how it was obtained |
+| `clusters: dict[str, str]` | HA cluster (a group name) → split policy |
+| `dhcp_off`, `mac_tables`, `counters`, `notes` | the rest |
+
+The model's core questions are answered by a few functions:
+
+- `usable(link)`: can this cable carry data? Not if it's down, a control
+  cable, either end is dead, STP is blocking either end, or a broadcast storm
+  has saturated it. Everything that forwards goes through this.
+- `segment(dev, port)`: the broadcast domain seen from one interface (every
+  other interface reachable through switches alone).
+- `l2path(src_iface, dst_iface)`: the frame path between two interfaces.
+- `route(src, dst_iface)`: a list of **legs**, each one layer-2 hop between
+  addressed interfaces: `(from_iface, to_iface, frame_path)`.
+- `ha_state(cluster)`: partitions, active sides, virtual-gateway owners, and
+  a health level.
+- `stp_update()`: recomputes blocked ports (union-find over the switch graph,
+  nearest-the-root first) and ends storms whose loop is gone.
+- `flood(iface)`: follows one broadcast, generation by generation. Copies are
+  counted per (cable, direction), so even an exponential storm is cheap. If
+  frames are still alive after `len(links) + 2` hops, it's a storm.
+- `reconcile()`: runs `stp_update()`, then brings addresses in line with the
+  cabling, and returns notes describing what changed. The app calls it after every change.
+- `auto_layout(width)`: positions every device.
+- `traversal(order, root)` / `renumber(order, root)`: BFS/DFS visit order,
+  and renaming every device to match (returns `{old: new}`).
+
+Code that holds on to a device across `changed()` should keep the
+`Device` object, not its id: auto-renumbering may rename it (see `cmd_link`).
+
+Device paths are lists of `(device_id, index_of_link_used_to_arrive)`, with
+`-1` for the first device.
+
+## The UI
+
+`ByteSimApp` combines the four command mixins with Textual's `App`. The flow
+for every command:
+
+1. `on_input_submitted` → `run_command(line)`. Any `NetError` becomes a red
+   console line.
+2. `dispatch(tokens)` pulls out `key=value` options and applies the shortcuts
+   (`r1` selects, `r1 s2` cables, a bare group name selects it). It then looks
+   the word up in the table built by `registry.collect()`.
+3. The handler changes the model, logs what happened, and calls
+   `self.changed()`.
+4. `changed()` runs `reconcile`, applies auto-renumbering if it's on, reports HA state changes, re-runs the layout
+   if auto-arrange is on, and redraws the canvas and inspector.
+
+`NetCanvas.render()` rebuilds the picture every frame, in layers: group
+frames, then cables, then group labels, then device boxes, then address
+labels, then packets. Each cable cell keeps a bitmask of the directions it
+connects in (N/E/S/W), so crossings and junctions get the right box-drawing
+character. A cell used only by control cables uses the double-line set; one
+used only by fabric cables uses the heavy set.
+
+Packets are lists of screen cells. A timer moves every packet forward one
+cell per tick and runs a callback when it arrives, which is how ping chains
+its reply. Multicast copies share cells until their paths split, so a single
+packet appears to fork.
+
+## Scripts and synthesis
+
+The command interpreter (`tui/commands/interpreter.py`) has no Textual
+dependency. The app and `scripting.ScriptRunner` both use it.
+
+- **`ScriptRunner`** is the real command mixins plus a stub canvas. It builds
+  structure and skips layout, re-addressing and animation, so replaying a
+  script is fast and uses exactly the app's command semantics.
+- **`synthesis.synthesize(net, mode)`**:
+  1. Renders an explicit plan: devices in id order, with placeholders for
+     gaps, then groups, interfaces, cables, settings and failures.
+  2. Lists reuse candidates. `clone` candidates are checked against the exact
+     mapping `clone` would make. `copy` and `ports copy` candidates compare
+     boundary patterns.
+  3. Tries the best savings first. Each candidate is kept only if the
+     re-rendered script replays into a network with no
+     `equivalence.differences()` and is shorter.
+- **The renderer** interleaves explicit `add`s and clones so every kind's ids
+  are created in increasing order, and finishes a clone's source (groups,
+  internal cables, settings) just before the clone.
+
+## Adding a command
+
+Add a method to the mixin that fits, or create a new mixin and add it to
+`ByteSimApp`'s bases:
+
+```python
+from .registry import command
+
+class TopologyCommands(CommandHost):
+    @command("rename", "mv")
+    def cmd_rename(self, args: list[str], opts: dict[str, str]) -> None:
+        if len(args) != 2:
+            raise NetError("usage: rename <id> <new-id>")
+        ...                       # change self.net
+        self.log_msg("renamed")
+        self.changed()
+```
+
+Raise `NetError` for anything the user got wrong; it's shown in the console.
+Put real behaviour in the model rather than the handler, so it can be tested
+without the UI. Add a line to `tui/help.py` and to `docs/guide.md`.
+
+## Tests
+
+```sh
+pytest
+```
+
+- `tests/test_topology.py`, `test_groups.py`, `test_addressing.py` and
+  `test_ha.py`, `test_naming.py`, `test_stp.py` and `test_cloning.py` exercise
+  the model directly, using the demo networks from
+  `conftest.py`.
+- `tests/test_app.py` drives the real app headlessly with Textual's
+  `run_test()` and waits for packet animations to finish.
+
+## Releasing
+
+1. Bump `__version__` in `src/bytesim/__init__.py` and add a `CHANGELOG.md`
+   entry.
+2. `python -m build` creates `dist/bytesim-X.Y.Z.tar.gz` and the wheel.
+3. `twine check dist/*`
+4. `twine upload --repository testpypi dist/*` to try it, then
+   `twine upload dist/*`.

bytesim-0.1.0/docs/file-format.md

@@ -0,0 +1,45 @@
+# Save file format
+
+This is the complete JSON snapshot written by `save`. For the hand-writable,
+template-based YAML format, see [topology-format.md](topology-format.md).
+
+`save` writes, and `load` reads, a single JSON object. All keys except
+`counters`, `devices` and `links` are optional, so older files still load.
+
+```json
+{
+  "counters": { "g": 1, "r": 2, "s": 3, "c": 10 },
+  "devices": [
+    { "kind": "r", "num": 1, "nports": 6, "x": 64, "y": 1, "up": true }
+  ],
+  "links": [
+    { "a": "r1", "pa": 5, "b": "r2", "pb": 5, "role": "control", "up": true }
+  ],
+  "groups":   { "dc1": ["fab1", "rfab1"], "rfab1": ["r1", "r2"], "fab1": ["s1", "s2"] },
+  "clusters": { "rfab1": "witness" },
+  "ifaces": {
+    "c1:1": { "mode": "dhcp", "net": 1, "host": 10, "gw": 254, "via": "dhcp" }
+  },
+  "dhcp_off": ["r2"],
+  "stp_off": ["s4", "s5"],
+  "stp_priority": { "s7": 4096 }
+}
+```
+
+| Key | Meaning |
+|---|---|
+| `counters` | the last number used for each kind, so ids are never reused |
+| `devices[]` | `kind` (`g`/`r`/`s`/`c`) and `num` make the id (`r1`). Also `nports`, canvas position `x`/`y`, and `up` (false = failed) |
+| `links[]` | two ends (`a`/`pa`, `b`/`pb`; ports start at 1), `role` (`data`, `control`, `control-backup`, `fabric`) and `up` |
+| `groups` | group → members, in order. A member is a device id or another group's name (groups nest) |
+| `clusters` | groups that are HA clusters → split policy (`none`, `quorum`, `witness`) |
+| `ifaces` | `"device:port"` → address config. `mode`: `dhcp`, `adhoc`, `static`, `auto` (routers) or `none`. `net`/`host`: the address. `gw`: the gateway's host number on the same network (254 = cluster virtual gateway). `via`: how the current address was obtained |
+| `dhcp_off` | routers and gateways whose DHCP server is switched off |
+| `stp_off` | switches with spanning tree switched off (every other switch runs it) |
+| `stp_priority` | switch → bridge priority (default 32768; lower wins the root election) |
+
+Blocked ports and storms aren't saved: blocked ports are recomputed when a file
+is loaded, and a storm only starts when traffic is sent.
+
+Entries that refer to missing devices or groups are dropped on load. An
+address in an older format is also dropped, and recomputed from the cabling.