diff --git a/test/shell.d/bar-widget-contract-test.sh b/test/shell.d/bar-widget-contract-test.sh
new file mode 100755
index 00000000..7cdd5b22
--- /dev/null
+++ b/test/shell.d/bar-widget-contract-test.sh
@@ -0,0 +1,98 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+TMPDIR=""
+QS_PID=""
+
+cleanup() {
+  if [[ -n $QS_PID ]] && kill -0 "$QS_PID" 2>/dev/null; then
+    kill "$QS_PID" 2>/dev/null || true
+    wait "$QS_PID" 2>/dev/null || true
+  fi
+  [[ -n $TMPDIR && -d $TMPDIR ]] && rm -rf "$TMPDIR"
+}
+trap cleanup EXIT
+
+if [[ -z ${WAYLAND_DISPLAY:-} ]]; then
+  pass "no Wayland compositor; skipping bar widget contract test"
+  exit 0
+fi
+
+if ! command -v quickshell >/dev/null 2>&1; then
+  pass "quickshell not installed; skipping bar widget contract test"
+  exit 0
+fi
+
+require_command jq
+require_command python3
+
+bar_widgets=$(ROOT="$ROOT" python3 <<'PY'
+import base64
+import json
+import os
+from pathlib import Path
+
+root = Path(os.environ["ROOT"])
+entries = []
+for manifest_path in sorted((root / "shell/plugins").glob("**/manifest.json")) + sorted((root / "shell/plugins").glob("**/*.manifest.json")):
+  manifest = json.loads(manifest_path.read_text())
+  if "bar-widget" not in manifest.get("kinds", []):
+    continue
+  entry_point = manifest.get("entryPoints", {}).get("barWidget")
+  if not entry_point:
+    continue
+  entries.append({
+    "id": manifest["id"],
+    "url": (manifest_path.parent / entry_point).resolve().as_uri(),
+    "manifest": manifest,
+  })
+
+print(base64.b64encode(json.dumps(entries).encode()).decode())
+PY
+)
+
+TMPDIR=$(mktemp -d)
+result="$TMPDIR/result.json"
+log="$TMPDIR/quickshell.log"
+config_dir="$TMPDIR/bar-widget-contract"
+mkdir -p "$config_dir" "$TMPDIR/home"
+cp "$SHELL_TEST_DIR/fixtures/bar-widget-contract/shell.qml" "$config_dir/shell.qml"
+ln -s "$ROOT/shell/Ui" "$config_dir/Ui"
+ln -s "$ROOT/shell/Commons" "$config_dir/Commons"
+
+OMARCHY_PATH="$ROOT" \
+OMARCHY_QML_TEST_RESULT="$result" \
+OMARCHY_QML_BAR_WIDGETS="$bar_widgets" \
+HOME="$TMPDIR/home" \
+QML2_IMPORT_PATH="$ROOT/shell${QML2_IMPORT_PATH:+:$QML2_IMPORT_PATH}" \
+QML_IMPORT_PATH="$ROOT/shell${QML_IMPORT_PATH:+:$QML_IMPORT_PATH}" \
+PATH="$ROOT/bin:$PATH" \
+  quickshell -p "$config_dir" --no-color >"$log" 2>&1 &
+QS_PID=$!
+
+for _ in {1..80}; do
+  [[ -s $result ]] && break
+  if ! kill -0 "$QS_PID" 2>/dev/null; then
+    sed -n '1,220p' "$log" >&2
+    fail "bar widget contract quickshell exited before writing result"
+  fi
+  sleep 0.1
+done
+
+[[ -s $result ]] || {
+  sed -n '1,220p' "$log" >&2
+  fail "bar widget contract test timed out"
+}
+
+if ! jq -e '.ok == true' "$result" >/dev/null; then
+  printf 'Bar widget contract result:\n' >&2
+  jq . "$result" >&2
+  printf 'Bar widget contract log:\n' >&2
+  sed -n '1,220p' "$log" >&2
+  fail "bar widget contracts pass"
+fi
+
+pass "bar widget contracts pass"
diff --git a/test/shell.d/fixtures/bar-widget-contract/shell.qml b/test/shell.d/fixtures/bar-widget-contract/shell.qml
new file mode 100644
index 00000000..40955501
--- /dev/null
+++ b/test/shell.d/fixtures/bar-widget-contract/shell.qml
@@ -0,0 +1,171 @@
+import QtQuick
+import Quickshell
+
+ShellRoot {
+  id: root
+
+  readonly property string resultPath: Quickshell.env("OMARCHY_QML_TEST_RESULT")
+  readonly property string rootPath: Quickshell.env("OMARCHY_PATH")
+  property var failures: []
+  property var createdIds: []
+  property var createdObjects: []
+
+  function fail(message) {
+    failures.push(String(message))
+  }
+
+  function assertTrue(condition, message) {
+    if (!condition) fail(message)
+  }
+
+  function assertEqual(actual, expected, message) {
+    if (actual !== expected) fail(message + " expected=" + expected + " actual=" + actual)
+  }
+
+  function shellQuote(value) {
+    return "'" + String(value).replace(/'/g, "'\\''") + "'"
+  }
+
+  function writeResult() {
+    var payload = JSON.stringify({
+      ok: failures.length === 0,
+      failures: failures,
+      created: createdIds
+    })
+
+    if (resultPath) {
+      Quickshell.execDetached(["bash", "-lc", "printf '%s' " + shellQuote(payload) + " > " + shellQuote(resultPath)])
+    }
+  }
+
+  function widgets() {
+    try {
+      return JSON.parse(Qt.atob(Quickshell.env("OMARCHY_QML_BAR_WIDGETS") || "W10="))
+    } catch (error) {
+      fail("bar widget list failed to parse: " + error)
+      return []
+    }
+  }
+
+  function safeCall(item, method, entry) {
+    if (!item || typeof item[method] !== "function") return
+    try {
+      item[method]()
+    } catch (error) {
+      fail(entry.id + " " + method + "() threw: " + error)
+    }
+  }
+
+  function finiteDimension(value) {
+    var n = Number(value)
+    return isFinite(n) && n >= 0
+  }
+
+  function loadWidget(entry) {
+    var component = Qt.createComponent(entry.url, Component.PreferSynchronous)
+    if (component.status !== Component.Ready) {
+      fail(entry.id + " failed to load: " + component.errorString())
+      return
+    }
+
+    var item = component.createObject(host, {
+      moduleName: entry.id,
+      settings: {}
+    })
+    if (!item) {
+      fail(entry.id + " failed to instantiate without bar: " + component.errorString())
+      return
+    }
+
+    if ("bar" in item) {
+      root.assertTrue(item.bar === null || item.bar === undefined, entry.id + " starts without injected bar")
+      item.bar = fakeBar
+      root.assertTrue(item.bar === fakeBar, entry.id + " accepts delayed bar injection")
+    }
+    if ("moduleName" in item) {
+      item.moduleName = entry.id
+      root.assertEqual(item.moduleName, entry.id, entry.id + " accepts moduleName injection")
+    }
+    if ("settings" in item) {
+      item.settings = {}
+      root.assertTrue(item.settings !== null && item.settings !== undefined, entry.id + " accepts settings injection")
+    }
+    if (typeof item.setting === "function") {
+      root.assertEqual(item.setting("missing", "fallback"), "fallback", entry.id + " exposes setting fallback")
+    }
+
+    safeCall(item, "refresh", entry)
+    safeCall(item, "close", entry)
+
+    createdObjects.push(item)
+    createdIds.push(entry.id)
+  }
+
+  Item { id: host }
+
+  QtObject {
+    id: mockNotificationService
+    property bool doNotDisturb: false
+    property ListModel pendingModel: ListModel {}
+    property ListModel pastModel: ListModel {}
+    function setDoNotDisturb(value) { doNotDisturb = !!value }
+  }
+
+  QtObject {
+    id: mockShell
+    property var bar: fakeBar
+    property var barConfig: ({ position: "top" })
+    property var shellConfig: ({ version: 1, idle: {}, plugins: [], bar: { layout: { left: [], center: [], right: [] } } })
+    function firstPartyServiceFor(id) {
+      if (id === "omarchy.notifications") return mockNotificationService
+      return null
+    }
+    function serviceFor(id) { return firstPartyServiceFor(id) }
+    function summon(id, payloadJson) { return true }
+    function hide(id) { return true }
+    function toggle(id, payloadJson) { return true }
+    function updateEntryInline(moduleName, settings) { return true }
+  }
+
+  QtObject {
+    id: fakeBar
+    property bool vertical: false
+    property int barSize: 26
+    property string omarchyPath: root.rootPath
+    property string fontFamily: "monospace"
+    property color foreground: "white"
+    property color background: "black"
+    property color urgent: "red"
+    property var shell: mockShell
+    function run(command) {}
+    function showTooltip(target, text) {}
+    function hideTooltip(target) {}
+    function requestPopout(owner) {}
+    function releasePopout(owner) {}
+    function registerClickTarget(target) {}
+    function unregisterClickTarget(target) {}
+  }
+
+  Timer {
+    interval: 1
+    running: true
+    repeat: false
+    onTriggered: {
+      var entries = widgets()
+      root.assertTrue(entries.length > 0, "bar widget list is not empty")
+      for (var i = 0; i < entries.length; i++) root.loadWidget(entries[i])
+
+      Qt.callLater(function() {
+        for (var j = 0; j < root.createdObjects.length; j++) {
+          var item = root.createdObjects[j]
+          var id = root.createdIds[j]
+          root.assertTrue(root.finiteDimension(item.implicitWidth), id + " has a finite implicitWidth")
+          root.assertTrue(root.finiteDimension(item.implicitHeight), id + " has a finite implicitHeight")
+          if (item && typeof item.destroy === "function") item.destroy()
+        }
+        root.assertTrue(root.createdIds.length === entries.length, "all bar widgets instantiate")
+        root.writeResult()
+      })
+    }
+  }
+}