synodic-client 0.0.1.dev77__tar.gz → 0.0.1.dev78__tar.gz

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: synodic_client
-Version: 0.0.1.dev77
+Version: 0.0.1.dev78
 Author-Email: Synodic Software <contact@synodic.software>
 License: LGPL-3.0-or-later
 Project-URL: homepage, https://github.com/synodic/synodic-client

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/pyproject.toml

@@ -15,7 +15,7 @@ dependencies = [
     "velopack>=0.0.1521.dev61717",
     "typer>=0.24.1",
 ]
-version = "0.0.1.dev77"
+version = "0.0.1.dev78"
 
 [project.license]
 text = "LGPL-3.0-or-later"

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/synodic_client/application/schema.py

@@ -43,36 +43,3 @@ class Snapshot:
 
     plugin_capabilities: dict[str, frozenset[PluginCapability]] = field(default_factory=dict)
     """Protocol capabilities reported for each discovered plugin."""
-
-
-@dataclass(slots=True)
-class ToolUpdateResult:
-    """Summary of a tool-update run across cached manifests."""
-
-    manifests_processed: int = 0
-    updated: int = 0
-    already_latest: int = 0
-    failed: int = 0
-    updated_packages: set[str] = field(default_factory=set)
-    """Package names that were successfully upgraded."""
-
-
-@dataclass(frozen=True, slots=True)
-class UpdateTarget:
-    """Identifies the scope of a manual tool update.
-
-    Passed to the shared completion handler so it can clear the correct
-    updating state and derive timestamp keys.  ``None`` (the default in
-    the handler) means the update was periodic / automatic.
-
-    When *package* is empty the update targeted an entire plugin;
-    otherwise it targeted one specific package within the plugin.
-    *plugin* always carries the signal key (possibly composite
-    ``"plugin:tag"``).
-    """
-
-    plugin: str
-    """Signal key for the plugin (may be composite ``"name:tag"``)."""
-
-    package: str = ''
-    """Package name, or empty when the whole plugin was updated."""

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/synodic_client/application/screen/action_card.py

@@ -79,6 +79,15 @@ _SPINNER_INTERVAL = 50
 #: display order always matches the order actions actually execute.
 _KIND_ORDER: dict[PluginKind | None, int] = {kind: i for i, kind in enumerate(PHASE_ORDER)}
 
