openprocess 0.7.0__py3-none-any.whl

openprocess/gui/studio/file_dialogs.py

@@ -0,0 +1,143 @@
+"""Small dialogs about files and folders.
+
+* :class:`ImportDialog` -- a file from outside the open folder is being
+  opened: copy it in, move it in, or open it where it is?
+* :func:`ask_about_clash` -- a file with that name is already there: keep
+  both, or replace it?
+* :class:`SettingsDialog` -- the app's settings (File ▸ Settings…, or the
+  application menu on macOS).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtWidgets import (
+    QButtonGroup, QCheckBox, QComboBox, QDialog, QDialogButtonBox, QFormLayout, QLabel,
+    QMessageBox, QRadioButton, QVBoxLayout, QWidget,
+)
+
+from .widgets import label, shortcut_text
+
+#: What to do with a file opened from outside the folder.
+IMPORT_CHOICES = {
+    "copy": "Copy into {folder}",
+    "move": "Move into {folder}",
+    "open": "Open from where it is",
+}
+IMPORT_DETAILS = {
+    "copy": "The original stays where it is.",
+    "move": "The file is no longer where it was.",
+    "open": "The folder will not have it next time.",
+}
+
+
+class ImportDialog(QDialog):
+    """Add files from elsewhere to the open folder?"""
+
+    def __init__(self, names: list[str], folder: str, parent=None,
+                 allow_open: bool = True, default: str = "copy") -> None:
+        super().__init__(parent)
+        self.setWindowTitle("Add to folder")
+        self.setMinimumWidth(440)
+        layout = QVBoxLayout(self)
+        layout.setSpacing(10)
+        what = f"“{names[0]}”" if len(names) == 1 else f"{len(names)} files"
+        heading = QLabel(f"<b>Add {what} to {folder}?</b>")
+        heading.setWordWrap(True)
+        layout.addWidget(heading)
+        if len(names) > 1:
+            listing = ", ".join(names[:5]) + (f" and {len(names) - 5} more" if len(names) > 5
+                                             else "")
+            layout.addWidget(label(listing, "muted", wrap=True))
+        self.group = QButtonGroup(self)
+        self.buttons: dict[str, QRadioButton] = {}
+        for key, text in IMPORT_CHOICES.items():
+            if key == "open" and not allow_open:
+                continue
+            radio = QRadioButton(text.format(folder=folder))
+            radio.setToolTip(IMPORT_DETAILS[key])
+            self.group.addButton(radio)
+            self.buttons[key] = radio
+            layout.addWidget(radio)
+        self.buttons.get(default, self.buttons["copy"]).setChecked(True)
+        self.always = QCheckBox(f"Always do this in {folder}")
+        layout.addWidget(self.always)
+        buttons = QDialogButtonBox(QDialogButtonBox.Ok | QDialogButtonBox.Cancel)
+        buttons.button(QDialogButtonBox.Ok).setText("Add")
+        buttons.accepted.connect(self.accept)
+        buttons.rejected.connect(self.reject)
+        layout.addWidget(buttons)
+
+    def choice(self) -> str:
+        return next(key for key, radio in self.buttons.items() if radio.isChecked())
+
+
+def ask_about_clash(parent: QWidget, target: Path) -> str | None:
+    """``"keep"`` (keep both), ``"replace"``, or None (skip this file)."""
+    box = QMessageBox(parent)
+    box.setIcon(QMessageBox.Question)
+    box.setWindowTitle("A file with that name exists")
+    box.setText(f"“{target.name}” is already in {target.parent.name}.")
+    box.setInformativeText("Keep both (the new one gets a number), or replace the one "
+                           "that is there? A replaced file goes to the Bin.")
+    keep = box.addButton("Keep Both", QMessageBox.AcceptRole)
+    replace = box.addButton("Replace", QMessageBox.DestructiveRole)
+    box.addButton("Skip", QMessageBox.RejectRole)
+    box.setDefaultButton(keep)
+    box.exec()
+    clicked = box.clickedButton()
+    return "keep" if clicked is keep else "replace" if clicked is replace else None
+
+
+class SettingsDialog(QDialog):
+    """The few settings the app has."""
+
+    IMPORT_LABELS = {"ask": "Ask each time", "copy": "Copy it into the folder",
+                     "move": "Move it into the folder", "open": "Open it from where it is"}
+
+    def __init__(self, values: dict, parent=None) -> None:
+        super().__init__(parent)
+        self.setWindowTitle("Settings")
+        self.setMinimumWidth(480)
+        layout = QVBoxLayout(self)
+        layout.setSpacing(12)
+        form = QFormLayout()
+        form.setVerticalSpacing(10)
+
+        self.autosave = QCheckBox("Save edits automatically")
+        self.autosave.setChecked(values["autosave"])
+        form.addRow("Nets in a folder", self.autosave)
+        form.addRow("", label("A second after you stop editing, and when you switch to "
+                              "another file or quit. Only for files in the open folder; "
+                              ".cpn files from CPN Tools are saved when you press "
+                              f"{shortcut_text('Ctrl+S')}.",
+                              "muted", wrap=True))
+
+        self.import_box = QComboBox()
+        for key, text in self.IMPORT_LABELS.items():
+            self.import_box.addItem(text, key)
+        self.import_box.setCurrentIndex(max(0, self.import_box.findData(values["import"])))
+        form.addRow("Opening a file from\noutside the folder", self.import_box)
+        form.addRow("", label("A choice made for one folder (“Always do this”) takes "
+                              "precedence.", "muted", wrap=True))
+
+        self.restore = QCheckBox("Reopen the folder and files at launch")
+        self.restore.setChecked(values["restore"])
+        form.addRow("Launch", self.restore)
+
+        self.updates = QCheckBox("Check for a new version when OpenProcess opens")
+        self.updates.setChecked(values["check_updates"])
+        form.addRow("Updates", self.updates)
+        layout.addLayout(form)
+
+        buttons = QDialogButtonBox(QDialogButtonBox.Ok | QDialogButtonBox.Cancel)
+        buttons.accepted.connect(self.accept)
+        buttons.rejected.connect(self.reject)
+        layout.addWidget(buttons)
+
+    def values(self) -> dict:
+        return {"autosave": self.autosave.isChecked(),
+                "import": self.import_box.currentData(),
+                "restore": self.restore.isChecked(),
+                "check_updates": self.updates.isChecked()}

openprocess/gui/studio/filter_dialog.py

@@ -0,0 +1,247 @@
+"""The Filter… dialog of a log page: ProM's and Disco's log filters in one form.
+
+Each filter is a group box that is switched off until you tick it; the line
+at the bottom previews the result as you change anything.  Accepting opens
+the filtered log as a new document next to the original (see
+:mod:`openprocess.mining.filtering` for what each filter does).
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from datetime import timezone
+
+from PySide6.QtCore import QDateTime, Qt, QTimer, QTimeZone
+from PySide6.QtWidgets import (
+    QButtonGroup, QComboBox, QDateTimeEdit, QDialog, QDialogButtonBox, QDoubleSpinBox,
+    QFormLayout, QGroupBox, QLineEdit, QListWidget, QListWidgetItem, QRadioButton, QSpinBox,
+    QVBoxLayout, QWidget,
+)
+
+from ...mining.filtering import FilterSettings, apply_filters
+from ...mining.stats import summarise
+from .widgets import button, hbox, label, scroll
+
+ACTIVITY_MODE_TEXT = [
+    ("keep events", "Keep only the events of the ticked activities"),
+    ("mandatory", "Keep cases that contain a ticked activity"),
+    ("forbidden", "Remove cases that contain a ticked activity"),
+]
+TIME_MODE_TEXT = [("contained", "Cases that start and end in the period"),
+                  ("started", "Cases that start in the period"),
+                  ("intersecting", "Cases active at some point in the period")]
+
+
+def _checklist(counts: Counter, total: int) -> QListWidget:
+    """Ticked items, most frequent first, each with its share of the cases."""
+    widget = QListWidget()
+    for name, count in counts.most_common():
+        item = QListWidgetItem(f"{name}   ({count:,} · {count / max(total, 1):.0%})")
+        item.setData(Qt.UserRole, name)
+        item.setFlags(item.flags() | Qt.ItemIsUserCheckable)
+        item.setCheckState(Qt.Checked)
+        widget.addItem(item)
+    widget.setMinimumHeight(min(60 + 22 * len(counts), 180))
+    return widget
+
+
+def _ticked(widget: QListWidget) -> set[str]:
+    return {widget.item(i).data(Qt.UserRole) for i in range(widget.count())
+            if widget.item(i).checkState() == Qt.Checked}
+
+
+def _set_all(widget: QListWidget, checked: bool) -> None:
+    for i in range(widget.count()):
+        widget.item(i).setCheckState(Qt.Checked if checked else Qt.Unchecked)
+
+
+class FilterDialog(QDialog):
+    """Choose filters for ``document``'s log; :meth:`result` is the new log."""
+
+    def __init__(self, document, parent=None) -> None:
+        super().__init__(parent)
+        self.document = document
+        self.log = document.log
+        self.classifier = document.classifier
+        self.setWindowTitle(f"Filter {document.name}")
+        self.setMinimumWidth(560)
+        sequences = self.log.sequences(self.classifier)
+        cases = len(sequences)
+        self._timer = QTimer(self, singleShot=True, interval=150)
+        self._timer.timeout.connect(self._preview)
+
+        # -- variants
+        self.variants_box = self._group("Variants", "Keep the most frequent behaviour.")
+        self.by_coverage = QRadioButton("Most frequent variants covering")
+        self.by_count = QRadioButton("The most frequent")
+        self.by_coverage.setChecked(True)
+        choice = QButtonGroup(self)
+        choice.addButton(self.by_coverage)
+        choice.addButton(self.by_count)
+        self.coverage = QDoubleSpinBox()
+        self.coverage.setRange(1, 100)
+        self.coverage.setDecimals(0)
+        self.coverage.setValue(80)
+        self.coverage.setSuffix(" % of the cases")
+        self.count = QSpinBox()
+        self.count.setRange(1, max(len(set(sequences)), 1))
+        self.count.setValue(min(5, self.count.maximum()))
+        self.count.setSuffix(" variants")
+        self.variants_box.layout().addLayout(hbox(self.by_coverage, self.coverage, None))
+        self.variants_box.layout().addLayout(hbox(self.by_count, self.count, None))
+
+        # -- activities
+        activity_cases = Counter(a for s in sequences for a in set(s))
+        self.activities_box = self._group("Activities", "Share = the cases the activity "
+                                          "occurs in.")
+        self.activity_mode = QComboBox()
+        for key, text in ACTIVITY_MODE_TEXT:
+            self.activity_mode.addItem(text, key)
+        self.activity_list = _checklist(activity_cases, cases)
+        self.activities_box.layout().addWidget(self.activity_mode)
+        self.activities_box.layout().addWidget(self.activity_list)
+        self.activities_box.layout().addLayout(hbox(
+            button("All", lambda: _set_all(self.activity_list, True), kind="ghost"),
+            button("None", lambda: _set_all(self.activity_list, False), kind="ghost"), None))
+
+        # -- start and end activities
+        self.start_box = self._group("Start activities", "Keep cases that start with a "
+                                     "ticked activity.")
+        self.start_list = _checklist(Counter(s[0] for s in sequences if s), cases)
+        self.start_box.layout().addWidget(self.start_list)
+        self.end_box = self._group("End activities", "Keep cases that end with a ticked "
+                                   "activity, e.g. to drop cases that were still running.")
+        self.end_list = _checklist(Counter(s[-1] for s in sequences if s), cases)
+        self.end_box.layout().addWidget(self.end_list)
+
+        # -- case length
+        lengths = [len(s) for s in sequences] or [0]
+        self.length_box = self._group("Case length", "Number of events per case (after the "
+                                      "activity filter).")
+        self.min_length, self.max_length = QSpinBox(), QSpinBox()
+        for box, value in ((self.min_length, min(lengths)), (self.max_length, max(lengths))):
+            box.setRange(0, 1_000_000)
+            box.setValue(value)
+        self.length_box.layout().addLayout(hbox(label("From"), self.min_length, label("to"),
+                                                self.max_length, label("events"), None))
+
+        # -- time frame
+        stamps = [e.timestamp for t in self.log for e in t if e.timestamp is not None]
+        self.time_box = self._group("Time frame", "Times in UTC.")
+        self.time_mode = QComboBox()
+        for key, text in TIME_MODE_TEXT:
+            self.time_mode.addItem(text, key)
+        self.time_from, self.time_to = QDateTimeEdit(), QDateTimeEdit()
+        for edit, stamp in ((self.time_from, min(stamps) if stamps else None),
+                            (self.time_to, max(stamps) if stamps else None)):
+            edit.setDisplayFormat("yyyy-MM-dd HH:mm:ss")
+            edit.setCalendarPopup(True)
+            if hasattr(edit, "setTimeZone"):                  # Qt 6.7 and later
+                edit.setTimeZone(QTimeZone.utc())
+            else:
+                edit.setTimeSpec(Qt.UTC)
+            if stamp is not None:
+                edit.setDateTime(QDateTime.fromSecsSinceEpoch(int(stamp.timestamp()),
+                                                              QTimeZone.utc()))
+        form = QFormLayout()
+        form.addRow("Keep", self.time_mode)
+        form.addRow("From", self.time_from)
+        form.addRow("To", self.time_to)
+        self.time_box.layout().addLayout(form)
+        if not stamps:
+            self.time_box.setEnabled(False)
+            self.time_box.setTitle("Time frame (this log has no timestamps)")
+
+        sections = QWidget()
+        column = QVBoxLayout(sections)
+        column.setContentsMargins(0, 0, 8, 0)
+        for box in (self.variants_box, self.activities_box, self.start_box, self.end_box,
+                    self.length_box, self.time_box):
+            column.addWidget(box)
+        column.addStretch(1)
+
+        self.name = QLineEdit(f"{document.name} (filtered)")
+        self.preview = label("", "muted", wrap=True)
+        self.buttons = QDialogButtonBox(QDialogButtonBox.Ok | QDialogButtonBox.Cancel)
+        self.buttons.button(QDialogButtonBox.Ok).setText("Create filtered log")
+        self.buttons.accepted.connect(self.accept)
+        self.buttons.rejected.connect(self.reject)
+
+        layout = QVBoxLayout(self)
+        layout.addWidget(label("Tick the filters to apply. The result opens as a new log; "
+                               "this one stays as it is.", "muted", wrap=True))
+        layout.addWidget(scroll(sections), 1)
+        name_row = QFormLayout()
+        name_row.addRow("Name", self.name)
+        layout.addLayout(name_row)
+        layout.addWidget(self.preview)
+        layout.addWidget(self.buttons)
+        self.resize(620, 720)
+
+        # Any change updates the preview (after a short pause).
+        for widget in (self.variants_box, self.activities_box, self.start_box, self.end_box,
+                       self.length_box, self.time_box):
+            widget.toggled.connect(self._changed)
+        for widget in (self.by_coverage, self.by_count):
+            widget.toggled.connect(self._changed)
+        for widget in (self.coverage, self.count, self.min_length, self.max_length):
+            widget.valueChanged.connect(self._changed)
+        for widget in (self.activity_mode, self.time_mode):
+            widget.currentIndexChanged.connect(self._changed)
+        for widget in (self.activity_list, self.start_list, self.end_list):
+            widget.itemChanged.connect(self._changed)
+        for widget in (self.time_from, self.time_to):
+            widget.dateTimeChanged.connect(self._changed)
+        self._result = None
+        self._preview()
+
+    def _group(self, title: str, hint: str) -> QGroupBox:
+        box = QGroupBox(title)
+        box.setCheckable(True)
+        box.setChecked(False)
+        layout = QVBoxLayout(box)
+        layout.addWidget(label(hint, "muted", wrap=True))
+        return box
+
+    def settings(self) -> FilterSettings:
+        """The filters as currently ticked."""
+        settings = FilterSettings()
+        if self.variants_box.isChecked():
+            if self.by_coverage.isChecked():
+                settings.variant_coverage = self.coverage.value()
+            else:
+                settings.top_variants = self.count.value()
+        if self.activities_box.isChecked():
+            settings.activities = (_ticked(self.activity_list),
+                                   self.activity_mode.currentData())
+        if self.start_box.isChecked():
+            settings.start_activities = _ticked(self.start_list)
+        if self.end_box.isChecked():
+            settings.end_activities = _ticked(self.end_list)
+        if self.length_box.isChecked():
+            settings.case_length = (self.min_length.value(), self.max_length.value())
+        if self.time_box.isChecked() and self.time_box.isEnabled():
+            start = self.time_from.dateTime().toPython().replace(tzinfo=timezone.utc)
+            end = self.time_to.dateTime().toPython().replace(tzinfo=timezone.utc)
+            settings.time_frame = (start, end, self.time_mode.currentData())
+        return settings
+
+    def _changed(self, *_args) -> None:
+        self._timer.start()
+
+    def _preview(self) -> None:
+        self._result = apply_filters(self.log, self.settings(), self.classifier,
+                                     name=self.name.text().strip() or None)
+        before = summarise(self.log, self.classifier)
+        after = summarise(self._result, self.classifier)
+        share = after.case_count / max(before.case_count, 1)
+        self.preview.setText(
+            f"Result: {after.case_count:,} of {before.case_count:,} cases ({share:.0%}) · "
+            f"{after.event_count:,} events · {after.variant_count:,} variants · "
+            f"{after.activity_count} activities")
+        self.buttons.button(QDialogButtonBox.Ok).setEnabled(after.case_count > 0)
+
+    def result_log(self):
+        """The filtered log (named as typed)."""
+        self._preview()
+        return self._result

