gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/ui/trap_lab.py

@@ -0,0 +1,270 @@
+"""Trap Lab — live trap-taxonomy histogram + a running feed of individual traps.
+
+Reads gini_trapdump over the serial (the agent's /traps, no gdb halt): per-kind counters drive a
+histogram of traps in the last 60s (syscall / page-fault / timer / device / illegal / other), and
+a ring drives a live feed (pid · kind · epc · faulting-address). The lesson students take away is
+that a system call, a timer preemption, and a demand-paged page are the SAME mechanism with
+different causes. "Step a trap ▸" opens the CPU journey to dissect one frame by frame.
+
+Same shape as the Syscall Lab: an injected `traps_source` (the bridge's /traps live, or
+DemoScheduler.traps() offline) polled off the GUI thread, so the whole face is testable against a
+fake feed.
+"""
+from __future__ import annotations
+
+from PySide6.QtCore import Qt, QTimer, Signal
+from PySide6.QtGui import QColor, QPainter
+from PySide6.QtWidgets import (
+    QComboBox, QDialog, QFrame, QHBoxLayout, QLabel, QPlainTextEdit, QPushButton, QVBoxLayout,
+    QWidget,
+)
+
+from ..domain.xv6 import (
+    TRAP_KINDS, TrapRate, parse_alarms, parse_trapcounts, parse_traptrace, trap_kind_name,
+)
+from .theme import ThemeManager, icons
+
+# trap kinds the "Step a trap" catcher can target (conditioned gdb breakpoint); "any" = next trap
+_CATCH_KINDS = ["any", "pagefault", "syscall", "timer", "illegal", "device"]
+
+# one colour per trap kind, so the histogram reads at a glance
+_KIND_ACCENT = {0: "blue", 1: "purple", 2: "amber", 3: "cyan", 4: "red", 5: "slate"}
+
+
+class TrapBars(QWidget):
+    """Horizontal bars for the six trap kinds, one colour per kind."""
+
+    def __init__(self, theme) -> None:
+        super().__init__()
+        self.theme = theme
+        self._rows: list = []          # [(kind_index, label, value)]
+        self.setMinimumHeight(180)
+
+    def set_data(self, rows) -> None:
+        self._rows = list(rows)
+        self.update()
+
+    def paintEvent(self, _e) -> None:
+        p = QPainter(self)
+        t = self.theme.theme
+        p.fillRect(self.rect(), QColor(t.panel))
+        if not self._rows or not any(v for _k, _l, v in self._rows):
+            p.setPen(QColor(t.muted))
+            p.drawText(self.rect(), Qt.AlignCenter, "no traps yet — run the machine (or use Demo)")
+            return
+        peak = max((v for _k, _l, v in self._rows), default=1) or 1
+        rowh = min(26, max(18, (self.height() - 8) // max(len(self._rows), 1)))
+        label_w, count_w = 96, 56
+        bar_max = max(40, self.width() - label_w - count_w - 12)
+        y = 4
+        for kind, label, v in self._rows:
+            p.setPen(QColor(t.text))
+            p.drawText(4, y, label_w - 6, rowh, Qt.AlignVCenter | Qt.AlignLeft, label)
+            w = int(bar_max * (v / peak))
+            p.fillRect(label_w, y + 3, max(w, 1), rowh - 8,
+                       QColor(t.accent_for(_KIND_ACCENT.get(kind, "blue"))))
+            p.setPen(QColor(t.muted))
+            p.drawText(label_w + bar_max + 6, y, count_w, rowh,
+                       Qt.AlignVCenter | Qt.AlignLeft, str(v))
+            y += rowh
+
+
+class TrapLab(QDialog):
+    traps_ready = Signal(str)          # raw /traps text pushed from the poll worker
+    alarms_ready = Signal(str)         # raw gini_dump text (ALARM lines) from the poll worker
+    caught = Signal(object)            # a TrapFrame from a live catch (or None), off the worker
+
+    def __init__(self, parent, theme: ThemeManager, device=None, traps_source=None,
+                 on_step=None, catch_source=None, alarm_source=None, on_play=None) -> None:
+        super().__init__(parent)
+        self.theme = theme
+        self.device = device
+        self._src = traps_source or (lambda: "")
+        self._on_step = on_step
+        self._on_play = on_play             # callable() opening the decode-the-trap game; may be None
+        self._catch = catch_source          # callable(kind) -> TrapFrame (live gdb freeze); may be None
+        self._alarm_src = alarm_source      # callable() -> gini_dump text with ALARM lines; may be None
+        self._rate = TrapRate(window=60.0)
+        self._busy = False
+        self._closed = False
+
+        t = theme.theme
+        self.setWindowTitle(f"Traps & Interrupts Lab — {getattr(device, 'name', 'xv6')}")
+        self.resize(760, 580)
+        self.setStyleSheet(f"QDialog{{background:{t.bg};}}")
+        root = QVBoxLayout(self)
+
+        hdr = QHBoxLayout()
+        ic = QLabel(); ic.setPixmap(icons.render_pixmap("dashboard", t.accent_for("amber"), 22))
+        title = QLabel(f"  Traps & Interrupts Lab — {getattr(device, 'name', 'xv6')}")
+        title.setStyleSheet(f"color:{t.text};font-size:16px;font-weight:600;")
+        hdr.addWidget(ic); hdr.addWidget(title); hdr.addStretch(1)
+        root.addLayout(hdr)
+
+        head = QLabel("Every trap the CPU takes, classified by cause. A system call, a timer "
+                      "preemption, and a demand-paged page are the same mechanism — watch the mix "
+                      "as programs run. No gdb; live over serial.")
+        head.setWordWrap(True); head.setStyleSheet(f"color:{t.muted};font-size:12px;")
+        root.addWidget(head)
+
+        self._bars = TrapBars(theme)
+        root.addWidget(self._panel("Traps · by cause, last 60s", self._bars), 1)
+
+        self._feed = QPlainTextEdit(); self._feed.setReadOnly(True)
+        self._feed.setStyleSheet(
+            f"QPlainTextEdit{{background:{t.panel};color:{t.text};border:1px solid {t.line};"
+            "border-radius:6px;font-family:monospace;font-size:12px;}")
+        root.addWidget(self._panel("Feed · recent traps  (pid  kind  epc  addr)", self._feed), 1)
+
+        # the sigalarm-lab strip — only shown when an alarm source is wired (Phase 3). It's the
+        # live proof a student's periodic handler works: the countdown ticks, `on` flips on fire.
+        self._alarms = QLabel()
+        self._alarms.setWordWrap(True)
+        self._alarms.setStyleSheet(
+            f"color:{t.text};background:{t.panel2};border:1px solid {t.line};border-radius:8px;"
+            "padding:6px 10px;font-family:monospace;font-size:12px;")
+        self._alarms.setVisible(self._alarm_src is not None)
+        root.addWidget(self._alarms)
+
+        row = QHBoxLayout()
+        if self._on_play is not None:                 # in-lab game: decode the trap from its scause
+            play = QPushButton("  Play: decode the trap")
+            play.setStyleSheet(
+                f"QPushButton{{color:{t.accent_for('purple')};background:{t.panel2};"
+                f"border:1px solid {t.line};border-radius:8px;padding:6px 12px;}}"
+                f"QPushButton:hover{{border-color:{t.accent};}}")
+            play.clicked.connect(lambda: self._on_play())
+            row.addWidget(play)
+        row.addStretch(1)
+        self._kind = QComboBox(); self._kind.addItems(_CATCH_KINDS)
+        self._kind.setToolTip("Which kind of trap to freeze")
+        self._kind.setStyleSheet(
+            f"QComboBox{{color:{t.text};background:{t.panel2};border:1px solid {t.line};"
+            "border-radius:6px;padding:4px 8px;}")
+        catch_lbl = QLabel("catch:"); catch_lbl.setStyleSheet(f"color:{t.muted};font-size:12px;")
+        row.addWidget(catch_lbl)
+        row.addWidget(self._kind)
+        self._step_btn = QPushButton("  Step a trap ▸")
+        self._step_btn.setToolTip("Freeze a real trap of this kind and dissect it in the CPU journey")
+        self._step_btn.setStyleSheet(
+            f"QPushButton{{color:{t.text};background:{t.panel2};border:1px solid {t.line};"
+            f"border-radius:8px;padding:6px 12px;}}QPushButton:hover{{border-color:{t.accent};}}")
+        self._step_btn.clicked.connect(self._step)
+        row.addWidget(self._step_btn)
+        root.addLayout(row)
+
+        self.traps_ready.connect(self._apply)
+        self.alarms_ready.connect(self._apply_alarms)
+        self.caught.connect(self._on_caught)
+        self._poll = QTimer(self); self._poll.timeout.connect(self._fetch)
+        self._poll.start(1500)
+        self._fetch()
+
+    def _panel(self, title, inner) -> QFrame:
+        t = self.theme.theme
+        f = QFrame(); f.setStyleSheet(
+            f"QFrame{{background:{t.panel2};border:1px solid {t.line};border-radius:10px;}}")
+        v = QVBoxLayout(f); v.setContentsMargins(10, 8, 10, 10)
+        h = QLabel(title); h.setStyleSheet(
+            f"color:{t.muted};font-size:11px;font-weight:600;border:none;")
+        v.addWidget(h)
+        inner.setStyleSheet((inner.styleSheet() or "") + "border:none;")
+        v.addWidget(inner, 1)
+        return f
+
+    def _step(self) -> None:
+        """Freeze a live trap (off the GUI thread — the gdb catch can take up to a few seconds),
+        then open the journey seeded with it. With no live catch source, open the authored
+        journey immediately."""
+        if not callable(self._on_step):
+            return
+        if callable(self._catch):
+            kind = self._kind.currentText()
+            self._step_btn.setEnabled(False)
+            self._step_btn.setText("  freezing a trap…")
+            import threading
+
+            def work():
+                try:
+                    fr = self._catch(kind)
+                except Exception:
+                    fr = None
+                if not self._closed:
+                    self.caught.emit(fr)
+            threading.Thread(target=work, daemon=True).start()
+        else:
+            self._on_step(None)
+
+    def _on_caught(self, frame) -> None:
+        self._step_btn.setEnabled(True)
+        self._step_btn.setText("  Step a trap ▸")
+        if not self._closed and callable(self._on_step):
+            self._on_step(frame)
+
+    def _fetch(self) -> None:
+        if self._busy or self._closed:
+            return
+        self._busy = True
+        import threading
+
+        def work():
+            try:
+                txt = self._src()
+            except Exception:
+                txt = ""
+            atxt = ""
+            if callable(self._alarm_src):
+                try:
+                    atxt = self._alarm_src() or ""
+                except Exception:
+                    atxt = ""
+            if not self._closed:                # don't signal a dialog that's being torn down
+                self.traps_ready.emit(txt or "")
+                if callable(self._alarm_src):
+                    self.alarms_ready.emit(atxt)
+        threading.Thread(target=work, daemon=True).start()
+
+    def _apply_alarms(self, txt) -> None:
+        if self._closed:
+            return
+        alarms = parse_alarms(txt)
+        if not alarms:
+            self._alarms.setText("⏰ no alarm set — a process calls sigalarm(interval, handler) to "
+                                 "run a periodic user-level handler (the sigalarm lab).")
+            return
+        lines = []
+        for pid in sorted(alarms):
+            a = alarms[pid]
+            state = " · handler RUNNING" if a.on else ""
+            lines.append(f"⏰ pid {pid} · every {a.interval} ticks · fires in {a.remaining} · "
+                         f"handler {a.handler}{state}")
+        self._alarms.setText("\n".join(lines))
+
+    def _apply(self, txt) -> None:
+        self._busy = False
+        if self._closed:
+            return
+        import time
+        counts = parse_trapcounts(txt)
+        if counts:
+            self._rate.add(time.monotonic(), counts)
+        rates = self._rate.rates()
+        # all six kinds, biggest first, so the mix is always fully visible (zeros included)
+        rows = sorted(((k, trap_kind_name(k), rates.get(k, 0)) for k in TRAP_KINDS),
+                      key=lambda r: -r[2])
+        self._bars.set_data(rows)
+        evs = parse_traptrace(txt)
+        if evs:
+            lines = [f"{e.pid:>3}  {trap_kind_name(e.kind):<9} {e.epc}"
+                     + (f"  {e.tval}" if e.tval not in ("0x0", "0x0000000000000000") else "")
+                     for e in evs]
+            sb = self._feed.verticalScrollBar()
+            at_bottom = sb.value() >= sb.maximum() - 4
+            self._feed.setPlainText("\n".join(lines))
+            if at_bottom:
+                sb.setValue(sb.maximum())
+
+    def closeEvent(self, e) -> None:  # noqa: N802
+        self._closed = True
+        self._poll.stop()
+        super().closeEvent(e)

gini/ui/worker_host.py

@@ -0,0 +1,102 @@
+"""Running slow hardware work off the GUI thread, safely.
+
+Extracted from board_dialog so that every hardware dialog shares ONE copy. The rules
+below are not stylistic — each one is a bug that aborted the whole process when it was
+found by running the setup dialog headless, and re-deriving them per dialog is how they
+come back:
+
+1. **Hold a Python reference to the worker AND the thread.** PySide does not keep a
+   worker alive merely because a signal is connected to it, so a worker passed in as a
+   temporary is collected the moment the call returns; the thread then sits in its event
+   loop forever and nothing is ever emitted.
+2. **Connect only to BOUND METHODS of the dialog, never to a closure.** A closure has no
+   thread affinity, so Qt chooses a direct connection and the "off-thread" handler runs
+   ON the worker thread, touching widgets from outside the GUI thread.
+3. **Never parent the QThread to the dialog.** Serial work is slow — a board reboots when
+   its port is opened — so the dialog can easily be closed mid-run; destroying a running
+   QThread makes Qt abort. Unparented, the module registry holds it until it finishes.
+
+A host must provide `_alive: bool` and a `_worker_failed(str)` slot.
+"""
+from __future__ import annotations
+
+import warnings
+
+from PySide6.QtCore import QObject, QThread
+
+# Workers and their threads outlive the dialog that started them, so they need an owner
+# that is not the dialog. Entries retire themselves when the thread ends.
+_LIVE_THREADS: set = set()          # {(QThread, worker)}
+
+
+def drain(timeout_ms: int = 3000) -> int:
+    """Stop and reap every live worker thread. Returns how many were still running.
+
+    `_detach` makes a running worker harmless to the DIALOG, but the thread itself is
+    still owned by the registry and is only retired when its `finished` signal is
+    delivered — which needs an event loop to be turning. At application shutdown (or at
+    the end of a test run) there may be none left, and Python then garbage-collects a
+    QThread that is still running, which is precisely the "Destroyed while thread is
+    still running" abort that this module exists to prevent. So ask them to stop, and
+    wait.
+    """
+    stragglers = 0
+    for thread, _worker in list(_LIVE_THREADS):
+        try:
+            if thread.isRunning():
+                stragglers += 1
+                thread.quit()
+                thread.wait(timeout_ms)
+        except RuntimeError:
+            pass                      # already deleted by Qt; nothing to reap
+        _LIVE_THREADS.discard((thread, _worker))
+    return stragglers
+
+
+class WorkerHost:
+    """Mixin: `self._run(worker, on_done)` and `self._detach()`."""
+
+    def _run(self, worker: QObject, on_done) -> None:
+        thread = QThread()
+        worker.moveToThread(thread)
+        thread.started.connect(worker.run)
+        entry = (thread, worker)                 # rule 1
+        _LIVE_THREADS.add(entry)
+        self._worker = worker
+
+        worker.done.connect(on_done)             # rule 2: a bound method of the dialog
+        worker.done.connect(thread.quit)
+        self._connections = [(worker.done, on_done)]
+        if hasattr(worker, "failed"):
+            worker.failed.connect(self._worker_failed)
+            worker.failed.connect(thread.quit)
+            self._connections.append((worker.failed, self._worker_failed))
+        if hasattr(worker, "progress") and hasattr(self, "_worker_progress"):
+            worker.progress.connect(self._worker_progress)
+            self._connections.append((worker.progress, self._worker_progress))
+        thread.finished.connect(worker.deleteLater)
+        thread.finished.connect(lambda: _LIVE_THREADS.discard(entry))
+        thread.finished.connect(thread.deleteLater)
+        self._thread = thread                    # rule 3: unparented
+        thread.start()
+
+    def _detach(self) -> None:
+        """Cut every path from a running worker back into this dialog.
+
+        An `_alive` flag alone is not enough: if the dialog is destroyed while a worker is
+        still going, the queued call lands on a freed C++ object and takes the process
+        with it. Only OUR handlers are disconnected — `thread.quit` stays connected, or
+        the thread would never stop.
+        """
+        self._alive = False
+        for signal, slot in getattr(self, "_connections", []):
+            # A worker that already finished has dropped its connections, and PySide
+            # reports that as a warning rather than an exception. Closing a dialog after
+            # a successful run is the common case, so this must be silent.
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", RuntimeWarning)
+                try:
+                    signal.disconnect(slot)
+                except (RuntimeError, TypeError):
+                    pass
+        self._connections = []

gini/ui/zoo_lab.py

@@ -0,0 +1,112 @@
+"""Zoo Lab — a historical OS from the OS Zoo, running under emulation with its screen embedded.
+
+Open it by double-clicking an OS Zoo element (FreeDOS, Plan 9, ReactOS, or a bring-your-own
+classic OS) once the topology is running. The container boots the guest under QEMU with a VNC
+framebuffer and serves it as a web page (noVNC); this dialog embeds that page in a
+`QWebEngineView`, so the OS runs right inside gBuilder — mouse, keyboard, boot and all.
+
+The embedded page is the full noVNC client (`vnc.html`), which already carries its own toolbar
+for power/keys (Ctrl-Alt-Del), clipboard and fullscreen; this wrapper just frames it and adds
+Reload / Open-in-browser. Importing this module requires QtWebEngine — the caller catches an
+ImportError and falls back to opening the same URL in the system browser, so the feature works
+with no extra dependency.
+
+Sibling of the Machine Lab (xv6): there you inspect an OS's internals; here you *use* a whole
+historical OS live.
+"""
+from __future__ import annotations
+
+from PySide6.QtCore import QUrl
+from PySide6.QtGui import QDesktopServices
+from PySide6.QtWebEngineWidgets import QWebEngineView   # ships in PySide6-Addons (or full PySide6)
+from PySide6.QtWidgets import QDialog, QHBoxLayout, QLabel, QPushButton, QVBoxLayout
+
+from .theme import ThemeManager, icons
+from .theme.manager import scale_css as _scss
+
+
+class ZooLab(QDialog):
+    """Embedded screen for one OS Zoo guest (noVNC in a QWebEngineView) + a small control strip."""
+
+    def __init__(self, parent, theme: ThemeManager, device, url: str) -> None:
+        super().__init__(parent)
+        self.theme = theme
+        self.device = device
+        self.url = url
+
+        t = theme.theme
+        self.setWindowTitle(f"Zoo Lab — {device.name}")
+        self.resize(1024, 820)                 # 1024x768 guest + room for the header/controls
+        self.setStyleSheet(f"QDialog{{background:{t.bg};}}")
+
+        root = QVBoxLayout(self)
+        self._build_header(root)
+        self._view = QWebEngineView(self)
+        self._view.setUrl(QUrl(url))
+        root.addWidget(self._view, 1)
+
+    # -- header / controls --------------------------------------------------- #
+    def _build_header(self, root) -> None:
+        t = self.theme.theme
+        head = QHBoxLayout()
+        ic = QLabel(); ic.setPixmap(icons.render_pixmap("host", t.accent_for("orange"), 24))
+        title = QLabel(f"  {self.device.name} — {self._label()}")
+        title.setStyleSheet(_scss(f"color:{t.text};font-size:16px;font-weight:600;"))
+        head.addWidget(ic); head.addWidget(title); head.addStretch(1)
+
+        tk = self.device.type_key
+        try:
+            from ..domain import os_zoo
+            chip = ("bring your own image" if tk == "oszoo_byo"
+                    else "boots out of the box" if os_zoo.get(tk) else "over noVNC")
+        except Exception:
+            chip = "over noVNC"
+        tier = QLabel(chip)
+        tier.setStyleSheet(
+            f"color:{t.muted};background:{t.panel2};border:1px solid {t.line};"
+            "border-radius:9px;padding:2px 10px;font-size:11px;")
+        head.addWidget(tier)
+
+        reload_btn = QPushButton("  Reload")
+        reload_btn.setIcon(icons.icon("link", t.accent_for("blue"), 14))
+        reload_btn.setToolTip("Reconnect the embedded screen")
+        reload_btn.clicked.connect(lambda: self._view.setUrl(QUrl(self.url)))
+        reload_btn.setStyleSheet(self._btn_css())
+        head.addWidget(reload_btn)
+
+        browser = QPushButton("  Open in browser")
+        browser.setIcon(icons.icon("open", t.accent_for("green"), 14))
+        browser.setToolTip("Open this OS's screen in your web browser instead")
+        browser.clicked.connect(lambda: QDesktopServices.openUrl(QUrl(self.url)))
+        browser.setStyleSheet(self._btn_css())
+        head.addWidget(browser)
+        root.addLayout(head)
+
+    def _label(self) -> str:
+        tk = self.device.type_key
+        try:
+            from ..domain import os_zoo
+            if tk != "oszoo_byo":
+                o = os_zoo.get(tk)
+                if o:
+                    return o.label
+            elif tk == "oszoo_byo":
+                img = (self.device.properties or {}).get("Image", "")
+                return f"classic OS ({img})" if img else "classic OS (set an image)"
+        except Exception:
+            pass
+        try:                                       # generic (e.g. a Desktop machine): element label
+            from ..domain.devices import REGISTRY
+            dt = REGISTRY.get(tk)
+            if dt:
+                return dt.label
+        except Exception:
+            pass
+        return tk
+
+    def _btn_css(self) -> str:
+        t = self.theme.theme
+        return _scss(
+            f"QPushButton{{color:{t.text};background:{t.panel2};border:1px solid {t.line};"
+            f"border-radius:8px;padding:4px 12px;font-size:12px;}}"
+            f"QPushButton:hover{{border-color:{t.accent};}}")

gini_toolkit-6.0.1.dev0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: gini-toolkit
+Version: 6.0.1.dev0
+Summary: GINI gBuilder — next-generation topology builder for computer networks and cloud computing experimentation
+Author: GINI Toolkit
+License: GPL-3.0-or-later
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PySide6-Essentials>=6.6
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: agent
+Requires-Dist: mcp>=1.0; extra == "agent"
+Provides-Extra: graph
+Requires-Dist: matplotlib>=3.7; extra == "graph"
+Requires-Dist: numpy>=1.24; extra == "graph"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-qt>=4; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+
+# GINI gBuilder — next generation
+
+A ground-up rewrite of the GINI gBuilder frontend on **PySide6 (Qt 6) / Python 3**, expanding
+GINI from a computer-networks lab into an **ultimate experimentation toolkit** spanning both
+**computer networks** and **cloud computing**, with a first-class **AI agent layer** so agents can
+build, inspect, and explain topologies for students.
+
+## What's here
+
+```
+frontend-ng/
+├── pyproject.toml
+├── src/gini/
+│   ├── __main__.py          launch the app  (python -m gini)
+│   ├── domain/              pure-Python model — NO Qt
+│   │   ├── devices.py       device/element registry (networking + cloud)
+│   │   └── topology.py      Topology, DeviceInstance, Link
+│   ├── app/
+│   │   └── context.py       AppContext + typed event bus (replaces global singletons)
+│   ├── ui/
+│   │   ├── main_window.py   shell: toolbar, palette, canvas, inspector, console, assistant
+│   │   ├── canvas.py        QGraphicsView scene + node/edge items
+│   │   ├── palette.py       searchable, categorized device palette
+│   │   ├── inspector.py     tabbed property inspector
+│   │   ├── assistant.py     in-app "Ask GINI" AI assistant panel
+│   │   └── theme/
+│   │       ├── tokens.py    themeable design tokens (dark / light / brand)
+│   │       ├── manager.py   token → QSS generator + ThemeManager
+│   │       └── icons.py     license-safe flat SVG icon set, recolored per category
+│   └── agent/
+│       ├── api.py           programmatic GiniAPI: build / inspect / explain / run
+│       └── mcp_server.py    MCP server exposing GiniAPI to external agents
+└── tests/
+```
+
+## Run it
+
+```bash
+cd frontend-ng
+pip install -e .
+gbuilder                 # or:  python -m gini
+```
+
+Headless smoke test (no display needed):
+
+```bash
+QT_QPA_PLATFORM=offscreen python -m gini --selftest
+```
+
+## Status
+
+Early scaffold (Phase 2 of the evolution plan). The UI shell, themeable design system, icon
+system, the expanded device taxonomy, and the agent API/MCP scaffold are in place and runnable.
+The legacy `.gsav`/compiler/protocol services are being ported behind `services/` next.
+
+See `../GINI Project/GINI_Frontend_Evolution_Plan.md` for the full roadmap.