+#: Mapping of resolved status label → stylesheet for dry-run badge styling.
+_STATUS_STYLES: dict[str, str] = {
+    'Update available': ACTION_CARD_STATUS_UPDATE,
+    'Failed': ACTION_CARD_STATUS_FAILED,
+    'Pending': ACTION_CARD_STATUS_PENDING,
+    'Ready': ACTION_CARD_STATUS_SATISFIED,
+    'Needed': ACTION_CARD_STATUS_NEEDED,
+}
+
 
 def action_sort_key(action: SetupAction) -> int:
     """Return a sort key that groups cards by execution phase.
@@ -465,15 +474,6 @@ class ActionCard(QFrame):
 
         self._stop_spinner()
 
-        # Status-to-style mapping
-        _STATUS_STYLES: dict[str, str] = {
-            'Update available': ACTION_CARD_STATUS_UPDATE,
-            'Failed': ACTION_CARD_STATUS_FAILED,
-            'Pending': ACTION_CARD_STATUS_PENDING,
-            'Ready': ACTION_CARD_STATUS_SATISFIED,
-            'Needed': ACTION_CARD_STATUS_NEEDED,
-        }
-
         style = _STATUS_STYLES.get(status, ACTION_CARD_STATUS_SATISFIED)
         display = status
 

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/synodic_client/application/screen/install.py

@@ -50,7 +50,6 @@ from synodic_client.application.screen.schema import (
     ActionState,
     InstallCallbacks,
     InstallConfig,
-    PreviewCallbacks,
     PreviewConfig,
     PreviewModel,
     PreviewPhase,
@@ -499,12 +498,7 @@ class SetupPreviewWidget(QWidget):
                     project_directory=project_directory,
                     prerelease_packages=prerelease_packages,
                 ),
-                callbacks=PreviewCallbacks(
-                    on_manifest_parsed=self._on_manifest_parsed,
-                    on_plugins_queried=self._on_plugins_queried,
-                    on_preview_ready=self._on_preview_resolved,
-                    on_action_checked=self._on_action_checked,
-                ),
+                on_event=self._on_preview_event,
                 plugins=self._discovered_plugins,
             )
             self._on_preview_finished()
@@ -540,6 +534,26 @@ class SetupPreviewWidget(QWidget):
             logger.exception('Install execution failed')
             self._on_install_error(str(exc))
 
+    # --- Preview event dispatcher ---
+
+    def _on_preview_event(self, event: object) -> None:
+        """Route a :data:`PreviewEvent` to the appropriate handler."""
+        from synodic_client.operations.schema import (
+            PreviewActionChecked,
+            PreviewManifestParsed,
+            PreviewPluginsQueried,
+            PreviewReady,
+        )
+
+        if isinstance(event, PreviewManifestParsed):
+            self._on_manifest_parsed(event.manifest, event.manifest_path, event.temp_dir)
+        elif isinstance(event, PreviewPluginsQueried):
+            self._on_plugins_queried(event.availability, event.capabilities)
+        elif isinstance(event, PreviewReady):
+            self._on_preview_resolved(event.manifest, event.manifest_path, event.temp_dir)
+        elif isinstance(event, PreviewActionChecked):
+            self._on_action_checked(event.index, event.result, event.status)
+
     # --- Preview callbacks (wired by load()) ---
 
     def _on_manifest_parsed(self, preview: SetupResults, manifest_path: str, temp_dir_path: str) -> None:
@@ -577,9 +591,6 @@ class SetupPreviewWidget(QWidget):
 
         self._show_metadata(preview)
 
-        if preview.metadata:
-            self.metadata_ready.emit(preview)
-
         if not preview.actions:
             self._card_list.clear()
             self._status_label.setText('No actions to perform — the manifest is empty.')
@@ -618,16 +629,13 @@ class SetupPreviewWidget(QWidget):
 
         Called after ``MANIFEST_LOADED`` — cards are already visible
         from the earlier ``_on_manifest_parsed`` handler.  This updates
-        the temp-dir reference and emits metadata.
+        the temp-dir reference.
         """
         if self._model.preview is None:
             return
 
         self._model.temp_dir = temp_dir_path
 
-        if preview.metadata:
-            self.metadata_ready.emit(preview)
-
     def _on_action_checked(self, row: int, result: SetupActionResult, status: str) -> None:
         """Update the model and action card with a dry-run result.
 
@@ -976,9 +984,7 @@ class SetupPreviewWidget(QWidget):
         pre_skipped = len(m.install_plan.satisfied_indices) if m.install_plan else 0
 
         # If we have stashed install results (auto-run path), use combined summary
-        install_results = (
-            list(self._install_results.results) if hasattr(self, '_install_results') and self._install_results else None
-        )
+        install_results = list(self._install_results.results) if self._install_results else None
         summary = format_install_summary(
             install_results=install_results,
             post_sync_results=m.post_sync_results,
@@ -988,7 +994,12 @@ class SetupPreviewWidget(QWidget):
         self._install_btn.setEnabled(False)
         self._run_commands_btn.setEnabled(False)
         self._close_btn.setEnabled(True)
-        self.install_finished.emit(results)
+
+        # Only emit when coming from the auto-run path (install_finished
+        # was not yet emitted).  On the manual "Run Commands" path the
+        # signal was already emitted by _on_install_finished.
+        if self._install_results is not None:
+            self.install_finished.emit(results)
 
 
 # ---------------------------------------------------------------------------

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/synodic_client/application/screen/install_workers.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from collections.abc import Callable
 from pathlib import Path
 
 from porringer.api import API
@@ -17,9 +18,6 @@ from porringer.backend.command.core.discovery import DiscoveredPlugins
 from porringer.schema import (
     ActionCompletedEvent,
     ActionStartedEvent,
-    ManifestLoadedEvent,
-    SetupAction,
-    SetupActionResult,
     SetupResults,
     SubActionProgressEvent,
 )
@@ -27,16 +25,13 @@ from porringer.schema import (
 from synodic_client.application.screen.schema import (
     InstallCallbacks,
     InstallConfig,
-    PreviewCallbacks,
     PreviewConfig,
 )
 from synodic_client.application.uri import safe_rmtree
-from synodic_client.operations.install import execute_install, execute_post_sync, preview_manifest_stream
+from synodic_client.operations.install import collect_install, collect_post_sync, preview_manifest_stream
 from synodic_client.operations.schema import (
-    PreviewActionChecked,
+    PreviewEvent,
     PreviewManifestParsed,
-    PreviewPluginsQueried,
-    PreviewReady,
 )
 
 logger = logging.getLogger(__name__)
@@ -58,16 +53,21 @@ async def run_install(
 ) -> SetupResults:
     """Execute setup actions via the operations layer and stream progress.
 
