bytesim 0.1.0__py3-none-any.whl

bytesim/topology.py

@@ -0,0 +1,517 @@
+"""The declarative topology format (``bytesim/topology-v1``): load and export.
+
+A topology file describes the *architecture*: devices, groups and cables,
+optionally built from reusable templates and link macros. It leaves out
+runtime state: positions (auto-arranged), addresses (re-learned), failures and
+storms. Ports are allocated in file order unless pinned (``r1:3``).
+
+    schema: bytesim/topology-v1
+    defaults: {links: data, stp: on, interfaces: {computer: dhcp}}
+    templates:
+      site:
+        devices:                     # roles
+          routers:  {kind: router, count: 2, ports: 8}
+          access:   {kind: switch, count: 2, ports: 5}
+        groups:                      # local names; a list = members, a mapping = subgroups
+          core: routers
+          office: {room1: ["access[0]"], room2: ["access[1]"]}
+        links:
+          - mesh: [routers, access]
+    instances:
+      site1:
+        template: site
+        group: site1                 # wrap the instance in a group (default: its own name)
+        devices: {routers: [r1, r2], access: [s1, s2]}   # optional: fixed ids
+        groups: {core: rfab1, office.room1: room1}       # optional: names by key or dotted path
+    devices: {s8: 5, s12: {ports: 5, stp: off}}           # stand-alone devices: id → ports | spec
+    groups: {link1: [s8, s12]}
+    links:
+      - parallel: [s8, s12, 2]
+      - {connect: ["r1:5", "r2:5"], role: control}
+
+Link macros: ``connect: [a, b]``, ``mesh: [A, B]`` (every pairing),
+``zip: [A, B]`` (pairwise), ``parallel: [a, b, n]``, ``chain: [a, b, c…]`` and
+``ring: [a, b, c…]``. A name can be a device id (optionally ``:port``), a role
+or ``role[i]`` inside a template, a group (all devices in it), or a list.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import yaml
+
+from .constants import ALIASES, AUTO, GROUP_NAME, KINDS, POLICIES, RANK, REF, ROLES
+from .model import NetError, Network
+from .model.types import Device, Iface
+
+SCHEMA = "bytesim/topology-v1"
+GROUP_KEYS = {"members", "cluster"}
+INDEXED = re.compile(r"^([A-Za-z_][\w-]*)\[(\d+)\](?::(?:p|nic|eth)?(\d+))?$")
+KIND_NAME = {name: k for k, (name, _, _) in KINDS.items()}
+
+
+def looks_like_topology(text: str) -> bool:
+    """True for a topology file (YAML, or JSON with a schema key), False for a save file."""
+    head = text.lstrip()[:400]
+    return "bytesim/topology" in head or (not head.startswith("{") and "counters" not in head)
+
+
+# ---------------------------------------------------------------------------- loading
+class _Builder:
+    def __init__(self, spec: dict) -> None:
+        self.spec = spec
+        self.net = Network()
+        d = spec.get("defaults") or {}
+        self.default_role = str(d.get("links", "data"))
+        self.default_stp = _onoff(d.get("stp", "on"), "defaults.stp")
+        self.default_ifaces = {_kind(k, "defaults.interfaces"): str(v)
+                               for k, v in (d.get("interfaces") or {}).items()}
+        if self.default_role not in ROLES:
+            raise NetError(f"defaults.links: role must be one of {', '.join(ROLES)}")
+
+    # ---- devices ---------------------------------------------------------
+    def _declare(self, did: str, kind: str, spec: Any, where: str) -> Device:
+        m = REF.match(did)
+        if not m or m[3]:
+            raise NetError(f"{where}: {did!r} isn't a device id like r1 or s12")
+        if m[1].lower() != kind:
+            raise NetError(f"{where}: {did} is named like a {KINDS[m[1].lower()][0]} but declared a {KINDS[kind][0]}")
+        did = did.lower()
+        if did in self.net.devices:
+            raise NetError(f"{where}: {did} is declared twice")
+        spec = {"ports": spec} if isinstance(spec, int) else dict(spec or {})
+        dev = Device(kind, int(m[2]), int(spec.get("ports", KINDS[kind][1])))
+        if not 1 <= dev.nports <= 64:
+            raise NetError(f"{where}: {did} ports must be 1..64")
+        self.net.devices[did] = dev
+        self.net.counters[kind] = max(self.net.counters[kind], dev.num)
+        self._settings(dev, spec, where)
+        return dev
+
+    def _auto(self, kind: str, spec: dict, where: str) -> Device:
+        """The lowest free number of this kind, skipping every id the file fixes."""
+        n = 1
+        while f"{kind}{n}" in self.net.devices or f"{kind}{n}" in self.reserved:
+            n += 1
+        return self._declare(f"{kind}{n}", kind, spec, where)
+
+    def _settings(self, dev: Device, spec: dict, where: str) -> None:
+        net = self.net
+        if dev.kind == "s" and not _onoff(spec.get("stp", self.default_stp), f"{where}.stp"):
+            net.stp_off.add(dev.id)
+        if "priority" in spec:
+            net.stp_priority[dev.id] = int(spec["priority"])
+        if dev.kind in "rg" and not _onoff(spec.get("dhcp", True), f"{where}.dhcp"):
+            net.dhcp_off.add(dev.id)
+        mode = spec.get("interfaces", self.default_ifaces.get(dev.kind))
+        if mode is not None:
+            if mode not in ("dhcp", "adhoc", "none", "auto"):
+                raise NetError(f"{where}.interfaces: use dhcp, adhoc, none or auto")
+            for p in range(1, dev.nports + 1):
+                net.ifaces[f"{dev.id}:{p}"] = Iface(mode)
+
+    # ---- names → devices ---------------------------------------------------
+    def _resolve(self, ref: Any, roles: dict[str, list[str]], where: str) -> list[tuple[str, int | None]]:
+        if isinstance(ref, list):
+            return [d for r in ref for d in self._resolve(r, roles, where)]
+        ref = str(ref)
+        if (m := INDEXED.match(ref)):
+            role, i, port = m[1], int(m[2]), m[3]
+            if role not in roles:
+                raise NetError(f"{where}: no role {role!r} here")
+            if i >= len(roles[role]):
+                raise NetError(f"{where}: {role} has {len(roles[role])} devices, so {ref} doesn't exist")
+            return [(roles[role][i], int(port) if port else None)]
+        if ref in roles:
+            return [(d, None) for d in roles[ref]]
+        if (m := REF.match(ref)):
+            did = f"{m[1].lower()}{int(m[2])}"
+            if did not in self.net.devices:
+                raise NetError(f"{where}: no device {did}")
+            return [(did, int(m[3]) if m[3] else None)]
+        if ref.lower() in self.net.groups:
+            return [(d, None) for d in self.net.devices_in(ref.lower())]
+        raise NetError(f"{where}: {ref!r} is not a device, role or group")
+
+    def _links(self, items: list, roles: dict[str, list[str]], where: str) -> None:
+        for n, item in enumerate(items or []):
+            here = f"{where}[{n}]"
+            if not isinstance(item, dict):
+                raise NetError(f"{here}: expected e.g. {{mesh: [a, b]}}")
+            role = str(item.get("role", self.default_role))
+            if role not in ROLES:
+                raise NetError(f"{here}: role must be one of {', '.join(ROLES)}")
+            ops = [k for k in item if k != "role"]
+            if len(ops) != 1:
+                raise NetError(f"{here}: one of connect, mesh, zip, parallel, chain, ring")
+            op, args = ops[0], item[ops[0]]
+            pairs: list[tuple[tuple[str, int | None], tuple[str, int | None]]] = []
+            if op in ("connect", "mesh", "zip"):
+                if not (isinstance(args, list) and len(args) == 2):
+                    raise NetError(f"{here}: {op} takes two names")
+                a, b = (self._resolve(x, roles, here) for x in args)
+                if op == "connect":
+                    if len(a) != 1 or len(b) != 1:
+                        raise NetError(f"{here}: connect joins single devices (use mesh or zip for sets)")
+                    pairs = [(a[0], b[0])]
+                elif op == "mesh":
+                    pairs = [(x, y) for x in a for y in b]
+                else:
+                    if len(a) != len(b):
+                        raise NetError(f"{here}: zip needs equal sizes ({len(a)} vs {len(b)})")
+                    pairs = list(zip(a, b))
+            elif op == "parallel":
+                if not (isinstance(args, list) and len(args) == 3 and isinstance(args[2], int)):
+                    raise NetError(f"{here}: parallel takes [a, b, count]")
+                a, b = (self._resolve(x, roles, here) for x in args[:2])
+                if len(a) != 1 or len(b) != 1:
+                    raise NetError(f"{here}: parallel joins two single devices")
+                pairs = [(a[0], b[0])] * args[2]
+            elif op in ("chain", "ring"):
+                seq = self._resolve(args, roles, here)
+                pairs = list(zip(seq, seq[1:])) + ([(seq[-1], seq[0])] if op == "ring" and len(seq) > 2 else [])
+            else:
+                raise NetError(f"{here}: unknown macro {op!r}")
+            for (da, pa), (db, pb) in pairs:
+                try:
+                    self.net.connect(da, pa, db, pb, role)
+                except NetError as e:
+                    raise NetError(f"{here}: {e}") from None
+
+    # ---- groups --------------------------------------------------------------
+    def _groups(self, tree: dict, roles: dict[str, list[str]], names: dict[str, str] | None,
+                path: str, where: str) -> list[str]:
+        """Create a group tree; returns the top-level group names in order.
+
+        ``names`` maps template paths to chosen names; unmapped template groups
+        take their key if it's free, else the next free variant (core → core-2).
+        Stand-alone groups (``names`` is None) are named exactly by their key."""
+        made = []
+        for key, val in (tree or {}).items():
+            local = f"{path}.{key}" if path else str(key)
+            key = str(key).lower()
+            claimed = frozenset(self.reserved_groups)
+            try:
+                if names is None:
+                    name = self.net.resolve_group_name(key, claimed)
+                elif local in names:
+                    name = self.net.resolve_group_name(names[local], claimed)
+                elif key not in self.net.groups and key not in self.net.devices and key not in claimed:
+                    name = key
+                else:                       # a template's own name, taken: use a free variant
+                    name = self.net.next_group_name(key, claimed)
+            except NetError as e:
+                raise NetError(f"{where}.{local}: {e}") from None
+            if not GROUP_NAME.match(name) or REF.match(name):
+                raise NetError(f"{where}.{local}: bad group name {name!r} (start with a letter, "
+                               f"at most 16 characters, not a device id)")
+            if name in self.net.groups:
+                raise NetError(f"{where}: group {name} is defined twice")
+            members: list[str] = []
+            subs: dict = {}
+            cluster = None
+            if isinstance(val, (str, list)):
+                members = [d for d, _ in self._resolve(val, roles, f"{where}.{local}")]
+            elif isinstance(val, dict):
+                members = [d for d, _ in self._resolve(val.get("members", []), roles, f"{where}.{local}")]
+                cluster = val.get("cluster")
+                subs = {k: v for k, v in val.items() if k not in GROUP_KEYS}
+            else:
+                raise NetError(f"{where}.{local}: a group is a list of members or a mapping of subgroups")
+            for d in members:                              # membership is a tree
+                if (owner := self.net.group_of(d)) is not None or members.count(d) > 1:
+                    raise NetError(f"{where}.{local}: {d} is already in group {owner or name}"
+                                   f" (a device belongs to one group)")
+            self.net.groups[name] = []                     # reserve before the children
+            children = self._groups(subs, roles, names, local, where)
+            self.net.groups[name] = children + members
+            if not self.net.groups[name]:
+                raise NetError(f"{where}.{local}: group {name} is empty")
+            if cluster is not None:
+                cluster = "none" if cluster is True else str(cluster)
+                if cluster not in POLICIES:
+                    raise NetError(f"{where}.{local}.cluster: one of {', '.join(POLICIES)} (or true)")
+                self.net.clusters[name] = cluster
+            made.append(name)
+        return made
+
+    @staticmethod
+    def _explicit_group_names(spec: dict, instances: dict) -> set[str]:
+        """Group names fixed in the file: instance names for template groups, wrapper
+        groups, and every stand-alone group (nested ones included)."""
+        out: set[str] = set()
+
+        def fixed(name: Any) -> None:
+            if name and not AUTO.match(str(name)):
+                out.add(str(name).lower())
+
+        for iname, inst in instances.items():
+            inst = inst or {}
+            fixed(inst.get("group", iname))
+            for new in (inst.get("groups") or {}).values():
+                fixed(new)
+
+        def walk(tree: Any) -> None:
+            for key, val in (tree or {}).items():
+                fixed(key)
+                if isinstance(val, dict):
+                    walk({k: v for k, v in val.items() if k not in GROUP_KEYS})
+
+        walk(spec.get("groups"))
+        return out
+
+    @staticmethod
+    def _expand_ids(ids: Any, kind: str, where: str) -> list[str | None] | None:
+        """Fixed ids, with auto-number patterns (s(2)) expanded to placeholders."""
+        if ids is None:
+            return None
+        if not isinstance(ids, list):
+            raise NetError(f"{where}: a list of ids, e.g. [{kind}1, {kind}2] or [{kind}(2)]")
+        out: list[str | None] = []
+        for d in ids:
+            m = AUTO.match(str(d))
+            if not m:
+                out.append(str(d))
+                continue
+            if m[1].lower() != kind:
+                raise NetError(f"{where}: this role holds {KINDS[kind][0]}s, so write {kind}({m[2]}), not {d}")
+            out += [None] * int(m[2])
+        return out
+
+    @staticmethod
+    def _group_paths(tree: dict, path: str = "") -> list[str]:
+        out = []
+        for key, val in (tree or {}).items():
+            local = f"{path}.{key}" if path else str(key)
+            out.append(local)
+            if isinstance(val, dict):
+                out += _Builder._group_paths({k: v for k, v in val.items() if k not in GROUP_KEYS}, local)
+        return out
+
+    # ---- the whole file ------------------------------------------------------
+    def build(self) -> Network:
+        spec, net = self.spec, self.net
+        schema = spec.get("schema", SCHEMA)
+        if not str(schema).startswith("bytesim/topology"):
+            raise NetError(f"schema {schema!r} isn't a ByteSim topology")
+        templates = spec.get("templates") or {}
+        instances = spec.get("instances") or {}
+        if "sites" in spec:
+            raise NetError("use `instances:` for template instances (see docs/topology-format.md)")
+
+        # Pass 1: every name the file fixes explicitly is reserved before anything is
+        # allocated, so auto-numbering (s(2), fab(1)) never depends on what comes later.
+        self.reserved = {str(d).lower() for d in (spec.get("devices") or {})}
+        self.reserved_groups = self._explicit_group_names(spec, instances)
+        for inst in instances.values():
+            for ids in ((inst or {}).get("devices") or {}).values():
+                self.reserved |= {str(d).lower() for d in ids if not AUTO.match(str(d))}
+
+        for did, dspec in (spec.get("devices") or {}).items():
+            m = REF.match(str(did))
+            if not m:
+                raise NetError(f"devices: {did!r} isn't a device id like r1 or s12")
+            self._declare(str(did), m[1].lower(), dspec, f"devices.{did}")
+
+        built: list[tuple[str, dict, dict, dict[str, list[str]]]] = []
+        for iname, inst in instances.items():
+            where = f"instances.{iname}"
+            inst = inst or {}
+            tname = inst.get("template")
+            if tname not in templates:
+                raise NetError(f"{where}: unknown template {tname!r}")
+            tmpl = templates[tname] or {}
+            fixed = inst.get("devices") or {}
+            roles: dict[str, list[str]] = {}
+            for role, rspec in (tmpl.get("devices") or {}).items():
+                rspec = dict(rspec or {})
+                kind = _kind(rspec.get("kind"), f"templates.{tname}.devices.{role}.kind")
+                count = int(rspec.get("count", 1))
+                here = f"{where}.devices.{role}"
+                ids = self._expand_ids(fixed.get(role), kind, here)
+                if ids is not None and len(ids) != count:
+                    raise NetError(f"{here}: the template has {count}, you gave {len(ids)}")
+                roles[role] = [self._declare(d, kind, rspec, here).id if d else self._auto(kind, rspec, here).id
+                               for d in (ids or [None] * count)]
+            unknown = set(fixed) - set(roles)
+            if unknown:
+                raise NetError(f"{where}.devices: the template has no role {sorted(unknown)[0]!r}")
+            built.append((iname, tmpl, inst, roles))
+
+        # Groups: instances first (each optionally wrapped), then stand-alone ones.
+        for iname, tmpl, inst, roles in built:
+            where = f"instances.{iname}"
+            paths = self._group_paths(tmpl.get("groups") or {})
+            names = {}
+            for key, new in (inst.get("groups") or {}).items():
+                hits = [p for p in paths if p == key or p.split(".")[-1] == key]
+                if len(hits) != 1:
+                    raise NetError(f"{where}.groups: {key!r} " + ("matches no group in the template" if not hits
+                                   else f"is ambiguous, say which: {', '.join(hits)}"))
+                names[hits[0]] = str(new).lower()
+            tops = self._groups(tmpl.get("groups") or {}, roles, names, "", where)
+            wrap = inst.get("group", iname)
+            if wrap:
+                try:
+                    wrap = net.resolve_group_name(str(wrap), frozenset(self.reserved_groups))
+                except NetError as e:
+                    raise NetError(f"{where}.group: {e}") from None
+                loose = [d for ids in roles.values() for d in ids if net.group_of(d) is None]
+                net.group_add(wrap, tops + loose)
+        self._groups(spec.get("groups") or {}, {}, None, "", "groups")
+
+        # Cables, in file order: every instance's template links, then the stand-alone ones.
+        for iname, tmpl, inst, roles in built:
+            self._links(tmpl.get("links"), roles, f"instances.{iname}.links")
+        self._links(spec.get("links"), {}, "links")
+        return net
+
+
+def load_topology(text: str) -> Network:
+    """Build a Network from topology YAML (or JSON). Raises NetError with the place it broke."""
+    try:
+        spec = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        raise NetError(f"not valid YAML: {e}") from None
+    if not isinstance(spec, dict):
+        raise NetError("a topology file is a mapping (schema, devices, groups, links…)")
+    return _Builder(spec).build()
+
+
+def _kind(word: Any, where: str) -> str:
+    w = str(word).lower()
+    if w in KIND_NAME:
+        return KIND_NAME[w]
+    if w in ALIASES:
+        return ALIASES[w]
+    raise NetError(f"{where}: kind must be gateway, router, switch or computer")
+
+
+def _onoff(v: Any, where: str) -> bool:
+    if isinstance(v, bool):
+        return v
+    if str(v).lower() in ("on", "enabled", "yes", "true"):
+        return True
+    if str(v).lower() in ("off", "disabled", "no", "false"):
+        return False
+    raise NetError(f"{where}: use on or off")
+
+
+# ---------------------------------------------------------------------------- export
+def dump_topology(net: Network, pin_ports: bool = False) -> str:
+    """Write a network as a topology file (no templates: those can't be inferred).
+
+    Compact by default: meshes between groups and parallel cables are folded
+    into macros, and ports are left to be allocated on load. ``pin_ports``
+    writes every cable as an explicit ``connect`` with its ports, so loading it
+    rebuilds identical cabling (and so identical MACs on each end)."""
+    out = [f"schema: {SCHEMA}",
+           "# Exported by ByteSim. Positions, addresses, failures and storms are not included.",
+           ""]
+    stp_default = len(net.stp_off) <= sum(1 for d in net.devices.values() if d.kind == "s") / 2
+    out.append(f"defaults: {{links: data, stp: {'on' if stp_default else 'off'}}}")
+    out.append("")
+
+    out.append("devices:")
+    for kind in KINDS:
+        devs = [d for d in net.sorted_devices() if d.kind == kind]
+        if not devs:
+            continue
+        name = KINDS[kind][0]
+        out.append(f"  # {name}{'es' if name.endswith('h') else 's'}")
+        for d in devs:
+            extra = {}
+            if d.kind == "s" and (d.id in net.stp_off) == stp_default:
+                extra["stp"] = "off" if d.id in net.stp_off else "on"
+            if d.id in net.stp_priority:
+                extra["priority"] = net.stp_priority[d.id]
+            if d.id in net.dhcp_off:
+                extra["dhcp"] = "off"
+            modes = {i.mode for p in range(1, d.nports + 1) if (i := net.ifaces.get(f"{d.id}:{p}"))}
+            if d.kind == "c" and modes and modes != {"dhcp"} and len(modes) == 1 and "static" not in modes:
+                extra["interfaces"] = modes.pop()
+            if extra:
+                inner = ", ".join([f"ports: {d.nports}"] + [f"{k}: {v}" for k, v in extra.items()])
+                out.append(f"  {d.id}: {{{inner}}}")
+            else:
+                out.append(f"  {d.id}: {d.nports}")
+
+    if net.groups:
+        out += ["", "groups:"]
+        for g in net.groups:
+            if net.parent_of(g) is None:
+                out += _dump_group(net, g, 1)
+
+    out += ["", "links:"]
+    out += _dump_links(net, pin_ports)
+    return "\n".join(out) + "\n"
+
+
+def _dump_group(net: Network, g: str, depth: int) -> list[str]:
+    pad = "  " * depth
+    subs = net.subgroups(g)
+    devs = [m for m in net.groups[g] if m in net.devices]
+    cluster = net.clusters.get(g)
+    if not subs and cluster is None:
+        return [f"{pad}{g}: [{', '.join(devs)}]"]
+    lines = [f"{pad}{g}:"]
+    if cluster is not None:
+        lines.append(f"{pad}  cluster: {cluster}")
+    if devs:
+        lines.append(f"{pad}  members: [{', '.join(devs)}]")
+    for sub in subs:
+        lines += _dump_group(net, sub, depth + 1)
+    return lines
+
+
+def _dump_links(net: Network, pin_ports: bool) -> list[str]:
+    def end(d: str, p: int) -> str:
+        return f"{d}:{p}" if pin_ports else d
+
+    lines: list[str] = []
+    if pin_ports:
+        for l in net.links:
+            role = f", role: {l.role}" if l.role != "data" else ""
+            lines.append(f'  - {{connect: [{end(l.a, l.pa)}, {end(l.b, l.pb)}]{role}}}')
+        return lines
+
+    # Cables as a multiset of unordered device pairs, per role.
+    remaining = [(min(l.a, l.b, key=_order), max(l.a, l.b, key=_order), l.role) for l in net.links]
+    data_pairs: dict[tuple[str, str], int] = {}
+    for a, b, role in remaining:
+        if role == "data":
+            data_pairs[(a, b)] = data_pairs.get((a, b), 0) + 1
+
+    def take(a: str, b: str) -> None:
+        key = (min(a, b, key=_order), max(a, b, key=_order))
+        data_pairs[key] -= 1
+        if not data_pairs[key]:
+            del data_pairs[key]
+
+    def has(a: str, b: str) -> bool:
+        return data_pairs.get((min(a, b, key=_order), max(a, b, key=_order)), 0) > 0
+
+    # Meshes between groups' direct devices (largest first), then parallels, then singles.
+    sets = sorted(((g, [m for m in net.groups[g] if m in net.devices]) for g in net.groups),
+                  key=lambda t: -len(t[1]))
+    sets = [(g, ds) for g, ds in sets if len(ds) >= 1 and not net.subgroups(g)]
+    for i, (ga, a) in enumerate(sets):
+        for gb, b in sets[i + 1:]:
+            if set(a) & set(b) or len(a) * len(b) < 2:
+                continue
+            if all(has(x, y) for x in a for y in b):
+                for x in a:
+                    for y in b:
+                        take(x, y)
+                lines.append(f"  - mesh: [{ga}, {gb}]")
+    for (a, b), n in sorted(data_pairs.items(), key=lambda kv: (_order(kv[0][0]), _order(kv[0][1]))):
+        lines.append(f"  - parallel: [{a}, {b}, {n}]" if n > 1 else f"  - connect: [{a}, {b}]")
+    for a, b, role in remaining:
+        if role != "data":
+            lines.append(f"  - {{connect: [{a}, {b}], role: {role}}}")
+    return lines
+
+
+def _order(did: str) -> tuple[int, int]:
+    return RANK[did[0]], int(did[1:])

bytesim/tui/__init__.py

@@ -0,0 +1,4 @@
+"""The Textual user interface."""
+from .app import ByteSimApp
+
+__all__ = ["ByteSimApp"]

bytesim/tui/app.py

@@ -0,0 +1,161 @@
+"""The ByteSim Textual app: layout, the command line, and keeping everything in sync."""
+from __future__ import annotations
+
+from rich.markup import escape
+from textual import events
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, VerticalScroll
+from textual.widgets import Footer, Input, RichLog, Static
+
+from .. import __version__
+from ..model import NetError, Network
+from .canvas import NetCanvas
+from .command_input import CommandInput
+from .commands.addressing import AddressCommands
+from .commands.groups import GroupCommands
+from .commands.history import HistoryCommands
+from .commands.interpreter import Interpreter
+from .commands.naming import NamingCommands
+from .commands.scripting import ScriptCommands
+from .commands.switching import SwitchingCommands
+from .commands.registry import collect
+from .commands.topology import TopologyCommands
+from .commands.traffic import TrafficCommands
+from .inspector import render_inspector
+
+
+class ByteSimApp(TopologyCommands, GroupCommands, AddressCommands, TrafficCommands, NamingCommands,
+                 SwitchingCommands, ScriptCommands, HistoryCommands, Interpreter, App):
+    """Canvas on the left, inspector on the right, console and command line below."""
+
+    TITLE = "ByteSim"
+    CSS = """
+    #main { height: 1fr; }
+    NetCanvas { width: 1fr; height: 1fr; border: round $panel-lighten-2; }
+    NetCanvas:focus { border: round $accent; }
+    #side { width: 38; border: round $panel-lighten-2; padding: 0 1; }
+    #log { height: 9; border: round $panel-lighten-2; padding: 0 1; }
+    #cmd { border: tall $panel-lighten-2; }
+    #cmd:focus { border: tall $accent; }
+    """
+    BINDINGS = [Binding("ctrl+q", "quit", "Quit")]
+    AUTO_FOCUS = "#cmd"
+
+    def __init__(self, network: Network | None = None, startup: list[str] | None = None,
+                 auto: bool | None = None) -> None:
+        """``network`` starts the app on an existing model; ``startup`` commands run once mounted.
+        ``auto`` turns auto-arrange on or off (default: on, unless a network with its own
+        positions is given)."""
+        super().__init__()
+        self.net = network or Network()
+        self.auto = (network is None) if auto is None else auto
+        self.graph = False              # graph-only mode: connectivity without addressing
+        self._startup = startup or []
+        self._ha_seen: dict = {}
+        self._commands = collect(type(self))
+
+    def compose(self) -> ComposeResult:
+        with Horizontal(id="main"):
+            yield NetCanvas(id="canvas")
+            with VerticalScroll(id="side"):
+                yield Static(id="info")
+        yield RichLog(id="log", markup=True, wrap=True)
+        yield CommandInput(id="cmd", placeholder="r1 s2 to cable · add r 8 · ping c1 c4 · help")
+        yield Footer()
+
+    @property
+    def canvas(self) -> NetCanvas:
+        return self.query_one(NetCanvas)
+
+    def on_mount(self) -> None:
+        self.query_one("#canvas").border_title = "network"
+        self.query_one("#side").border_title = "inspector"
+        self.query_one("#log").border_title = "console"
+        self.log_msg(f"[b]ByteSim {__version__}[/] — type [cyan]help[/] for commands, "
+                     "or [cyan]demo[/] / [cyan]demo ha[/] for a sample network.")
+        if self.net.devices:
+            self.call_after_refresh(self.changed)
+        for line in self._startup:
+            self.call_after_refresh(self.run_command, line)
+        self.refresh_sidebar()
+
+    # ---- shared helpers (used by the canvas and the command mixins) ----
+    def log_msg(self, msg: str) -> None:
+        if self.replaying:                   # a script is running: keep the console quiet
+            return
+        self.query_one(RichLog).write(msg)
+
+    def action_focus_cmd(self) -> None:
+        self.query_one(CommandInput).focus()
+
+    def action_focus_canvas(self) -> None:
+        self.canvas.focus()
+
+    def arrange(self, announce: bool = False) -> None:
+        self.auto = True
+        self.net.auto_layout(self.canvas.size.width or 120)
+        self.canvas.pan = (0, 0)
+        if announce:
+            self.log_msg("[green]auto-arrange on[/]")
+        self.changed()
+
+    def manual_moved(self) -> None:
+        if self.auto:
+            self.auto = False
+            self.log_msg("[dim]auto-arrange paused — press [b]a[/b] or type [b]auto[/b] to re-arrange[/]")
+
+    def replace_network(self, net: Network, auto: bool) -> None:
+        """Swap in a whole new network (clear, demo, load)."""
+        self.net = net
+        self.auto = auto
+        self._ha_seen = {}
+        self.canvas.reset()
+        self.changed()
+
+    def changed(self, skip: frozenset[tuple[str, int]] = frozenset()) -> None:
+        """Call after any structural change: re-address, renumber, report HA, re-layout, redraw."""
+        if self.replaying:                   # a script is running: do it all once at the end
+            return
+        self.reconcile(skip)
+        self.auto_renumber()
+        if not self.graph:
+            self._ha_report()
+        if self.auto:
+            self.net.auto_layout(self.canvas.size.width or 120)
+        c = self.canvas
+        if c.selected not in self.net.devices:
+            c.selected = None
+        if c.selected_group not in self.net.groups:
+            c.selected_group = None
+        c.hot_links.clear()
+        c.refresh()
+        self.refresh_sidebar()
+
+    def on_resize(self, event: events.Resize) -> None:
+        if self.auto:
+            self.call_after_refresh(self.changed)
+
+    def refresh_sidebar(self) -> None:
+        c = self.canvas
+        self.query_one("#info", Static).update(
+            render_inspector(self.net, c.selected, c.selected_group, self.graph, self.auto,
+                             self.naming_text()))
+
+    # ---- the command line ----------------------------------------------
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        line = event.value.strip()
+        inp = self.query_one(CommandInput)
+        inp.remember(line)
+        inp.value = ""
+        if line:
+            self.log_msg(f"[dim]›[/] {escape(line)}")
+            self.run_command(line)
+
+    def run_command(self, line: str) -> None:
+        """Run one command line, reporting errors in the console. Anything it changes
+        (even partly, before an error) becomes one undo step."""
+        try:
+            self.recorded(line, lambda: self.dispatch(self.tokens(line)))
+        except NetError as e:
+            self.log_msg(f"[red]✗ {escape(str(e))}[/]")