karcytics-sdk 2.1.8__tar.gz → 2.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. {karcytics_sdk-2.1.8/src/karcytics_sdk.egg-info → karcytics_sdk-2.2.0}/PKG-INFO +1 -1
  2. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/pyproject.toml +1 -1
  3. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/module_status_widget.py +28 -0
  4. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/__init__.py +3 -0
  5. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/academy.py +29 -1
  6. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/academy_driver.py +95 -6
  7. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/autosave.py +8 -0
  8. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/base.py +138 -85
  9. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/components.py +49 -0
  10. karcytics_sdk-2.2.0/src/karcytics_sdk/plugin/history.py +220 -0
  11. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/menu_builder.py +11 -3
  12. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/ribbon.py +24 -1
  13. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/signals.py +3 -0
  14. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/state.py +1 -1
  15. karcytics_sdk-2.2.0/src/karcytics_sdk/plugin/toast.py +375 -0
  16. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/tutorial_overlay.py +207 -26
  17. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/ui_daemon_runtime.py +114 -0
  18. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/ui_preferences.py +14 -0
  19. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0/src/karcytics_sdk.egg-info}/PKG-INFO +1 -1
  20. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk.egg-info/SOURCES.txt +1 -0
  21. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_plugin_state.py +46 -29
  22. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_plugin_ui.py +6 -19
  23. karcytics_sdk-2.1.8/src/karcytics_sdk/plugin/toast.py +0 -204
  24. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/LICENSE +0 -0
  25. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/README.md +0 -0
  26. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/setup.cfg +0 -0
  27. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/__init__.py +0 -0
  28. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/cli/__init__.py +0 -0
  29. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/cli/commands/__init__.py +0 -0
  30. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/cli/commands/diagnostics.py +0 -0
  31. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/cli/commands/migrate.py +0 -0
  32. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/cli/commands/scaffold.py +0 -0
  33. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/cli/commands/security.py +0 -0
  34. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/cli/main.py +0 -0
  35. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/contrib/__init__.py +0 -0
  36. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/contrib/image_utils.py +0 -0
  37. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/__init__.py +0 -0
  38. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/ai.py +0 -0
  39. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/core_services.py +0 -0
  40. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/docs.py +0 -0
  41. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/marketplace_cache.py +0 -0
  42. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/qt_bridge.py +0 -0
  43. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/sign_plugin.py +0 -0
  44. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/trust_manager.py +0 -0
  45. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/trust_overrides.py +0 -0
  46. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/trust_path.py +0 -0
  47. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/host/trust_storage.py +0 -0
  48. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/interfaces/__init__.py +0 -0
  49. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/interfaces/i_crash_reporter.py +0 -0
  50. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/interfaces/i_event_bus.py +0 -0
  51. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/interfaces/i_logger.py +0 -0
  52. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/interfaces/i_task_scheduler.py +0 -0
  53. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/academy_window.py +0 -0
  54. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/analysis.py +0 -0
  55. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/context.py +0 -0
  56. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/course_complete_overlay.py +0 -0
  57. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/cyto_character.py +0 -0
  58. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/cyto_costumes.py +0 -0
  59. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/daemon.py +0 -0
  60. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/dialogs.py +0 -0
  61. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/draggable.py +0 -0
  62. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/effects.py +0 -0
  63. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/events.py +0 -0
  64. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/galactic_loader.py +0 -0
  65. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/galactic_loader.qml +0 -0
  66. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/interfaces.py +0 -0
  67. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/io.py +0 -0
  68. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/logging.py +0 -0
  69. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/managed_task.py +0 -0
  70. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/manifest.py +0 -0
  71. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/manifest_parser.py +0 -0
  72. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/preferences.py +0 -0
  73. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/rendering/__init__.py +0 -0
  74. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/rendering/graphics_scene.py +0 -0
  75. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/rendering/lock.py +0 -0
  76. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/rendering/mpl_canvas.py +0 -0
  77. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/rendering/pipeline.py +0 -0
  78. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/runtime_services.py +0 -0
  79. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/security_parser.py +0 -0
  80. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/theme_fallback.py +0 -0
  81. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/tutorial_models.py +0 -0
  82. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/update_check.py +0 -0
  83. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/validation.py +0 -0
  84. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/wizard.py +0 -0
  85. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/worker_thread.py +0 -0
  86. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/plugin/workflow.py +0 -0
  87. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/py.typed +0 -0
  88. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/sdk_cli.py +0 -0
  89. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/testing/__init__.py +0 -0
  90. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk/testing/contract.py +0 -0
  91. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk.egg-info/dependency_links.txt +0 -0
  92. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk.egg-info/entry_points.txt +0 -0
  93. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk.egg-info/requires.txt +0 -0
  94. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/src/karcytics_sdk.egg-info/top_level.txt +0 -0
  95. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_host_ai.py +0 -0
  96. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_host_security.py +0 -0
  97. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_image_utils.py +0 -0
  98. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_marketplace_cache.py +0 -0
  99. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_namespaces.py +0 -0
  100. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_plugin_architecture.py +0 -0
  101. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_plugin_ribbon.py +0 -0
  102. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_sdk_cli.py +0 -0
  103. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_sign_plugin.py +0 -0
  104. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_testing_contract.py +0 -0
  105. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_theme_fallback.py +0 -0
  106. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_ui_daemon_runtime.py +0 -0
  107. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_workflow_context.py +0 -0
  108. {karcytics_sdk-2.1.8 → karcytics_sdk-2.2.0}/tests/test_workflow_dialogs.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: karcytics-sdk