-    Delegates to :func:`~synodic_client.operations.install.execute_install`
-    and routes the tagged ``(stage, event)`` stream to GUI callbacks.
+    Delegates to :func:`~synodic_client.operations.install.collect_install`
+    and routes progress events to GUI callbacks.
     """
     cfg = config or InstallConfig()
     cb = callbacks or InstallCallbacks()
-    actions: list[SetupAction] = []
-    collected: list[SetupActionResult] = []
-    manifest_result: SetupResults | None = None
 
-    async for stage, event in execute_install(
+    def _on_progress(stage: str, event: object) -> None:
+        if stage == 'action_started' and isinstance(event, ActionStartedEvent) and cb.on_action_started is not None:
+            cb.on_action_started(event.action)
+        elif stage == 'sub_progress' and isinstance(event, SubActionProgressEvent) and cb.on_sub_progress is not None:
+            cb.on_sub_progress(event.action, event.sub_action)
+        elif stage == 'action_completed' and isinstance(event, ActionCompletedEvent) and cb.on_progress is not None:
+            cb.on_progress(event.action, event.result)
+
+    return await collect_install(
         porringer,
         manifest_path,
         project_directory=cfg.project_directory,
@@ -75,27 +75,7 @@ async def run_install(
         prerelease_packages=cfg.prerelease_packages,
         discovered=plugins,
         exclude_post_sync=exclude_post_sync,
-    ):
-        if stage == 'manifest_loaded' and isinstance(event, ManifestLoadedEvent):
-            manifest_result = event.manifest
-            actions = list(event.manifest.actions)
-
-        elif stage == 'action_started' and isinstance(event, ActionStartedEvent) and cb.on_action_started is not None:
-            cb.on_action_started(event.action)
-
-        elif stage == 'sub_progress' and isinstance(event, SubActionProgressEvent) and cb.on_sub_progress is not None:
-            cb.on_sub_progress(event.action, event.sub_action)
-
-        elif stage == 'action_completed' and isinstance(event, ActionCompletedEvent):
-            collected.append(event.result)
-            if cb.on_progress is not None:
-                cb.on_progress(event.action, event.result)
-
-    return SetupResults(
-        actions=actions,
-        results=collected,
-        manifest_path=manifest_result.manifest_path if manifest_result else None,
-        metadata=manifest_result.metadata if manifest_result else None,
+        on_progress=_on_progress,
     )
 
 
@@ -114,40 +94,25 @@ async def run_post_sync(
 ) -> SetupResults:
     """Execute only the post-sync commands from a manifest.
 
