py-data-engine 0.1.0__py3-none-any.whl

data_engine/ui/gui/render_support.py

@@ -0,0 +1,241 @@
+"""Rendering and widget-presentation helpers for the GUI application shell."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QColor, QIcon, QPixmap
+from PySide6.QtWidgets import QFrame, QHBoxLayout, QLabel, QPushButton, QStyle, QWidget
+
+from data_engine.domain import FlowLogEntry, RuntimeStepEvent
+from data_engine.ui.gui.helpers import (
+    action_bar_icon as helper_action_bar_icon,
+    apply_theme as helper_apply_theme,
+    artifact_key_for_operation as helper_artifact_key_for_operation,
+    capture_step_outputs as helper_capture_step_outputs,
+    group_icon as helper_group_icon,
+    group_icon_color as helper_group_icon_color,
+    inspect_step_output as helper_inspect_step_output,
+    is_inspectable_operation as helper_is_inspectable_operation,
+    log_icon as helper_log_icon,
+    refresh_operation_buttons as helper_refresh_operation_buttons,
+    rehydrate_step_outputs_from_ledger as helper_rehydrate_step_outputs_from_ledger,
+    render_group_icon_pixmap as helper_render_group_icon_pixmap,
+    render_svg_icon_pixmap as helper_render_svg_icon_pixmap,
+    show_config_preview as helper_show_config_preview,
+    show_output_preview as helper_show_output_preview,
+    sync_theme_to_system as helper_sync_theme_to_system,
+    toggle_theme as helper_toggle_theme,
+    update_operation_scroll_cues as helper_update_operation_scroll_cues,
+    update_sidebar_scroll_cues as helper_update_sidebar_scroll_cues,
+    view_rail_icon as helper_view_rail_icon,
+)
+from data_engine.ui.gui.presenters import refresh_sidebar_selection, refresh_sidebar_state_views, repolish_widget_tree, set_hovered
+from data_engine.ui.gui.presenters import (
+    apply_runtime_event as present_runtime_event,
+    duration_text as present_duration_text,
+    format_raw_log_message as present_format_raw_log_message,
+    format_seconds as present_format_seconds,
+    normalize_completed_operation_rows as present_normalize_completed_operation_rows,
+    refresh_live_operation_durations as present_refresh_live_operation_durations,
+    render_operation_durations as present_render_operation_durations,
+    reset_operation_state as present_reset_operation_state,
+)
+from data_engine.ui.gui.widgets import (
+    build_flow_row_widget,
+    build_group_row_widget,
+    format_operation_title as view_format_operation_title,
+    set_operation_cards as view_set_operation_cards,
+)
+
+if TYPE_CHECKING:
+    from data_engine.ui.gui.app import DataEngineWindow
+    from data_engine.views.models import QtFlowCard
+
+
+class GuiRenderingMixin:
+    """Widget rendering and visual-state helpers for the GUI shell."""
+
+    def _format_raw_log_message(self: "DataEngineWindow", entry: FlowLogEntry) -> str:
+        return present_format_raw_log_message(entry)
+
+    def _set_operation_cards(self: "DataEngineWindow", operation_items: tuple[str, ...]) -> None:
+        view_set_operation_cards(self, operation_items)
+
+    def _update_operation_scroll_cues(self: "DataEngineWindow", *args) -> None:
+        helper_update_operation_scroll_cues(self, *args)
+
+    def _update_sidebar_scroll_cues(self: "DataEngineWindow", *args) -> None:
+        helper_update_sidebar_scroll_cues(self, *args)
+
+    def _format_operation_title(self: "DataEngineWindow", operation_name: str) -> str:
+        return view_format_operation_title(operation_name)
+
+    def _reset_operation_state(self: "DataEngineWindow", flow_name: str) -> None:
+        present_reset_operation_state(self, flow_name)
+
+    def _apply_runtime_event(self: "DataEngineWindow", event: RuntimeStepEvent) -> None:
+        present_runtime_event(self, event)
+
+    def _render_operation_durations(self: "DataEngineWindow", flow_name: str) -> None:
+        present_render_operation_durations(self, flow_name)
+
+    def _duration_text(self: "DataEngineWindow", flow_name: str, operation_name: str) -> str:
+        return present_duration_text(self, flow_name, operation_name)
+
+    def _refresh_live_operation_durations(self: "DataEngineWindow") -> None:
+        present_refresh_live_operation_durations(self)
+
+    def _apply_operation_row_state(self: "DataEngineWindow", row_card: QFrame, row_state) -> None:
+        status = row_state.status if row_state is not None else "idle"
+        if row_card.property("stepState") == status:
+            return
+        row_card.setProperty("stepState", status)
+        style = row_card.style()
+        style.unpolish(row_card)
+        style.polish(row_card)
+        row_card.update()
+
+    def _flash_operation_row(self: "DataEngineWindow", index: int) -> None:
+        from data_engine.ui.gui.presenters.steps import flash_operation_row
+
+        flash_operation_row(self, index)
+
+    def _normalize_completed_operation_rows(self: "DataEngineWindow", flow_name: str) -> None:
+        present_normalize_completed_operation_rows(self, flow_name)
+
+    def _format_seconds(self: "DataEngineWindow", seconds: float) -> str:
+        return present_format_seconds(seconds)
+
+    def _group_icon(self: "DataEngineWindow", group_name: str) -> QIcon:
+        return helper_group_icon(self, group_name)
+
+    def _group_icon_color(self: "DataEngineWindow") -> QColor:
+        return helper_group_icon_color(self)
+
+    def _render_svg_icon_pixmap(
+        self: "DataEngineWindow", icon_name: str, size: int, *, fill_color: str | None = None
+    ) -> QPixmap:
+        return helper_render_svg_icon_pixmap(self, icon_name, size, fill_color=fill_color)
+
+    def _view_rail_icon(self: "DataEngineWindow", view_name: str) -> QIcon:
+        return helper_view_rail_icon(self, view_name)
+
+    def _action_bar_icon(self: "DataEngineWindow", action_name: str) -> QIcon:
+        return helper_action_bar_icon(self, action_name)
+
+    def _log_icon(self: "DataEngineWindow", icon_name: str, size: int = 16) -> QIcon:
+        return helper_log_icon(self, icon_name, size)
+
+    def _render_group_icon_pixmap(self: "DataEngineWindow", group_name: str, size: int) -> QPixmap:
+        return helper_render_group_icon_pixmap(self, group_name, size)
+
+    def _build_group_row_widget(self: "DataEngineWindow", group_name: str, entries: list["QtFlowCard"]) -> QFrame:
+        return build_group_row_widget(self, group_name, entries)
+
+    def _build_flow_row_widget(self: "DataEngineWindow", card: "QtFlowCard") -> QFrame:
+        return build_flow_row_widget(self, card)
+
+    def _build_log_run_widget(self: "DataEngineWindow", run_group) -> QFrame:
+        frame = QFrame()
+        frame.setObjectName("logRunRow")
+        layout = QHBoxLayout(frame)
+        layout.setContentsMargins(8, 6, 8, 6)
+        layout.setSpacing(10)
+
+        title_row = QHBoxLayout()
+        title_row.setContentsMargins(0, 0, 0, 0)
+        title_row.setSpacing(8)
+        title = QLabel(run_group.display_label)
+        title.setObjectName("logPrimary")
+        title_row.addWidget(title, 0, Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter)
+        if run_group.elapsed_seconds is not None:
+            duration = QLabel(self._format_seconds(run_group.elapsed_seconds))
+            duration.setObjectName("logDuration")
+            title_row.addWidget(duration, 0, Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter)
+        title_row.addStretch(1)
+        layout.addLayout(title_row, 1)
+
+        status_name = "failed" if run_group.status in {"failed", "stopped"} else "started" if run_group.status == "started" else "finished"
+        status_icon = QLabel()
+        status_icon.setObjectName("logStatusIcon")
+        status_icon.setPixmap(self._render_svg_icon_pixmap(self._LOG_ICON_NAMES[status_name], 16, fill_color=self._LOG_ICON_COLORS[status_name]))
+        status_icon.setToolTip(run_group.status.title())
+        layout.addWidget(status_icon, 0, Qt.AlignmentFlag.AlignVCenter)
+
+        view_button = QPushButton()
+        view_button.setObjectName("logIconButton")
+        view_button.setIcon(self._log_icon("view_log"))
+        view_button.setIconSize(QPixmap(16, 16).size())
+        view_button.setToolTip("View Log")
+        view_button.clicked.connect(lambda _checked=False, group=run_group: self._show_run_log_preview(group))
+        layout.addWidget(view_button, 0, Qt.AlignmentFlag.AlignVCenter)
+
+        return frame
+
+    def _refresh_sidebar_selection(self: "DataEngineWindow") -> None:
+        refresh_sidebar_selection(self)
+
+    def _refresh_sidebar_state_views(self: "DataEngineWindow", changed_flow_names: set[str]) -> None:
+        """Refresh sidebar labels/colors in place for state-only changes."""
+        if refresh_sidebar_state_views(self, changed_flow_names):
+            self._populate_flow_tree()
+
+    def _set_hovered(self: "DataEngineWindow", widget: QFrame, hovered: bool) -> None:
+        """Update one sidebar row hover property and repolish it."""
+        set_hovered(widget, hovered)
+
+    def _repolish_widget_tree(self: "DataEngineWindow", widget: QWidget) -> None:
+        """Reapply stylesheet state to one widget and its child widgets."""
+        repolish_widget_tree(widget)
+
+    def _flow_icon(self: "DataEngineWindow", card: "QtFlowCard") -> QIcon:
+        """Return a left-side icon for one flow row."""
+        style = self.style()
+        state = self.flow_states.get(card.name, card.state)
+        if state == "failed":
+            return style.standardIcon(QStyle.StandardPixmap.SP_MessageBoxCritical)
+        if state in {"running", "polling", "scheduled"}:
+            return style.standardIcon(QStyle.StandardPixmap.SP_DialogApplyButton)
+        if state in {"stopping flow", "stopping runtime"}:
+            return style.standardIcon(QStyle.StandardPixmap.SP_BrowserStop)
+        if card.mode == "schedule":
+            return style.standardIcon(QStyle.StandardPixmap.SP_FileDialogDetailedView)
+        if card.mode == "poll":
+            return style.standardIcon(QStyle.StandardPixmap.SP_BrowserReload)
+        return style.standardIcon(QStyle.StandardPixmap.SP_FileIcon)
+
+    def _toggle_theme(self: "DataEngineWindow") -> None:
+        helper_toggle_theme(self)
+
+    def _sync_theme_to_system(self: "DataEngineWindow", *args) -> None:
+        helper_sync_theme_to_system(self, *args)
+
+    def _apply_theme(self: "DataEngineWindow") -> None:
+        helper_apply_theme(self)
+
+    def _is_inspectable_operation(self: "DataEngineWindow", operation_name: str) -> bool:
+        return helper_is_inspectable_operation(operation_name)
+
+    def _artifact_key_for_operation(self: "DataEngineWindow", operation_name: str) -> str | None:
+        return helper_artifact_key_for_operation(operation_name)
+
+    def _capture_step_outputs(self: "DataEngineWindow", flow_name: str, results: object) -> None:
+        helper_capture_step_outputs(self, flow_name, results)
+
+    def _rehydrate_step_outputs_from_ledger(self: "DataEngineWindow") -> None:
+        helper_rehydrate_step_outputs_from_ledger(self)
+
+    def _refresh_operation_buttons(self: "DataEngineWindow", flow_name: str) -> None:
+        helper_refresh_operation_buttons(self, flow_name)
+
+    def _inspect_step_output(self: "DataEngineWindow", operation_name: str) -> None:
+        helper_inspect_step_output(self, operation_name)
+
+    def _show_output_preview(self: "DataEngineWindow", operation_name: str, output_path: Path) -> None:
+        helper_show_output_preview(self, operation_name, output_path)
+
+    def _show_config_preview(self: "DataEngineWindow") -> None:
+        helper_show_config_preview(self)

data_engine/ui/gui/rendering/__init__.py

@@ -0,0 +1,12 @@
+"""Rendering helpers for the desktop UI."""
+
+from data_engine.ui.gui.rendering.artifacts import ArtifactPreviewSpec, classify_artifact_preview, populate_output_preview
+from data_engine.ui.gui.rendering.icons import render_svg_icon_pixmap, theme_svg_paths
+
+__all__ = [
+    "ArtifactPreviewSpec",
+    "classify_artifact_preview",
+    "populate_output_preview",
+    "render_svg_icon_pixmap",
+    "theme_svg_paths",
+]

data_engine/ui/gui/rendering/artifacts.py

@@ -0,0 +1,95 @@
+"""Artifact classification and preview rendering helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import polars as pl
+from PySide6.QtWidgets import (
+    QAbstractItemView,
+    QHeaderView,
+    QLabel,
+    QTableWidget,
+    QTableWidgetItem,
+    QTextEdit,
+    QVBoxLayout,
+)
+
+from data_engine.views import ArtifactPreviewSpec, classify_artifact_preview
+
+
+def populate_output_preview(layout: QVBoxLayout, output_path: Path, preview_spec: ArtifactPreviewSpec | None = None) -> None:
+    """Populate one dialog layout with the appropriate artifact preview widgets."""
+    preview_spec = preview_spec or classify_artifact_preview(output_path)
+    if preview_spec.kind == "parquet":
+        _add_tabular_preview(layout, pl.read_parquet(output_path), preview_spec.label)
+        return
+    if preview_spec.kind == "excel":
+        _add_tabular_preview(layout, pl.read_excel(output_path, sheet_id=1, engine="calamine"), preview_spec.label)
+        return
+    if preview_spec.kind == "text":
+        _add_text_preview(layout, output_path, preview_spec.label)
+        return
+    if preview_spec.kind == "pdf":
+        _add_placeholder_preview(
+            layout,
+            heading=preview_spec.label,
+            message=preview_spec.placeholder_message or "PDF artifacts are recognized, but in-app PDF text inspection is not available yet.",
+            output_path=output_path,
+        )
+        return
+    _add_placeholder_preview(
+        layout,
+        heading=preview_spec.label,
+        message=preview_spec.placeholder_message or "This artifact type is not previewable in the UI yet.",
+        output_path=output_path,
+    )
+
+
+def _add_tabular_preview(layout: QVBoxLayout, frame: pl.DataFrame, heading: str) -> None:
+    meta_label = QLabel(f"{heading}  {frame.height} row(s) x {len(frame.columns)} column(s)  Previewing up to 200 rows")
+    meta_label.setObjectName("sectionMeta")
+    layout.addWidget(meta_label)
+
+    table = QTableWidget()
+    table.setObjectName("outputPreviewTable")
+    table.setColumnCount(len(frame.columns))
+    table.setHorizontalHeaderLabels(frame.columns)
+    preview = frame.head(200)
+    table.setRowCount(preview.height)
+    table.setAlternatingRowColors(True)
+    table.setEditTriggers(QAbstractItemView.EditTrigger.NoEditTriggers)
+    table.setSelectionBehavior(QAbstractItemView.SelectionBehavior.SelectRows)
+    table.setSelectionMode(QAbstractItemView.SelectionMode.SingleSelection)
+    table.setShowGrid(False)
+    table.verticalHeader().setVisible(False)
+    table.horizontalHeader().setStretchLastSection(True)
+    table.horizontalHeader().setSectionResizeMode(QHeaderView.ResizeMode.ResizeToContents)
+    for row_index in range(preview.height):
+        for column_index, column_name in enumerate(preview.columns):
+            table.setItem(row_index, column_index, QTableWidgetItem(str(preview[row_index, column_name])))
+    layout.addWidget(table, 1)
+
+
+def _add_text_preview(layout: QVBoxLayout, output_path: Path, heading: str) -> None:
+    meta_label = QLabel(heading)
+    meta_label.setObjectName("sectionMeta")
+    layout.addWidget(meta_label)
+    body = QTextEdit()
+    body.setObjectName("outputPreviewText")
+    body.setReadOnly(True)
+    body.setPlainText(output_path.read_text(encoding="utf-8"))
+    layout.addWidget(body, 1)
+
+
+def _add_placeholder_preview(layout: QVBoxLayout, *, heading: str, message: str, output_path: Path) -> None:
+    size_bytes = output_path.stat().st_size if output_path.exists() else 0
+    meta_label = QLabel(f"{heading}  {size_bytes:,} bytes")
+    meta_label.setObjectName("sectionMeta")
+    layout.addWidget(meta_label)
+    body = QTextEdit()
+    body.setObjectName("outputPreviewText")
+    body.setReadOnly(True)
+    body.setPlainText(message)
+    layout.addWidget(body, 1)
+__all__ = ["ArtifactPreviewSpec", "classify_artifact_preview", "populate_output_preview"]

