Fix invisible sidebar badge on transparent themes (#186); point schema-fence message at doctor --force (#185)

#186: the sidebar header badge drew its label with fg={theme.background} on a
theme.accent background. Themes that set background:"none" to respect terminal
transparency resolve theme.background to RGBA(0,0,0,0), so the badge text
rendered fully transparent and vanished, making transparent themes unusable.
Derive the text color from the badge's own (always-opaque) accent background via
a luminance-based black/white pick (readableTextColorOn), so the label stays
readable regardless of background transparency. Pure, unit-tested helper.

#185: the schema-fence message (DB on disk is a newer schema than this binary
supports) said only "upgrade Magic Context/OpenCode/Pi". The common cause is a
pinned or stale plugin sharing the shared context.db with a newer instance, and
the concrete remedy is 'doctor --force' (which unpins the config entry AND
clears the stale npm plugin cache). Updated the shared storage log line, the
Desktop fence warning, and Pi's fence warning to name the likely cause and the
exact command.

Co-authored-by: Alfonso [Magic Context] <288211368+alfonso-magic-context@users.noreply.github.com>

Author: ualtinok

packages/pi-plugin/src/index.ts

@@ -468,7 +468,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	if (!db) {
 		warn(
 			`Magic Context (pi) storage unavailable at ${dbPath} (cache schema is newer than this binary supports). ` +
-				"Plugin will not register hooks; upgrade/restart Pi/OpenCode/Magic Context to recover.",
+				"A pinned or stale plugin is likely sharing this database with a newer instance. " +
+				"Plugin will not register hooks; run 'npx @cortexkit/magic-context@latest doctor --force' " +
+				"(or update Pi/OpenCode) and restart to recover.",
 		);
 		return;
 	}

packages/plugin/src/features/magic-context/storage-db.ts

@@ -296,7 +296,7 @@ export function enforceSchemaFence(
     }
     lastSchemaFenceRejection = { persistedVersion, supportedVersion: latestSupportedVersion };
     log(
-        `[magic-context] storage fatal: refusing to open ${dbPath}; database schema v${persistedVersion} is newer than this binary supports (max v${latestSupportedVersion}). Upgrade Magic Context/OpenCode/Pi before writing to this cache.`,
+        `[magic-context] storage fatal: refusing to open ${dbPath}; database schema v${persistedVersion} is newer than this binary supports (max v${latestSupportedVersion}). A pinned or stale plugin is likely sharing this database with a newer instance; update or unpin Magic Context with 'npx @cortexkit/magic-context@latest doctor --force', then restart.`,
     );
     return false;
 }

packages/plugin/src/plugin/conflict-warning-hook.ts