-    Delegates to :func:`~synodic_client.operations.install.execute_post_sync`
-    and routes events to GUI callbacks.
+    Delegates to :func:`~synodic_client.operations.install.collect_post_sync`
+    and routes progress events to GUI callbacks.
     """
     cb = callbacks or InstallCallbacks()
-    actions: list[SetupAction] = []
-    collected: list[SetupActionResult] = []
-    manifest_result: SetupResults | None = None
-
-    async for stage, event in execute_post_sync(
-        porringer,
-        manifest_path,
-        project_directory=project_directory,
-        discovered=plugins,
-    ):
-        if stage == 'manifest_loaded' and isinstance(event, ManifestLoadedEvent):
-            manifest_result = event.manifest
-            actions = list(event.manifest.actions)
 
-        elif stage == 'action_started' and isinstance(event, ActionStartedEvent) and cb.on_action_started is not None:
+    def _on_progress(stage: str, event: object) -> None:
+        if stage == 'action_started' and isinstance(event, ActionStartedEvent) and cb.on_action_started is not None:
             cb.on_action_started(event.action)
-
         elif stage == 'sub_progress' and isinstance(event, SubActionProgressEvent) and cb.on_sub_progress is not None:
             cb.on_sub_progress(event.action, event.sub_action)
+        elif stage == 'action_completed' and isinstance(event, ActionCompletedEvent) and cb.on_progress is not None:
+            cb.on_progress(event.action, event.result)
 
-        elif stage == 'action_completed' and isinstance(event, ActionCompletedEvent):
-            collected.append(event.result)
-            if cb.on_progress is not None:
-                cb.on_progress(event.action, event.result)
-
-    return SetupResults(
-        actions=actions,
-        results=collected,
-        manifest_path=manifest_result.manifest_path if manifest_result else None,
-        metadata=manifest_result.metadata if manifest_result else None,
+    return await collect_post_sync(
+        porringer,
+        manifest_path,
+        project_directory=project_directory,
+        discovered=plugins,
+        on_progress=_on_progress,
     )
 
 
@@ -161,17 +126,15 @@ async def run_preview(
     url: str,
     *,
     config: PreviewConfig | None = None,
-    callbacks: PreviewCallbacks | None = None,
+    on_event: Callable[[PreviewEvent], object] | None = None,
     plugins: DiscoveredPlugins | None = None,
 ) -> None:
     """Download a manifest and perform a dry-run preview.
 
     Delegates to :func:`preview_manifest_stream` in the operations