data_engine/ui/gui/rendering/icons.py

@@ -0,0 +1,50 @@
+"""Theme-aware SVG icon rendering helpers."""
+
+from __future__ import annotations
+
+import re
+
+from PySide6.QtCore import QRectF, Qt
+from PySide6.QtGui import QColor, QPainter, QPixmap
+from PySide6.QtSvg import QSvgRenderer
+
+from data_engine.ui.gui.icons import load_svg_icon_text
+
+
+def theme_svg_paths(svg_text: str, fill: str) -> str:
+    """Apply one fill color to every SVG path element in one icon."""
+
+    def _replace(match: re.Match[str]) -> str:
+        attributes = re.sub(r'\sfill="[^"]*"', "", match.group(1))
+        return f'<path fill="{fill}"{attributes}>'
+
+    return re.sub(r"<path\b([^>]*)>", _replace, svg_text)
+
+
+def render_svg_icon_pixmap(
+    *,
+    icon_name: str,
+    size: int,
+    device_pixel_ratio: float,
+    fill_color: str | None = None,
+    default_fill_color: QColor | str,
+) -> QPixmap:
+    """Render one registered SVG icon to one theme-aware pixmap."""
+    svg_text = load_svg_icon_text(icon_name)
+    if isinstance(default_fill_color, QColor):
+        default_fill = default_fill_color.name()
+    else:
+        default_fill = str(default_fill_color)
+    themed_svg = theme_svg_paths(svg_text, fill_color or default_fill)
+    renderer = QSvgRenderer(themed_svg.encode("utf-8"))
+    dpr = max(1.0, float(device_pixel_ratio))
+    pixmap = QPixmap(int(size * dpr), int(size * dpr))
+    pixmap.setDevicePixelRatio(dpr)
+    pixmap.fill(Qt.GlobalColor.transparent)
+    painter = QPainter(pixmap)
+    renderer.render(painter, QRectF(0, 0, size, size))
+    painter.end()
+    return pixmap
+
+
+__all__ = ["render_svg_icon_pixmap", "theme_svg_paths"]