3
- Version: 2.1.8
3
+ Version: 2.2.0
4
4
  Summary: Software Development Kit and CLI for Karcytics.
5
5
  Author: Kalaimaran Balasothy
6
6
  License: # PolyForm Noncommercial License 1.0.0
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "karcytics-sdk"
7
- version = "2.1.8"
7
+ version = "2.2.0"
8
8
  description = "Software Development Kit and CLI for Karcytics."
9
9
  readme = "README.md"
10
10
  license = { file = "LICENSE" }
@@ -215,9 +215,35 @@ class ModuleStatusWidget(QWidget):
215
215
  self._action_button = QPushButton()
216
216
  self._action_button.clicked.connect(self._on_action_clicked)
217
217
 
218
+ # Secondary action shown only in the Crashed state — lets the user
219
+ # dismiss the overlay and return to the project view without
220
+ # reopening the module. Reuses cancel() which already transitions
221
+ # the widget to STATE_CLOSED; the host's state_changed handler
222
+ # (plugin_loader._on_overlay_state_changed) hides this overlay on
223
+ # STATE_CLOSED, so no extra wiring is needed here.
224
+ self._return_button = QPushButton("Return to Project View")
225
+ self._return_button.setVisible(False)
226
+ self._return_button.clicked.connect(self.cancel)
227
+ self._return_button.setStyleSheet(
228
+ "QPushButton {"
229
+ " color: rgba(200, 200, 210, 0.75);"
230
+ " background: transparent;"
231
+ " border: 1px solid rgba(255, 255, 255, 30);"
232
+ " border-radius: 6px;"
233
+ " padding: 5px 16px;"
234
+ " font-size: 12px;"
235
+ "}"
236
+ "QPushButton:hover {"
237
+ " color: #f2f2f2;"
238
+ " border-color: rgba(255, 255, 255, 70);"
239
+ " background: rgba(255, 255, 255, 8);"
240
+ "}"
241
+ )
242
+
218
243
  card_layout.addWidget(self._status_label)
219
244
  card_layout.addWidget(self._progress_bar, alignment=Qt.AlignmentFlag.AlignHCenter)
220
245
  card_layout.addWidget(self._action_button, alignment=Qt.AlignmentFlag.AlignHCenter)
246
+ card_layout.addWidget(self._return_button, alignment=Qt.AlignmentFlag.AlignHCenter)
221
247
 
222
248
  outer.addWidget(card)
223
249
 
@@ -255,6 +281,8 @@ class ModuleStatusWidget(QWidget):
255
281
  self._progress_bar.show()
256
282
  else:
257
283
  self._progress_bar.hide()
284
+ # Show the "Return" escape hatch only when the module has crashed.
285
+ self._return_button.setVisible(self._state == self.STATE_CRASHED)
258
286
 
259
287
  def _set_state(self, state: str, error_message: str | None = None) -> None:
260
288
  self._state = state
@@ -49,6 +49,7 @@ from .dialogs import (
49
49
  show_warning,
50
50
  )
51
51
  from .events import CentralEventBus
52
+ from .history import HistoryEntry, UndoHistory
52
53
  from .interfaces import KarcyticsPlugin
53
54
  from .io import PluginConfig, PluginPreferenceManager, load_json, save_json