openprocess/gui/studio/graph_builders.py

@@ -0,0 +1,176 @@
+"""Turn mining objects into canvas descriptions (:class:`NodeSpec` / :class:`EdgeSpec`).
+
+Keeping this separate from the canvas means the drawing code knows nothing
+about Petri nets or logs, and these functions know nothing about Qt.
+"""
+
+from __future__ import annotations
+
+import math
+
+from ...mining.analysis import StateGraph
+from ...mining.dfg import DFG, END, START
+from ...mining.discovery.heuristics import DependencyGraph
+from ...mining.petrinet import Marking, PetriNet
+from ...mining.stats import format_duration
+from . import style
+from .graph_view import EdgeSpec, NodeSpec
+
+
+ENABLED_FILL = "#dff5e4"
+ENABLED_FILL_DARK = "#1e4028"
+ENABLED_STROKE = "#2e9e4f"
+
+
+def compact(n: float) -> str:
+    """1284 -> 1,284;  12900 -> 12.9K."""
+    if n >= 100_000:
+        return f"{n / 1000:.0f}K"
+    if n >= 10_000:
+        return f"{n / 1000:.1f}K"
+    return f"{int(n):,}"
+
+
+# ---------------------------------------------------------------------------
+# Petri nets
+# ---------------------------------------------------------------------------
+def petri_net_specs(net: PetriNet, marking: Marking | None = None,
+                    enabled: set[str] | None = None,
+                    badges: dict[str, list[tuple[str, str]]] | None = None,
+                    fills: dict[str, str] | None = None,
+                    show_place_names: bool = True) -> tuple[list[NodeSpec], list[EdgeSpec]]:
+    t = style.tokens()
+    marking = marking if marking is not None else net.initial_marking
+    enabled = enabled or set()
+    badges = badges or {}
+    fills = fills or {}
+    nodes: list[NodeSpec] = []
+    for place in net.places.values():
+        roles = []
+        if net.initial_marking[place.id]:
+            roles.append("initial")
+        if net.final_marking[place.id]:
+            roles.append("final")
+        name = place.name
+        tip = f"Place {name}" + (f" ({', '.join(roles)})" if roles else "")
+        tip += f"\nTokens: {marking[place.id]}"
+        nodes.append(NodeSpec(place.id, "place", below=name if show_place_names else "",
+                              tokens=marking[place.id], badges=badges.get(place.id, []),
+                              tooltip=tip, fill=fills.get(place.id)))
+    for transition in net.transitions.values():
+        is_enabled = transition.id in enabled
+        tip = ("Silent transition (τ)" if transition.silent else f"Transition {transition.label}")
+        if is_enabled:
+            tip += "\nEnabled — click to fire"
+        # Enabled transitions are green, as in CPN Tools and CPN IDE; a silent
+        # transition keeps its solid fill but gets the green outline.
+        enabled_fill = ENABLED_FILL_DARK if style.theme.is_dark() else ENABLED_FILL
+        fill = fills.get(transition.id)
+        if fill is None and is_enabled:
+            fill = ENABLED_STROKE if transition.silent else enabled_fill
+        nodes.append(NodeSpec(
+            transition.id, "silent" if transition.silent else "transition",
+            text="" if transition.silent else transition.name,
+            fill=fill, stroke=ENABLED_STROKE if is_enabled else None, emphasis=is_enabled,
+            badges=badges.get(transition.id, []), tooltip=tip))
+    edges = [EdgeSpec(a.source, a.target, text=str(a.weight) if a.weight != 1 else "",
+                      width=1.4) for a in net.arcs]
+    return nodes, edges
+
+
+# ---------------------------------------------------------------------------
+# Process maps
+# ---------------------------------------------------------------------------
+def dfg_specs(dfg: DFG, mode: str = "frequency") -> tuple[list[NodeSpec], list[EdgeSpec]]:
+    """Frequency mode: node fill = how often; edge width = how often.
+    Performance mode: edge labels are mean durations; the slowest edges are
+    drawn thickest, in the accent-free critical tone with a text label."""
+    t = style.tokens()
+    most = max(dfg.activities.values(), default=1)
+    nodes = [NodeSpec(START, "start", tooltip=f"Start — {sum(dfg.start.values()):,} cases"),
+             NodeSpec(END, "end", tooltip=f"End — {sum(dfg.end.values()):,} cases")]
+    for activity, count in dfg.activities.items():
+        fraction = math.log1p(count) / math.log1p(most) if most else 0
+        fill = style.sequential(0.1 + 0.8 * fraction)
+        nodes.append(NodeSpec(activity, "activity", text=activity, subtext=compact(count),
+                              fill=fill, stroke=style.SEQUENTIAL_BLUE[-3],
+                              tooltip=f"{activity}\n{count:,} events"))
+
+    all_edges = dfg.all_edges()
+    top = max((n for _, _, n in all_edges), default=1)
+    durations = {edge: dfg.mean_duration(edge) for edge in dfg.edges}
+    slowest = max((d for d in durations.values() if d is not None), default=0)
+    edges: list[EdgeSpec] = []
+    for a, b, count in all_edges:
+        weight = count / top if top else 0
+        if mode == "performance" and (a, b) in dfg.edges:
+            mean = durations.get((a, b))
+            relative = (mean / slowest) if (mean is not None and slowest) else 0
+            edges.append(EdgeSpec(
+                a, b, text=format_duration(mean) if mean is not None else "",
+                width=1.2 + 4.5 * relative,
+                colour=style.STATUS["critical"] if relative > 0.66 else t.text_secondary,
+                tooltip=f"{a} → {b}\nmean {format_duration(mean)} · median "
+                        f"{format_duration(dfg.median_duration((a, b)))} · {count:,}×"))
+        else:
+            edges.append(EdgeSpec(a, b, text=compact(count) if mode == "frequency" else "",
+                                  width=1.0 + 4.5 * weight,
+                                  colour=t.text_secondary if weight > 0.15 else t.text_muted,
+                                  dashed=a == START or b == END,
+                                  tooltip=f"{a} → {b}: {count:,} times"))
+    return nodes, edges
+
+
+def dependency_specs(graph: DependencyGraph) -> tuple[list[NodeSpec], list[EdgeSpec]]:
+    t = style.tokens()
+    most = max(graph.activities.values(), default=1)
+    nodes = [NodeSpec(START, "start"), NodeSpec(END, "end")]
+    for activity, count in graph.activities.items():
+        fraction = math.log1p(count) / math.log1p(most)
+        nodes.append(NodeSpec(activity, "activity", text=activity, subtext=compact(count),
+                              fill=style.sequential(0.1 + 0.8 * fraction),
+                              stroke=style.SEQUENTIAL_BLUE[-3]))
+    edges = [EdgeSpec(START, a, dashed=True, colour=t.text_muted) for a in graph.start]
+    edges += [EdgeSpec(a, END, dashed=True, colour=t.text_muted) for a in graph.end]
+    for (a, b), (value, count) in graph.edges.items():
+        edges.append(EdgeSpec(a, b, text=f"{value:.2f}", width=1.0 + 3 * max(value, 0),
+                              colour=t.text_secondary,
+                              tooltip=f"{a} ⇒ {b} = {value:.3f}   (|{a} > {b}| = {count})"))
+    return nodes, edges
+
+
+# ---------------------------------------------------------------------------
+# State spaces
+# ---------------------------------------------------------------------------
+def state_graph_specs(graph: StateGraph, limit: int = 250) -> tuple[list[NodeSpec], list[EdgeSpec]]:
+    t = style.tokens()
+    net = graph.net
+    shown = min(len(graph.states), limit)
+    dead = set(graph.dead_states())
+    nodes = []
+    for index in range(shown):
+        marking = graph.states[index]
+        is_final = marking == net.final_marking and bool(net.final_marking)
+        tip = f"State {index}: {marking.describe(net)}"
+        if index == 0:
+            tip += "\nInitial marking"
+        if index in dead:
+            tip += "\nDead: nothing is enabled" + (" (final marking)" if is_final else "")
+        stroke = None
+        if index in dead and not is_final:
+            stroke = style.STATUS["critical"]
+        nodes.append(NodeSpec(str(index), "state", text=marking.describe(net), tooltip=tip,
+                              emphasis=index == 0 or is_final, stroke=stroke,
+                              fill=t.accent_soft if index == 0 else None))
+    # Several transitions can lead from the same state to the same state
+    # (e.g. a choice between three seats that all end in [sink]); draw them
+    # as one edge carrying all labels instead of stacking identical curves.
+    labels: dict[tuple[int, int], list[str]] = {}
+    for s, tr, d in graph.edges:
+        if s < shown and d < shown:
+            labels.setdefault((s, d), []).append(net.transitions[tr].name)
+    edges = [EdgeSpec(str(s), str(d), width=1.2,
+                      text=names[0] if len(names) == 1 else f"{names[0]} +{len(names) - 1}",
+                      tooltip="\n".join(names))
+             for (s, d), names in labels.items()]
+    return nodes, edges