-    layer, then routes each :data:`PreviewEvent` to the appropriate
-    callback.
+    layer, then yields each :data:`PreviewEvent` to *on_event*.
     """
     logger.info('run_preview starting for: %s', url)
-    cb = callbacks or PreviewCallbacks()
     cfg = config or PreviewConfig()
     temp_dir: str | None = None
     try:
@@ -184,18 +147,9 @@ async def run_preview(
         ):
             if isinstance(event, PreviewManifestParsed):
                 temp_dir = event.temp_dir or None
-                if cb.on_manifest_parsed is not None:
-                    cb.on_manifest_parsed(event.manifest, event.manifest_path, event.temp_dir)
-
-            elif isinstance(event, PreviewPluginsQueried) and cb.on_plugins_queried is not None:
-                cb.on_plugins_queried(event.availability, event.capabilities)
-
-            elif isinstance(event, PreviewReady):
-                if cb.on_preview_ready is not None:
-                    cb.on_preview_ready(event.manifest, event.manifest_path, event.temp_dir)
 
-            elif isinstance(event, PreviewActionChecked) and cb.on_action_checked is not None:
-                cb.on_action_checked(event.index, event.result, event.status)
+            if on_event is not None:
+                on_event(event)
 
     except asyncio.CancelledError:
         if temp_dir:

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/synodic_client/application/screen/plugin_row.py

@@ -7,6 +7,8 @@ package rows, project child rows, and filter chips.
 
 from __future__ import annotations
 
+from enum import Enum
+
 from porringer.schema import PluginInfo
 from porringer.schema.plugin import PluginCapability, PluginKind
 from PySide6.QtCore import Qt, QTimer, Signal
@@ -40,6 +42,7 @@ from synodic_client.application.theme import (
     PLUGIN_ROW_PROJECT_TAG_TRANSITIVE_STYLE,
     PLUGIN_ROW_REMOVE_STYLE,
     PLUGIN_ROW_STATUS_MIN_WIDTH,
+    PLUGIN_ROW_STATUS_PENDING_STYLE,
     PLUGIN_ROW_STATUS_STYLE,
     PLUGIN_ROW_STYLE,
     PLUGIN_ROW_TIMESTAMP_MIN_WIDTH,
@@ -59,6 +62,16 @@ from synodic_client.application.theme import (
     PROJECT_CHILD_VERSION_STYLE,
 )
 
+
+class RowPhase(Enum):
+    """Mutually exclusive visual state for a :class:`PluginRow`."""
+
+    IDLE = 'idle'
+    CHECKING = 'checking'
+    PENDING = 'pending'
+    UPDATING = 'updating'
+
+
 # Row-spinner dimensions
 _ROW_SPINNER_SIZE = 12
 _ROW_SPINNER_PEN = 2
@@ -249,15 +262,18 @@ class PluginProviderHeader(QFrame):
             update_btn.setToolTip('Not installed \u2014 cannot update')
 
     def set_updating(self, updating: bool) -> None:
-        """Toggle the button between *Updating…* and *Update* states."""
-        if self._update_btn is None:
-            return
+        """Toggle between *Updating…* (with spinner) and *Update* states."""
         if updating:
-            self._update_btn.setText('Updating\u2026')
-            self._update_btn.setEnabled(False)
+            if self._checking_spinner is not None:
+                self._checking_spinner.start()
+            if self._update_btn is not None:
+                self._update_btn.hide()
         else:
-            self._update_btn.setText('Update')
-            self._update_btn.setEnabled(True)
+            if self._checking_spinner is not None:
+                self._checking_spinner.stop()
+            if self._update_btn is not None:
+                self._update_btn.setText('Update')
+                self._update_btn.setEnabled(True)
 
     def set_checking(self, checking: bool) -> None:
         """Show or hide the inline checking spinner."""
@@ -331,7 +347,7 @@ class PluginRow(QFrame):
         self._signal_key = f'{data.plugin_name}:{data.runtime_tag}' if data.runtime_tag else data.plugin_name
         self._update_btn: QPushButton | None = None
         self._remove_btn: QPushButton | None = None
-        self._checking_spinner: _RowSpinner | None = None
+        self._row_spinner: _RowSpinner | None = None
         self._host_label: QLabel | None = None
         self._project_paths: list[str] = list(data.project_paths)
         self._project_labels: list[str] = [p.project_label for p in data.project_instances]
@@ -386,6 +402,11 @@ class PluginRow(QFrame):
         if data.show_toggle:
             self._build_toggle(layout, data)
 
+        # Inline spinner — always created so checking, pending, and
+        # updating flows can use it regardless of whether the toggle is shown.
+        self._row_spinner = _RowSpinner(self)
+        layout.addWidget(self._row_spinner)
+
         # Update button — always created for alignment, hidden when no update
         self._build_update_button(layout, data)
 
@@ -421,7 +442,7 @@ class PluginRow(QFrame):
         self._build_remove_button(layout, data)
 
     def _build_toggle(self, layout: QHBoxLayout, data: PluginRowData) -> None:
-        """Add the auto-update toggle and inline checking spinner."""
+        """Add the auto-update toggle button."""
         toggle_btn = QPushButton('Auto')
         toggle_btn.setCheckable(True)
         toggle_btn.setChecked(data.auto_update)
@@ -436,9 +457,6 @@ class PluginRow(QFrame):
         )
         layout.addWidget(toggle_btn)
 
-        self._checking_spinner = _RowSpinner(self)
-        layout.addWidget(self._checking_spinner)
-
     def _build_update_button(self, layout: QHBoxLayout, data: PluginRowData) -> None:
         """Add the per-package update button (always created, visibility toggled)."""
         update_btn = QPushButton('Update')
@@ -483,27 +501,65 @@ class PluginRow(QFrame):
         self._remove_btn = remove_btn
         layout.addWidget(remove_btn)
 
-    def set_updating(self, updating: bool) -> None:
-        """Toggle the button between *Updating…* and *Update* states."""
-        if self._update_btn is None:
-            return
-        if updating:
-            self._update_btn.setText('Updating\u2026')
-            self._update_btn.setEnabled(False)
+    def set_phase(self, phase: RowPhase) -> None:
+        """Transition the row to a mutually exclusive visual *phase*.
+
+        * ``IDLE`` — spinner stopped, status hidden, button restored.
+        * ``CHECKING`` — spinner running, button hidden.
+        * ``PENDING`` — spinner stopped, *Pending* text shown, button hidden.
+        * ``UPDATING`` — spinner running, status hidden, button hidden.
+        """
+        self._apply_phase_reset()
+
+        if phase == RowPhase.IDLE:
+            self._apply_phase_idle()
+        elif phase == RowPhase.PENDING:
+            self._apply_phase_pending()
         else:
+            # CHECKING and UPDATING both start spinner and hide update btn
+            self._apply_phase_spinner()
+
+    def _apply_phase_reset(self) -> None:
+        """Stop spinner and hide status — common entry for every transition."""
+        if self._row_spinner is not None:
+            self._row_spinner.stop()
+        if self._update_status_label is not None:
+            self._update_status_label.hide()
+
+    def _apply_phase_idle(self) -> None:
+        """Restore the update button to its default label and state."""
+        if self._update_btn is not None:
             self._update_btn.setText('Update')
             self._update_btn.setEnabled(True)
 
+    def _apply_phase_pending(self) -> None:
+        """Show *Pending* text and hide the update button."""
+        if self._update_status_label is not None:
+            self._update_status_label.setText('Pending')
+            self._update_status_label.setStyleSheet(PLUGIN_ROW_STATUS_PENDING_STYLE)
+            self._update_status_label.show()
+        if self._update_btn is not None:
+            self._update_btn.hide()
+
+    def _apply_phase_spinner(self) -> None:
+        """Start the spinner and hide the update button."""
+        if self._row_spinner is not None:
+            self._row_spinner.start()
+        if self._update_btn is not None:
+            self._update_btn.hide()
+
+    # Convenience aliases for backward-compatible call sites
+    def set_updating(self, updating: bool) -> None:
+        """Toggle between updating and idle states."""
+        self.set_phase(RowPhase.UPDATING if updating else RowPhase.IDLE)
+
     def set_checking(self, checking: bool) -> None:
-        """Show or hide the inline checking spinner."""
-        if self._checking_spinner is None:
-            return
-        if checking:
-            self._checking_spinner.start()
-            if self._update_btn is not None:
-                self._update_btn.hide()
-        else:
-            self._checking_spinner.stop()
+        """Toggle between checking and idle states."""
+        self.set_phase(RowPhase.CHECKING if checking else RowPhase.IDLE)
+
+    def set_pending(self, pending: bool) -> None:
+        """Toggle between pending and idle states."""
+        self.set_phase(RowPhase.PENDING if pending else RowPhase.IDLE)
 
     def set_removing(self, removing: bool) -> None:
         """Toggle the remove button between *Removing…* and *×* states."""

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/synodic_client/application/screen/projects.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING
 
 from porringer.api import API
 from porringer.backend.command.core.discovery import DiscoveredPlugins
+from porringer.schema import DirectoryValidationResult, ManifestDirectory
 from PySide6.QtCore import Qt, Signal
 from PySide6.QtWidgets import (
     QFileDialog,
@@ -138,15 +139,11 @@ class ProjectsView(QWidget):
                 # Convert ProjectInfo list to the same shape as validated_directories
                 results = []
                 for p in projects:
-                    result = type(
-                        '_Result',
-                        (),
-                        {
-                            'directory': type('_Dir', (), {'path': p.path, 'name': p.name})(),
-                            'exists': p.exists,
-                            'has_manifest': p.has_manifest,
-                        },
-                    )()
+                    result = DirectoryValidationResult(
+                        directory=ManifestDirectory(path=Path(p.path), name=p.name),
+                        exists=p.exists,
+                        has_manifest=p.has_manifest,
+                    )
                     results.append(result)
                 discovered = None
 
@@ -154,7 +151,7 @@ class ProjectsView(QWidget):
             current_paths: set[Path] = set()
             for result in results:
                 d = result.directory
-                valid = bool(result.exists and result.has_manifest is not False)
+                valid = bool(result.exists and result.has_manifest)
                 path = Path(d.path)
                 directories.append((path, d.name or '', valid))
                 current_paths.add(path)

{synodic_client-0.0.1.dev77 → synodic_client-0.0.1.dev78}/synodic_client/application/screen/schema.py

@@ -238,8 +238,6 @@ class PreviewModel:
 
     def __init__(self) -> None:
         """Initialise a blank preview model."""
-        self._normalize = normalize_manifest_key
-
         self.phase: PreviewPhase = PreviewPhase.IDLE
         self.preview: SetupResults | None = None
         self.manifest_path: Path | None = None
@@ -295,7 +293,7 @@ class PreviewModel:
 
     def has_same_manifest(self, key: str) -> bool:
         """Return ``True`` if *key* matches the current manifest key."""
-        return self.manifest_key is not None and self.manifest_key == self._normalize(key)
+        return self.manifest_key is not None and self.manifest_key == normalize_manifest_key(key)
 
 
 @dataclass(frozen=True, slots=True)
@@ -322,25 +320,29 @@ class InstallCallbacks:
 
 
 @dataclass(frozen=True, slots=True)
-class PreviewCallbacks:
-    """Callbacks for :func:`run_preview` progress reporting."""
+class PreviewConfig:
+    """Optional execution parameters for :func:`run_preview`."""
 
-    on_manifest_parsed: Callable[[SetupResults, str, str], None] | None = None
-    """``(SetupResults, manifest_path, temp_dir)`` — after JSON load."""
+    project_directory: Path | None = None
+    prerelease_packages: set[str] | None = None
 
-    on_plugins_queried: Callable[[dict[str, bool], dict[str, frozenset[PluginCapability]]], None] | None = None
-    """``(dict[str, bool], dict[str, frozenset[PluginCapability]])`` — plugin → installed + capabilities mappings."""
 
-    on_preview_ready: Callable[[SetupResults, str, str], None] | None = None
-    """``(SetupResults, manifest_path, temp_dir)`` — CLI commands resolved."""
+@dataclass(frozen=True, slots=True)
+class UpdateTarget:
+    """Identifies the scope of a manual tool update.
 
-    on_action_checked: Callable[[int, SetupActionResult, str], None] | None = None
-    """``(row_index, SetupActionResult, status)`` — per-action dry-run result with resolved status."""
+    Passed to the shared completion handler so it can clear the correct
+    updating state and derive timestamp keys.  ``None`` (the default in
+    the handler) means the update was periodic / automatic.
 
+    When *package* is empty the update targeted an entire plugin;
+    otherwise it targeted one specific package within the plugin.
+    *plugin* always carries the signal key (possibly composite
+    ``"plugin:tag"``).
+    """
 
-@dataclass(frozen=True, slots=True)
-class PreviewConfig:
-    """Optional execution parameters for :func:`run_preview`."""
+    plugin: str
+    """Signal key for the plugin (may be composite ``"name:tag"``)."""
 
-    project_directory: Path | None = None
-    prerelease_packages: set[str] | None = None
+    package: str = ''
+    """Package name, or empty when the whole plugin was updated."""