data_engine/ui/gui/runtime.py

@@ -0,0 +1,47 @@
+"""Runtime wiring helpers for the Data Engine desktop UI."""
+
+from __future__ import annotations
+
+import logging
+from queue import Queue
+
+from PySide6.QtCore import QObject, Signal
+
+from data_engine.domain import FlowLogEntry, format_log_line, parse_runtime_event
+
+
+class QueueLogHandler(logging.Handler):
+    """Logging handler that forwards formatted runtime lines into a queue."""
+
+    def __init__(self, queue: Queue[FlowLogEntry]) -> None:
+        """Initialize the handler with the queue consumed by the UI thread."""
+        super().__init__(level=logging.INFO)
+        self.queue = queue
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Convert one log record into a UI entry and enqueue it."""
+        try:
+            event = parse_runtime_event(record)
+            kind = "flow" if event is not None and event.flow_name is not None else "system"
+            self.queue.put_nowait(
+                FlowLogEntry(
+                    line=format_log_line(record),
+                    kind=kind,
+                    event=event,
+                    flow_name=event.flow_name if event is not None else None,
+                )
+            )
+        except Exception:
+            self.handleError(record)
+
+
+class UiSignals(QObject):
+    """Cross-thread Qt signals used by background runtime workers."""
+
+    run_finished = Signal(object, object, object)
+    runtime_finished = Signal(object, object, object)
+    docs_build_finished = Signal(bool, str)
+    daemon_startup_finished = Signal(bool, str)
+
+
+__all__ = ["FlowLogEntry", "QueueLogHandler", "UiSignals"]

data_engine/ui/gui/state_support.py

@@ -0,0 +1,193 @@
+"""Operator-session and log plumbing helpers for the GUI shell."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from data_engine.domain import (
+    DaemonStatusState,
+    FlowLogEntry,
+    FlowCatalogState,
+    OperationSessionState,
+    OperatorSessionState,
+    RuntimeSessionState,
+    WorkspaceControlState,
+    WorkspaceSessionState,
+)
+from data_engine.ui.gui.surface import (
+    append_log_entry as surface_append_log_entry,
+    append_log_line as surface_append_log_line,
+    flush_deferred_ui_updates as surface_flush_deferred_ui_updates,
+    log_matches_selection as surface_log_matches_selection,
+    schedule_ui_refresh as surface_schedule_ui_refresh,
+)
+from data_engine.views.models import QtFlowCard, flow_catalog_entry_from_qt_card, qt_flow_cards_from_entries
+
+if TYPE_CHECKING:
+    from data_engine.ui.gui.app import DataEngineWindow
+
+
+class GuiStateMixin:
+    """Session-state and log-queue helpers separated from the main GUI shell."""
+
+    @property
+    def runtime_ledger(self: "DataEngineWindow"):
+        """Compatibility facade over the current runtime binding ledger."""
+        return self.runtime_binding.runtime_ledger
+
+    @property
+    def log_store(self: "DataEngineWindow"):
+        """Compatibility facade over the current runtime binding log store."""
+        return self.runtime_binding.log_store
+
+    @property
+    def _daemon_manager(self: "DataEngineWindow"):
+        """Compatibility facade over the current runtime binding daemon manager."""
+        return self.runtime_binding.daemon_manager
+
+    @property
+    def runtime_session(self: "DataEngineWindow") -> RuntimeSessionState:
+        """Return the current operator runtime/control session state."""
+        return self._operator_session_state.runtime
+
+    @runtime_session.setter
+    def runtime_session(self: "DataEngineWindow", value: RuntimeSessionState) -> None:
+        self._operator_session_state = self._operator_session_state.with_runtime(value)
+
+    @property
+    def flow_catalog_state(self: "DataEngineWindow") -> FlowCatalogState:
+        """Return the current discovered flow catalog state."""
+        return self._operator_session_state.catalog
+
+    @flow_catalog_state.setter
+    def flow_catalog_state(self: "DataEngineWindow", value: FlowCatalogState) -> None:
+        self._operator_session_state = self._operator_session_state.with_catalog(value)
+
+    @property
+    def flow_cards(self: "DataEngineWindow") -> dict[str, QtFlowCard]:
+        return {card.name: card for card in qt_flow_cards_from_entries(self.flow_catalog_state.entries)}
+
+    @flow_cards.setter
+    def flow_cards(self: "DataEngineWindow", value: dict[str, QtFlowCard] | tuple[QtFlowCard, ...]) -> None:
+        cards = tuple(value.values()) if isinstance(value, dict) else tuple(value)
+        self.flow_catalog_state = self.flow_catalog_state.with_entries(
+            tuple(flow_catalog_entry_from_qt_card(card) for card in cards)
+        )
+
+    @property
+    def flow_states(self: "DataEngineWindow") -> dict[str, str]:
+        return self.flow_catalog_state.flow_states or {}
+
+    @flow_states.setter
+    def flow_states(self: "DataEngineWindow", value: dict[str, str]) -> None:
+        self.flow_catalog_state = self.flow_catalog_state.with_flow_states(value)
+
+    @property
+    def selected_flow_name(self: "DataEngineWindow") -> str | None:
+        return self.flow_catalog_state.selected_flow_name
+
+    @selected_flow_name.setter
+    def selected_flow_name(self: "DataEngineWindow", value: str | None) -> None:
+        self.flow_catalog_state = self.flow_catalog_state.with_selected_flow_name(value)
+
+    @property
+    def empty_flow_message(self: "DataEngineWindow") -> str:
+        return self.flow_catalog_state.empty_message
+
+    @empty_flow_message.setter
+    def empty_flow_message(self: "DataEngineWindow", value: str) -> None:
+        self.flow_catalog_state = self.flow_catalog_state.with_empty_message(value)
+
+    @property
+    def daemon_status(self: "DataEngineWindow") -> DaemonStatusState:
+        """Return the current daemon status domain model."""
+        return self._daemon_status
+
+    @daemon_status.setter
+    def daemon_status(self: "DataEngineWindow", value: DaemonStatusState) -> None:
+        self._daemon_status = value
+
+    @property
+    def workspace_control_state(self: "DataEngineWindow") -> WorkspaceControlState:
+        """Return the current structured workspace control state."""
+        return self._operator_session_state.workspace_control
+
+    @workspace_control_state.setter
+    def workspace_control_state(self: "DataEngineWindow", value: WorkspaceControlState) -> None:
+        self._operator_session_state = self._operator_session_state.with_workspace_control(value)
+
+    @property
+    def workspace_session_state(self: "DataEngineWindow") -> WorkspaceSessionState:
+        """Return the current workspace selection/root session state."""
+        return self._operator_session_state.workspace
+
+    @workspace_session_state.setter
+    def workspace_session_state(self: "DataEngineWindow", value: WorkspaceSessionState) -> None:
+        self._operator_session_state = self._operator_session_state.with_workspace(value)
+
+    @property
+    def operator_session_state(self: "DataEngineWindow") -> OperatorSessionState:
+        """Return the top-level operator session state for this surface."""
+        return self._operator_session_state
+
+    @property
+    def operation_tracker(self: "DataEngineWindow") -> OperationSessionState:
+        """Return the current operation/step session state."""
+        return self._operator_session_state.operations
+
+    @operation_tracker.setter
+    def operation_tracker(self: "DataEngineWindow", value: OperationSessionState) -> None:
+        self._operator_session_state = self._operator_session_state.with_operations(value)
+
+    @property
+    def docs_build_running(self: "DataEngineWindow") -> bool:
+        """Return whether the documentation build is currently active for this GUI window."""
+        return self._docs_build_running
+
+    @docs_build_running.setter
+    def docs_build_running(self: "DataEngineWindow", value: bool) -> None:
+        self._docs_build_running = bool(value)
+
+    @property
+    def docs_root_dir(self: "DataEngineWindow") -> Path | None:
+        """Return the current built-docs root directory for this GUI window, if available."""
+        return self._docs_root_dir
+
+    @docs_root_dir.setter
+    def docs_root_dir(self: "DataEngineWindow", value: Path | None) -> None:
+        self._docs_root_dir = value
+
+    @property
+    def workspace_collection_root_override(self: "DataEngineWindow") -> Path | None:
+        return self.workspace_session_state.workspace_collection_root_override
+
+    @workspace_collection_root_override.setter
+    def workspace_collection_root_override(self: "DataEngineWindow", value: Path | None) -> None:
+        self.workspace_session_state = self.workspace_session_state.with_override_root(value)
+
+    @property
+    def discovered_workspace_ids(self: "DataEngineWindow") -> tuple[str, ...]:
+        return self.workspace_session_state.discovered_workspace_ids
+
+    @discovered_workspace_ids.setter
+    def discovered_workspace_ids(self: "DataEngineWindow", value: tuple[str, ...]) -> None:
+        self.workspace_session_state = self.workspace_session_state.with_discovered_workspace_ids(value)
+
+    def _log_matches_selection(self: "DataEngineWindow", entry: FlowLogEntry) -> bool:
+        return surface_log_matches_selection(self, entry)
+
+    def _append_log_entry(self: "DataEngineWindow", entry: FlowLogEntry) -> None:
+        surface_append_log_entry(self, entry)
+
+    def _schedule_ui_refresh(self: "DataEngineWindow", *, log_view: bool = False, action_buttons: bool = False) -> None:
+        surface_schedule_ui_refresh(self, log_view=log_view, action_buttons=action_buttons)
+
+    def _flush_deferred_ui_updates(self: "DataEngineWindow") -> None:
+        surface_flush_deferred_ui_updates(self)
+
+    def _append_log_line(self: "DataEngineWindow", line: str, *, flow_name: str | None = None) -> None:
+        surface_append_log_line(self, line, flow_name=flow_name)
+
+
+__all__ = ["GuiStateMixin"]