@@ -524,8 +524,13 @@ export async function sendSchemaFenceWarning(
         `newer build (OpenCode and Pi share one database). This build only supports`,
         `up to v${detail.supportedVersion}, so it has fail-closed to avoid corrupting the cache.`,
         "",
-        "Update Magic Context on this harness (or update OpenCode/Pi) to the latest",
-        "version, then restart. Your data is safe — nothing is disabled permanently.",
+        "This usually means a pinned or stale plugin is sharing the database with a",
+        "newer instance. Update or unpin Magic Context on this harness (or update",
+        "OpenCode/Pi) to the latest version, then restart. The fastest fix is:",
+        "",
+        "  npx @cortexkit/magic-context@latest doctor --force",
+        "",
+        "Your data is safe; nothing is disabled permanently.",
     ].join("\n");
 
     try {

packages/plugin/src/tui/badge-contrast.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { readableTextColorOn } from "./badge-contrast";
+
+describe("readableTextColorOn", () => {
+    test("dark accent gets white text", () => {
+        // A typical dark accent (deep blue/purple) should read as white.
+        expect(readableTextColorOn({ r: 0.1, g: 0.1, b: 0.3 })).toBe("#ffffff");
+        expect(readableTextColorOn({ r: 0, g: 0, b: 0 })).toBe("#ffffff");
+    });
+
+    test("light accent gets black text", () => {
+        // Light/pastel accents should read as black.
+        expect(readableTextColorOn({ r: 0.9, g: 0.9, b: 0.7 })).toBe("#000000");
+        expect(readableTextColorOn({ r: 1, g: 1, b: 1 })).toBe("#000000");
+    });
+
+    test("pure green is treated as light (high luma weight)", () => {
+        // Green dominates perceived brightness, so a saturated green badge needs
+        // dark text.
+        expect(readableTextColorOn({ r: 0, g: 1, b: 0 })).toBe("#000000");
+    });
+
+    test("pure blue is treated as dark (low luma weight)", () => {
+        // Blue contributes little to perceived brightness, so a saturated blue
+        // badge needs light text.
+        expect(readableTextColorOn({ r: 0, g: 0, b: 1 })).toBe("#ffffff");
+    });
+
+    test("does not depend on the (possibly transparent) background alpha", () => {
+        // The helper only reads r/g/b — the regression in #186 was using a
+        // background color whose alpha could be 0. Two accents with identical
+        // rgb resolve identically regardless of any alpha the caller might pass.
+        const a = readableTextColorOn({ r: 0.2, g: 0.2, b: 0.2 });
+        const b = readableTextColorOn({ r: 0.2, g: 0.2, b: 0.2 });
+        expect(a).toBe(b);
+        expect(a).toBe("#ffffff");
+    });
+});

packages/plugin/src/tui/badge-contrast.ts

@@ -0,0 +1,21 @@
+/**
+ * Pick a readable text color (black or white) for text drawn ON TOP of a given
+ * background color.
+ *
+ * The sidebar header badge previously drew its label with `fg={theme.background}`
+ * on a `theme.accent` background. That breaks for themes that set
+ * `background: "none"` (transparent) to respect terminal transparency: the
+ * resolved background is `RGBA(0,0,0,0)`, so the badge text renders fully
+ * transparent and disappears (issue #186). The badge background (`accent`) is
+ * always opaque, so deriving the text color from it is transparency-proof.
+ *
+ * `RGBA` channels from @opentui/core are normalized 0..1 floats. We accept the
+ * minimal `{ r, g, b }` shape so this stays a pure, trivially testable function
+ * independent of the native color class.
+ */
+export function readableTextColorOn(bg: { r: number; g: number; b: number }): string {
+    // Perceptual brightness (ITU-R BT.601 luma weights). Channels are 0..1, so
+    // the result is 0..1; >= 0.5 is a "light" background that needs dark text.
+    const brightness = 0.299 * bg.r + 0.587 * bg.g + 0.114 * bg.b;
+    return brightness >= 0.5 ? "#000000" : "#ffffff";
+}

packages/plugin/src/tui/slots/sidebar-content.tsx

@@ -2,6 +2,7 @@
 import { Show, createEffect, createMemo, createSignal, on, onCleanup } from "solid-js"
 import type { TuiSlotPlugin, TuiPluginApi, TuiThemeCurrent } from "@opencode-ai/plugin/tui"
 import packageJson from "../../../package.json"
+import { readableTextColorOn } from '../badge-contrast';
 import { loadSidebarSnapshot, type SidebarSnapshot } from "../data/context-db"
 import { formatThresholdPercent } from "../../shared/format-threshold"
 import {
@@ -694,7 +695,7 @@ const SidebarContent = (props: {
                 onMouseDown={() => props.controller.toggleCollapsed()}
             >
                 <box paddingLeft={1} paddingRight={1} backgroundColor={props.theme.accent}>
-                    <text fg={props.theme.background}>
+                    <text fg={readableTextColorOn(props.theme.accent)}>
                         <b>{collapsed() ? "▶ " : "▼ "}{headerLabel()}</b>
                     </text>
                 </box>