Skip to content

Fix stale local plugin reloads and add scoped hot reload - #7771

Open
adamritter wants to merge 5 commits into
omacom:quattrofrom
adamritter:fix/plugin-widget-hot-reload
Open

adamritter wants to merge 5 commits into
omacom:quattrofrom
adamritter:fix/plugin-widget-hot-reload

Conversation

@adamritter

@adamritter adamritter commented Aug 22, 2026 •

Copy link
Copy Markdown

Fixes #6981.

Related to #7259 and #7605. This combines stale local QML entry-point replacement with targeted local-plugin reloads: unlike #7259 it does not restart the whole shell, and unlike #7605 it also forces the changed component to receive a fresh QML URL.

A more comprehensive targeted-reload implementation was previously explored in #6785 and closed because its complexity outweighed the benefit. This patch keeps the default path smaller by using per-plugin URL revisions and the existing registry/rescan lifecycle, while allowing plugins to opt into narrower reload boundaries where preserving their live instance matters.

Summary

  • give each changed local plugin entry point a revisioned URL so edited QML cannot resolve to a stale cached component
  • reload only plugins reported by the local file watcher instead of restarting unrelated first-party services
  • resolve watched source directories back to manifest IDs, including development checkouts whose directory name differs from the plugin ID
  • add an optional manifest.hotReload map for plugin-owned, in-process reload boundaries
  • call reloadEntryPoint(key, path) on every live instance of a matching bar widget while keeping the stock bar, widget instance, windows, and service state alive
  • fall back to the normal targeted plugin/QML graph reload when no live widget handles a declared boundary
  • validate that declared boundary paths are safe, relative, and present inside the plugin
  • keep full manual plugin rescans while avoiding global QML cache invalidation
  • extend registry, manifest-validation, and runtime coverage for mismatched IDs, imported QML changes, scoped boundaries, and fallback behavior

Hot-reload boundary contract

Local bar widgets can declare named boundaries in their manifest:

{
  "hotReload": {
    "content": "Content.qml"
  }
}

When the exact file changes, the shell calls the matching live widget instances:

function reloadEntryPoint(kind, path) {
  if (kind !== "content") return false
  contentRevision++
  contentLoader.source = Qt.resolvedUrl("Content.qml") + "#reload=" + contentRevision
  return true
}

Returning anything except false marks that instance as handled. If no live instance handles the key, the existing targeted plugin reload is queued instead. Imported QML or JavaScript files not declared as boundaries continue to trigger a QML graph reload.

Reproduction

The runtime assertion failed before the fix: the shell logged the local plugin change, but the running component continued using its original QML until the whole shell restarted. A development checkout exposed a second routing issue: the watcher reported its directory name while reload revisions were keyed by manifest ID, so a checkout such as agent-threads with manifest ID adam.codex-threads incremented the wrong revision.

The new boundary assertion additionally verifies that changing a declared content file replaces only that content and preserves a token stored on its parent widget instance.

Test plan

  • ./test/shell.d/plugin-validate-test.sh
  • ./test/shell.d/plugin-registry-contract-test.sh
  • ./test/shell.d/runtime-smoke-test.sh
  • ./test/shell (182/185 files passed during the earlier aggregate run; the three packaging-coverage files require a separate omarchy-pkgs checkout that is not present locally)
  • live verification with a plugin whose source directory and manifest ID differ

The three focused tests above pass with the scoped hot-reload commit.

Copilot AI balanced review requested due to automatic review settings August 22, 2026 12:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes stale hot reloads for locally-installed Quickshell plugins in the Omarchy desktop shell. Previously, when a user edited a local plugin's QML, the file watcher restarted the whole plugin subsystem (unloading all widgets and clearing the global component cache), yet the running component often kept rendering its original QML until a full shell restart. The fix gives each third-party plugin entry point a revisioned URL (#reload=N) so edited QML resolves to a fresh component, and narrows the local-change path to reload only the plugins the watcher actually reported, leaving unrelated first-party services untouched.

Changes:

  • Added pluginEntryPointUrl() which appends a per-plugin #reload=<revision> fragment to non-first-party entry point URLs, and routed all component-loading call sites through it.
  • Introduced a targeted local-reload path (queueLocalPluginReload/reloadLocalPlugins/unloadPluginService) that bumps only the affected plugins' revisions and rescans, replacing the previous global reload and Qt.clearComponentCache().
  • Extended the runtime smoke test to load a local bar widget, edit its QML live, and assert the replacement component loads while first-party services stay running.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File Description
shell/shell.qml Adds revisioned entry-point URLs and a targeted local-plugin reload path; removes global widget unload and component-cache clearing
test/shell.d/runtime-smoke-test.sh Adds a live bar-widget edit/reload assertion and verifies first-party services are not restarted

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread shell/shell.qml Resolved
Comment thread test/shell.d/runtime-smoke-test.sh Resolved
@adamritter adamritter changed the title Fix stale local plugin hot reloads Fix stale local plugin reloads and add scoped hot reload Aug 28, 2026
@omarchybot omarchybot added the enhancement New feature or request label Sep 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Plugin hot-reload never picks up changed plugin code (stale QML component cache)

3 participants