54
55
  from .logging import get_logger
@@ -141,6 +142,8 @@ __all__ = [
141
142
  "CytoWidget",
142
143
  "CourseCompleteOverlay",
143
144
  "CentralEventBus",
145
+ "HistoryEntry",
146
+ "UndoHistory",
144
147
  "PreferenceManagerProtocol",
145
148
  # Toasts
146
149
  "STYLE_ERROR",
@@ -210,9 +210,20 @@ class AcademyManager:
210
210
  self._cancel_wait_subscription()
211
211
 
212
212
  next_id = specific_step_id or self.current_step.next_step_id
213
+ self._advance_to(next_id)
214
+
215
+ def _advance_to(self, next_id: str | None) -> None:
216
+ """Resolves `next_id` per its three special forms — a real step id,
217
+ `"__abandon__"`, or falsy/`"__complete__"` — and applies it. Split
218
+ out of `next_step()` to keep that method's own branching (the
219
+ guard clauses above) under the complexity limit.
220
+ """
221
+ if next_id == "__abandon__":
222
+ self.abandon_course()
223
+ return
213
224
 
214
225
  if next_id and next_id != "__complete__":
215
- self.current_step = self.active_course.get_step(next_id)
226
+ self.current_step = self.active_course.get_step(next_id) if self.active_course else None
216
227
  if self.current_step:
217
228
  # Reset subtask progress for the new step
218
229
  if isinstance(self.current_step, ForcedInteractionStep):
@@ -290,6 +301,23 @@ class AcademyManager:
290
301
 
291
302
  self._event_bus.emit(ACADEMY_COURSE_COMPLETED, course_id, self.active_course.badge_reward)
292
303
 
304
+ def abandon_course(self) -> None:
305
+ """Leaves the active course without marking it complete or awarding
306
+ a badge — the `next_step_id="__abandon__"` counterpart to
307
+ `complete_course()`'s `"__complete__"`/`None` sentinel, for a step
308
+ that has nowhere useful to send the user (e.g. a "you haven't
309
+ finished the prerequisite course yet" screen). Progress is not
310
+ saved, matching `build_academy_overlay`'s close-button handler
311
+ (`_on_skip`) in `academy_driver.py`, which this mirrors exactly —
312
+ so relaunching the course later starts over from the beginning.
313
+ """
314
+ if self.is_reviewing:
315
+ return
316
+ self._cancel_wait_subscription()
317
+ self.active_course = None
318
+ self.current_step = None
319
+ self._emit_step_changed()
320
+
293
321
  def reset_course(self, course_id: str) -> None:
294
322
  """Clears progress for a specific course, allowing the user to start over."""
295
323
  modified = False
@@ -21,7 +21,7 @@ from collections.abc import Callable
21
21
  from typing import Any
22
22
 
23
23
  from PyQt6.QtCore import QObject, QRect, QTimer
24
- from PyQt6.QtWidgets import QScrollArea, QWidget
24
+ from PyQt6.QtWidgets import QApplication, QScrollArea, QWidget
25
25
 
26
26
  from .academy import AcademyManager
27
27
  from .tutorial_models import (
@@ -85,6 +85,7 @@ class AcademyStepDriver(QObject):
85
85
  self._stuck_hint_shown = False
86
86
  self._failure_hint_shown = False
87
87
  self._was_reviewing = False
88
+ self._last_canvas_guide_active = False
88
89
 
89
90
  self._timer = QTimer(self)
90
91
  self._timer.timeout.connect(self._tick)
@@ -105,12 +106,32 @@ class AcademyStepDriver(QObject):
105
106
  if self._handle_reviewing_state(step):
106
107
  return
107
108
 
108
- if step.id != self._last_step_id:
109
+ is_new_step = step.id != self._last_step_id
110
+ if is_new_step:
111
+ # Reset before _update_targets() below, not after — see that
112
+ # call's own comment for why the ordering here matters.
113
+ self._overlay._user_positioned = False # noqa: SLF001
114
+
115
+ # Resolved once per tick, before render_step() (if this is a step
116
+ # change) rather than after: render_step() unconditionally ends
117
+ # with its own _update_mask()/_reposition_cyto_and_bubble() call
118
+ # using whatever self._overlay.target_rects currently holds — if
119
+ # that still held the *previous* step's rects because this call
120
+ # instead ran afterward, every single step transition produced a
121
+ # real, visible one-tick flash: the spotlight/Cyto briefly wrong
122
+ # (still the old step's target), immediately followed by the
123
+ # correct one — the "half spotlighted scenes for half seconds" and
124
+ # jump/freeze feeling reported from live use. This used to run
125
+ # last in _tick() instead; moving it here (rather than calling it
126
+ # twice — once early, once in its old spot) fixes the flash without
127
+ # doubling the findChildren() work every transition already does.
128
+ self._update_targets(step)
129
+
130
+ if is_new_step:
109
131
  self._handle_step_changed(step)
110
132
 
111
133
  self._dispatch_step_updates(step)
112
134
  self._maybe_show_stuck_hint(step)
113
- self._update_targets(step)
114
135
 
115
136
  def _handle_no_active_step(self, step: Any | None) -> bool:
116
137
  """Hides the overlay and clears the canvas guide if there's nothing to show.
@@ -208,6 +229,22 @@ class AcademyStepDriver(QObject):
208
229
  if step.text != self._last_rendered_text:
209
230
  self._last_rendered_text = step.text
210
231
  self._overlay._update_text_rendering(step.text) # noqa: SLF001
232
+ # _update_text_rendering() only swaps the label's HTML — it
233
+ # doesn't resize the bubble to fit it. render_step() (a real
234
+ # step change) always follows its own text update with
235
+ # _force_resize()/_update_mask(), but this in-place edit runs
236
+ # instead of render_step(), so without the same follow-up here
237
+ # the bubble stays sized for whatever shorter placeholder text
238
+ # (e.g. "Scanning your run's real numbers...") it started with —
239
+ # reported live as the real, dynamically-computed text (e.g.
240
+ # naming the actual winning cluster ID) getting cut off mid
241
+ # sentence once a validator rewrites its own step's text.
242
+ self._overlay._force_resize() # noqa: SLF001
243
+ if not self._overlay._user_positioned: # noqa: SLF001
244
+ self._overlay._reposition_cyto_and_bubble( # noqa: SLF001
245
+ getattr(self._overlay, "target_rects", [])
246
+ )
247
+ self._overlay._update_mask() # noqa: SLF001
211
248
  self._verification_wait += 1
212
249
  if self._verification_wait > _VALIDATION_POLL_TICKS:
213
250
  self._verification_wait = 0
@@ -248,11 +285,36 @@ class AcademyStepDriver(QObject):
248
285
  tutorial's on-canvas polygon/rect/range/quadrant guide from ever
249
286
  appearing again — no exception, the call to draw it just never
250
287
  happened.
288
+
289
+ Skips the `findChildren`/`set_tutorial_guide` work entirely when
290
+ this step has no guide to draw AND the previous step didn't leave
291
+ one on screen to clear — `set_tutorial_guide()` always ends in a
292
+ full canvas redraw (`draw_idle()`), and the vast majority of steps
293
+ in any course never touch the canvas guide at all. Without this,
294
+ every single step transition paid that redraw regardless of
295
+ relevance — cheap early on when the canvas is empty, but a real,
296
+ visible stall once real gated data/overlays make that redraw
297
+ expensive (reported live: Course 2 feeling freezy between steps
298
+ where Course 1's identical transitions didn't).
251
299
  """
300
+ has_guide = self._step_has_canvas_guide(step)
301
+ if not has_guide and not self._last_canvas_guide_active:
302
+ return
303
+ self._last_canvas_guide_active = has_guide
304
+
252
305
  for canvas in self._search_root.findChildren(QWidget, "FlowCanvas"):
253
306
  if hasattr(canvas, "set_tutorial_guide"):
254
307
  canvas.set_tutorial_guide(step)
255
308
 
309
+ @staticmethod
310
+ def _step_has_canvas_guide(step: Any | None) -> bool:
311
+ if step is None:
312
+ return False
313
+ if getattr(step, "guide_poly", None):
314
+ return True
315
+ metadata = getattr(step, "metadata", None) or {}
316
+ return any(metadata.get(key) for key in ("guide_data_poly", "guide_rect", "guide_range", "guide_quadrant"))
317
+
256
318
  def _wire_interaction_step(self, step: InteractionStep) -> None:
257
319
  # findChildren() only searches descendants, never search_root
258
320
  # itself — but for an isolated plugin, search_root IS "its own
@@ -393,9 +455,12 @@ class AcademyStepDriver(QObject):
393
455
  if by_name:
394
456
  targets.extend(by_name)
395
457
  else:
396
- for w in self._search_root.findChildren(QWidget):
397
- if w.property("tutorial_id") == name and w.isVisible():
398
- targets.append(w)
458
+ by_id = [
459
+ w
460
+ for w in self._search_root.findChildren(QWidget)
461
+ if w.property("tutorial_id") == name and w.isVisible()
462
+ ]
463
+ targets.extend(by_id or self._find_in_other_windows(name))
399
464
  else:
400
465
  name = getattr(step, "target_widget_name", "")
401
466
  if name:
@@ -423,6 +488,30 @@ class AcademyStepDriver(QObject):
423
488
  scroll_target = scroll_area.viewport()
424
489
  self._overlay.set_scroll_target(scroll_target)
425
490
 
491
+ def _find_in_other_windows(self, name: str) -> list[QWidget]:
492
+ """Visible widgets named `name` in this process's *other* top-level
493
+ windows — e.g. the SDK Preferences dialog, a separate window parented
494
+ to the plugin's main window rather than living under `search_root`.
495
+
496
+ The overlay can't paint over another window, so such a target isn't
497
+ really spotlit — but mapping its rect in (via global coords, like any
498
+ other target) moves Cyto and the bubble out from behind it instead
499
+ of leaving them centred underneath where they can't be read. The
500
+ whole containing window is returned after the named widget(s) for
501
+ that reason: positioning only steers clear of target rects, so with
502
+ just (say) a nav list inside the dialog, Cyto would land right next
503
+ to it — still on top of the rest of the dialog.
504
+ """
505
+ own_window = self._search_root.window()
506
+ found: list[QWidget] = []
507
+ for top in QApplication.topLevelWidgets():
508
+ if top is own_window or not top.isVisible():
509
+ continue
510
+ matches = [w for w in top.findChildren(QWidget, name) if w.isVisible()]
511
+ if top.objectName() == name or matches:
512
+ found.extend([*matches, top])
513
+ return found
514
+
426
515
  def _collect_canvas_target_rects(self, step: Any) -> list[QRect]:
427
516
  """Duck-typed extension point, mirroring _apply_canvas_guide()'s
428
517
  FlowCanvas hook: a descendant that draws its own sub-elements inside
@@ -51,6 +51,9 @@ class WorkflowAutosaveController(QObject):
51
51
 
52
52
  Call `notify_saved()` after any *manual* save so the countdown restarts
53
53
  from that point instead of firing again moments later.
54
+
55
+ Given `has_unsaved_changes`, a tick where it returns False does nothing
56
+ at all — no redundant save, no "unsaved" reminder.
54
57
  """
55
58
 
56
59
  def __init__( # noqa: PLR0913 - a small DI-style constructor; each param is a distinct collaborator, not a group that bundles cleanly
@@ -62,11 +65,13 @@ class WorkflowAutosaveController(QObject):
62
65
  config: PreferenceManagerProtocol | None = None,
63
66
  interval_ms: int = DEFAULT_INTERVAL_MS,
64
67
  parent: QObject | None = None,
68
+ has_unsaved_changes: Callable[[], bool] | None = None,
65
69
  ) -> None:
66
70
  super().__init__(parent)
67
71
  self._plugin_id = plugin_id
68
72
  self._has_saved_once = has_saved_once
69
73
  self._save = save
74
+ self._has_unsaved_changes = has_unsaved_changes
70
75
  # Reuses the plugin's own PluginConfig instance for this plugin_id
71
76
  # (see PluginConfig.__new__) rather than risking a second, divergent
72
77
  # in-memory copy of the same JSON file.
@@ -104,6 +109,9 @@ class WorkflowAutosaveController(QObject):
104
109
  # ── Tick handling ───────────────────────────────────────────────
105
110
 
106
111
  def _on_tick(self) -> None:
112
+ # Nothing to save: neither re-write an identical file nor nag.
113
+ if self._has_unsaved_changes is not None and not self._has_unsaved_changes():
114
+ return
107
115
  if self.enabled and self._has_saved_once():
108
116
  try:
109
117
  self._save(self._on_autosave_result)
@@ -29,9 +29,10 @@ except ImportError:
29
29
 
30
30
  from .analysis import AnalysisBase, AnalysisRunnable, AnalysisWorker
31
31
  from .events import CentralEventBus
32
+ from .history import UndoHistory
32
33
  from .signals import PluginSignals
33
34
  from .state import PluginState
34
- from .toast import STYLE_SUCCESS, STYLE_UPDATE, show_toast
35
+ from .toast import STYLE_SUCCESS, STYLE_UPDATE, ToastManager
35
36
  from .worker_thread import OneShotWorkerThread
36
37
 
37
38
  if TYPE_CHECKING:
@@ -113,8 +114,8 @@ class PluginBase(QWidget):
113
114
 
114
115
  self.logger = get_logger(f"plugin.{plugin_id}", plugin_id)
115
116
 
116
- self._history = None
117
- self._current_state = None
117
+ self._undo_history: UndoHistory[Any] | None = None
118
+ self._undo_restore: Callable[[Any], None] | None = None
118
119
 
119
120
  # Isolated plugins have no automatic route back to the Hub's
120
121
  # diagnostics engine (in-process plugins get one for free via
@@ -129,44 +130,70 @@ class PluginBase(QWidget):
129
130
  # Connect to global theme engine
130
131
  theme_manager.theme_changed.connect(self._apply_theme_styles)
131
132
 
132
- @property
133
- def history(self):
134
- """Lazy-loaded HistoryManager to avoid circular dependencies."""
135
- if not hasattr(self, "_history") or self._history is None:
136
- try:
137
- from karcytics.core.history_manager import HistoryManager
138
-
139
- self._history = HistoryManager()
140
- except ImportError:
141
-
142
- class MockHistoryManager:
143
- def get_module_history(self, *args, **kwargs):
144
- class MockHistory:
145
- def push(self, *args):
146
- pass
147
-
148
- def undo(self):
149
- return None
150
-
151
- def redo(self):
152
- return None
153
-
154
- @property
155
- def undo_stack(self):
156
- return [1, 2]
133
+ # ── Toast anchoring & Ready Gate deferral ───────────────────────
134
+ # A private manager (not the shared module-level `toast_manager`)
135
+ # so this plugin's own toasts never mix into another window's
136
+ # stack, and so "bottom-left" only applies here rather than
137
+ # globally (the Hub's own SYSTEM_WARNING toasts stay bottom-right).
138
+ self._toast_manager = ToastManager(corner="bottom-left")
139
+
140
+ # A toast fired while the two-phase loading protocol's overlay
141
+ # (the Hub's crossfade loader, or an isolated module's
142
+ # GalacticLoader) is still covering this widget would show and
143
+ # fade out entirely underneath it — invisible for the whole time a
144
+ # workflow is loading, since that overlay paints above this panel
145
+ # regardless of the toast's own stacking order within it. Buffer
146
+ # any toast requested before the panel actually signals it's ready
147
+ # to be seen, and flush them once it does. Panels that don't
148
+ # implement the protocol at all have nothing masking them, so they
149
+ # get toasts immediately, same as before.
150
+ self._toast_gate_ready = not hasattr(self, "panel_ready")
151
+ self._pending_toasts: list[tuple[str, str, str, int]] = []
152
+ if hasattr(self, "data_ready"):
153
+ self.data_ready.connect(self._release_pending_toasts)
154
+ elif hasattr(self, "panel_ready"):
155
+ self.panel_ready.connect(self._release_pending_toasts)
157
156
 
158
- @property
159
- def redo_stack(self):
160
- return []
161
-
162
- return MockHistory()
163
-
164
- self._history = MockHistoryManager()
165
- return self._history
166
-
167
- @history.setter
168
- def history(self, value):
169
- self._history = value
157
+ @property
158
+ def undo_history(self) -> UndoHistory[Any]:
159
+ """This plugin's undo/redo history, created on first use.
160
+
161
+ Owned by the plugin's own process — never the Hub's `HistoryManager`,
162
+ which an isolated plugin can't import. By default each step is a
163
+ `get_state().to_dict()` snapshot restored through `set_state()`; a
164
+ plugin with its own state store swaps that out with
165
+ `bind_undo_history()`.
166
+ """
167
+ if self._undo_history is None:
168
+ self.bind_undo_history(UndoHistory(), self._restore_state_dict)
169
+ assert self._undo_history is not None
170
+ return self._undo_history
171
+
172
+ def bind_undo_history(self, history: UndoHistory[Any], restore: Callable[[Any], None]) -> None:
173
+ """Use `history` for undo/redo, restoring each snapshot via `restore(snapshot)`.
174
+
175
+ `restore` must bring the plugin's live state (and the UI showing it)
176
+ back to exactly what `snapshot` describes. Also re-emits
177
+ `undo_available`/`redo_available`/`undo_state_changed` whenever the
178
+ history changes, which is what keeps Edit → Undo/Redo in sync.
179
+ """
180
+ if self._undo_history is not None:
181
+ self._undo_history.remove_listener(self._on_undo_history_changed)
182
+ self._undo_history = history
183
+ self._undo_restore = restore
184
+ history.add_listener(self._on_undo_history_changed)
185
+ self._on_undo_history_changed()
186
+
187
+ def _on_undo_history_changed(self) -> None:
188
+ history = self._undo_history
189
+ if history is None:
190
+ return
191
+ self.signals.undo_available.emit(history.can_undo())
192
+ self.signals.redo_available.emit(history.can_redo())
193
+ self.signals.undo_state_changed.emit()
194
+
195
+ def _restore_state_dict(self, snapshot: dict[str, Any]) -> None:
196
+ self.set_state(self.get_state().__class__.from_dict(snapshot))
170
197
 
171
198
  def publish_event(self, topic: str, data: Any = None) -> None:
172
199
  """Publish an event to the Central Event Bus."""
@@ -210,52 +237,57 @@ class PluginBase(QWidget):
210
237
  """
211
238
  pass
212
239
 
213
- def push_state(self) -> None:
214
- """Save current state to undo history.
240
+ def push_state(self, label: str = "") -> None:
241
+ """Record the current state as one undoable step named `label`.
215
242
 
216
- Call this whenever the user makes a destructive edit (e.g., changing
217
- a parameter, drawing on an image). Karcytics will emit state_changed signal
218
- and automatically capture this state for undo/redo.
243
+ Call this after each completed user action (not on every intermediate
244
+ tick of a drag). The first call only sets the baseline.
219
245
  """
220
- state_dict = self.get_state().to_dict()
221
- self.history.get_module_history(self.plugin_id).push(state_dict)
246
+ self.undo_history.record(label, self.get_state().to_dict())
222
247
  self.state_changed.emit()
223
248
 
224
- def undo(self) -> None:
225
- """Undo to previous state."""
226
- history = self.history.get_module_history(self.plugin_id)
227
- prev_state_dict = history.undo()
228
- if prev_state_dict:
229
- state = self.get_state().__class__.from_dict(prev_state_dict)
230
- self.set_state(state)
231
- self.state_changed.emit()
232
-
233
- def redo(self) -> None:
234
- """Redo to next state."""
235
- history = self.history.get_module_history(self.plugin_id)
236
- next_state_dict = history.redo()
237
- if next_state_dict:
238
- state = self.get_state().__class__.from_dict(next_state_dict)
239
- self.set_state(state)
240
- self.state_changed.emit()
249
+ def undo(self) -> bool:
250
+ """Revert the most recent step. Returns True if a step was undone."""
251
+ return self._step(self.undo_history.undo, self.undo_history.redo)
241
252
 
242
- def can_undo(self) -> bool:
243
- """Check if undo is available.
253
+ def redo(self) -> bool:
254
+ """Re-apply the most recently undone step. Returns True if one was redone."""
255
+ return self._step(self.undo_history.redo, self.undo_history.undo)
244
256
 
245
- Returns:
246
- True if there are states to undo to
247
- """
248
- history = self.history.get_module_history(self.plugin_id)
249
- return len(history.undo_stack) > 1
257
+ def _step(self, move: Callable[[], Any], move_back: Callable[[], Any]) -> bool:
258
+ snapshot = move()
259
+ if snapshot is None:
260
+ return False
261
+ assert self._undo_restore is not None
262
+ try:
263
+ self._undo_restore(snapshot)
264
+ except Exception:
265
+ # Keep the history pointer matching the live state: a snapshot
266
+ # that couldn't be restored must not count as the current one.
267
+ move_back()
268
+ self.logger.exception("Failed to restore undo snapshot.")
269
+ self.status_message.emit("Undo/redo failed — see the log for details.")
270
+ return False
271
+ self.state_changed.emit()
272
+ return True
273
+
274
+ def can_undo(self) -> bool:
275
+ """Check if undo is available."""
276
+ return self.undo_history.can_undo()
250
277
 
251
278
  def can_redo(self) -> bool:
252
- """Check if redo is available.
279
+ """Check if redo is available."""
280
+ return self.undo_history.can_redo()
253
281
 
254
- Returns:
255
- True if there are states to redo to
256
- """
257
- history = self.history.get_module_history(self.plugin_id)
258
- return len(history.redo_stack) > 0
282
+ def undo_text(self) -> str:
283
+ """Menu text for Edit → Undo, e.g. "Undo Delete Gate"."""
284
+ label = self.undo_history.undo_label()
285
+ return f"Undo {label}" if label else "Undo"
286
+
287
+ def redo_text(self) -> str:
288
+ """Menu text for Edit → Redo, e.g. "Redo Delete Gate"."""
289
+ label = self.undo_history.redo_label()
290
+ return f"Redo {label}" if label else "Redo"
259
291
 
260
292
  # ── Resource Lifecycle (RAII) ────────────────────────────────────
261
293
 
@@ -382,14 +414,32 @@ class PluginBase(QWidget):
382
414
  color: str = "#5C9EE5",
383
415
  duration_ms: int = 4000,
384
416
  ) -> None:
385
- """Show a non-intrusive toast notification anchored to this plugin's window.
386
-
387
- Uses the same bottom-right, auto-fading popup the Hub uses for its
388
- own system warnings (see ``karcytics_sdk.plugin.toast``). Works
389
- identically whether this plugin runs in-process or isolated, since
390
- each owns its own ``QApplication``.
417
+ """Show a non-intrusive toast notification anchored to this plugin's own widget.
418
+
419
+ Uses the same auto-fading popup the Hub uses for its own system
420
+ warnings (see ``karcytics_sdk.plugin.toast``), pinned to the
421
+ bottom-left of *this widget* — not ``self.window()`` — so it tracks
422
+ the module's actual on-screen area (including its own resizes) even
423
+ when that's a panel embedded in the Hub's layout rather than the
424
+ Hub's whole window. Works identically whether this plugin runs
425
+ in-process or isolated, since each owns its own ``QApplication``.
426
+
427
+ If the panel implements the two-phase loading protocol
428
+ (``panel_ready``/``data_ready``) and hasn't signaled ready yet, the
429
+ toast is held until it does, rather than fading out unseen behind
430
+ the loading overlay.
391
431
  """
392
- show_toast(message, icon=icon, color=color, duration_ms=duration_ms)
432
+ if not self._toast_gate_ready:
433
+ self._pending_toasts.append((message, icon, color, duration_ms))
434
+ return
435
+ self._toast_manager.show(message, icon=icon, color=color, duration_ms=duration_ms, window=self)
436
+
437
+ def _release_pending_toasts(self) -> None:
438
+ """Flush any toasts buffered while the loading overlay was up (see `show_toast`)."""
439
+ self._toast_gate_ready = True
440
+ pending, self._pending_toasts = self._pending_toasts, []
441
+ for message, icon, color, duration_ms in pending:
442
+ self._toast_manager.show(message, icon=icon, color=color, duration_ms=duration_ms, window=self)
393
443
 
394
444
  # ── Workflow autosave ────────────────────────────────────────────────
395
445
 
@@ -399,6 +449,7 @@ class PluginBase(QWidget):
399
449
  save: Callable[[Callable[[bool], None]], None],
400
450
  *,
401
451
  interval_ms: int | None = None,
452
+ has_unsaved_changes: Callable[[], bool] | None = None,
402
453
  ) -> WorkflowAutosaveController:
403
454
  """Opt this plugin into the SDK's shared workflow-autosave loop.
404
455
 
@@ -407,7 +458,8 @@ class PluginBase(QWidget):
407
458
  applies after that — it's what gives a workflow a name). `save`
408
459
  should perform a *quiet* save (no blocking dialogs — the controller
409
460
  shows its own toast) and call the callback it's given with whether
410
- that save succeeded.
461
+ that save succeeded. `has_unsaved_changes`, if given, lets a tick
462
+ with nothing to save do nothing at all.
411
463
 
412
464
  Building the `WorkflowAutosaveController` here — rather than each
413
465
  plugin constructing one itself — is what makes `populate_preferences`
@@ -423,6 +475,7 @@ class PluginBase(QWidget):
423
475
  save,
424
476
  interval_ms=interval_ms if interval_ms is not None else DEFAULT_INTERVAL_MS,
425
477
  parent=self,
478
+ has_unsaved_changes=has_unsaved_changes,
426
479
  )
427
480
  self._workflow_autosave_controller = controller
428
481
  controller.start()