Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): stop theme toggle strobing other project windows (#2042)

Andrew Mikofalvye17e194442ea
diff --git a/.changeset/fix-multi-window-theme-content-flicker.md b/.changeset/fix-multi-window-theme-content-flicker.md
new file mode 100644
index 000000000..41008a465
--- /dev/null
+++ b/.changeset/fix-multi-window-theme-content-flicker.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix the appearance theme toggle making other open project windows flicker between light and dark before settling. With more than one project open, switching `Light` / `Dark` / `System` would strobe every other window. The cause was an app-layer feedback loop: when a window observed another window's theme change, it re-applied its own briefly-stale saved theme and wrote that stale value back to the shared theme storage, which re-triggered every window until all windows caught up. Theme changes now propagate across windows cleanly, with no cross-window flicker. (A companion change separately reduces redundant macOS window-chrome translucency work on the same switch.)
diff --git a/packages/app/src/lib/config-provider.tsx b/packages/app/src/lib/config-provider.tsx
index a0a77c5b4..cb65adf51 100644
--- a/packages/app/src/lib/config-provider.tsx
+++ b/packages/app/src/lib/config-provider.tsx
@@ -12,13 +12,13 @@ import {
type OkignoreBinding,
type WriteScope,
} from '@inkeep/open-knowledge-core';
-import { useTheme } from 'next-themes';
import { type ReactNode, useEffect, useState } from 'react';
import * as Y from 'yjs';
import { useThemeBridge } from '@/hooks/use-theme-bridge';
import { buildAuthToken } from './auth-token';
import { ConfigContext, type ConfigContextValue } from './config-context';
import { useServerInstanceId } from './server-instance-store';
+import { useApplyConfigTheme } from './use-apply-config-theme';
export { useConfigContext } from './config-context';
@@ -224,13 +224,8 @@ export function ConfigProvider({
? mergeLayered(userState.config, projectState.config, projectLocalState?.config)
: null;
- const { setTheme } = useTheme();
const themeValue = merged?.appearance?.theme;
- useEffect(() => {
- if (themeValue === 'light' || themeValue === 'dark' || themeValue === 'system') {
- setTheme(themeValue);
- }
- }, [themeValue, setTheme]);
+ useApplyConfigTheme(themeValue);
useThemeBridge(
typeof window !== 'undefined' ? window.okDesktop : undefined,
diff --git a/packages/app/src/lib/use-apply-config-theme.dom.test.tsx b/packages/app/src/lib/use-apply-config-theme.dom.test.tsx
new file mode 100644
index 000000000..cab4be649
--- /dev/null
+++ b/packages/app/src/lib/use-apply-config-theme.dom.test.tsx
@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, render } from '@testing-library/react';
+import { ThemeProvider } from 'next-themes';
+import type { ReactElement } from 'react';
+import { useApplyConfigTheme } from './use-apply-config-theme';
+
+function ConfigThemeHarness({ themeValue }: { themeValue: string | undefined }) {
+ useApplyConfigTheme(themeValue);
+ return null;
+}
+
+function themeTree(themeValue: string | undefined): ReactElement {
+ return (
+ <ThemeProvider
+ attribute="class"
+ defaultTheme="system"
+ enableSystem
+ disableTransitionOnChange
+ storageKey="ok-theme-v1"
+ >
+ <ConfigThemeHarness themeValue={themeValue} />
+ </ThemeProvider>
+ );
+}
+
+function dispatchCrossWindowStorage(newValue: string) {
+ window.localStorage.setItem('ok-theme-v1', newValue);
+ const ev = new Event('storage');
+ Object.assign(ev, { key: 'ok-theme-v1', newValue, oldValue: null });
+ window.dispatchEvent(ev);
+}
+
+describe('useApplyConfigTheme — cross-window flicker guard', () => {
+ beforeEach(() => {
+ (globalThis as { localStorage?: Storage }).localStorage = window.localStorage;
+ window.localStorage.clear();
+ document.documentElement.className = '';
+ });
+ afterEach(() => {
+ cleanup();
+ window.localStorage.clear();
+ document.documentElement.className = '';
+ });
+
+ test('a cross-window storage flip is NOT reverted while this window config is stale', async () => {
+ await act(async () => {
+ render(themeTree('light'));
+ await Promise.resolve();
+ });
+ expect(document.documentElement.classList.contains('light')).toBe(true);
+
+ await act(async () => {
+ dispatchCrossWindowStorage('dark');
+ await Promise.resolve();
+ });
+
+ expect(document.documentElement.classList.contains('dark')).toBe(true);
+ expect(document.documentElement.classList.contains('light')).toBe(false);
+ expect(window.localStorage.getItem('ok-theme-v1')).toBe('dark');
+ });
+
+ test('a genuine config-theme change still applies (the effect is not dead)', async () => {
+ const { rerender } = render(themeTree('light'));
+ await act(async () => {
+ await Promise.resolve();
+ });
+ expect(document.documentElement.classList.contains('light')).toBe(true);
+
+ await act(async () => {
+ rerender(themeTree('dark'));
+ await Promise.resolve();
+ });
+ expect(document.documentElement.classList.contains('dark')).toBe(true);
+ });
+
+ test("'system' is applied, pinning the third guard branch", async () => {
+ await act(async () => {
+ render(themeTree('system'));
+ await Promise.resolve();
+ });
+ expect(document.documentElement.classList.contains('light')).toBe(true);
+ expect(document.documentElement.classList.contains('dark')).toBe(false);
+ });
+
+ test('no-ops while themeValue is undefined (cold start), then applies once it lands', async () => {
+ const { rerender } = render(themeTree(undefined));
+ await act(async () => {
+ await Promise.resolve();
+ });
+ expect(document.documentElement.classList.contains('dark')).toBe(false);
+
+ await act(async () => {
+ rerender(themeTree('dark'));
+ await Promise.resolve();
+ });
+ expect(document.documentElement.classList.contains('dark')).toBe(true);
+ });
+});
diff --git a/packages/app/src/lib/use-apply-config-theme.ts b/packages/app/src/lib/use-apply-config-theme.ts
new file mode 100644
index 000000000..6b30fb673
--- /dev/null
+++ b/packages/app/src/lib/use-apply-config-theme.ts
@@ -0,0 +1,12 @@
+import { useTheme } from 'next-themes';
+import { useEffect } from 'react';
+
+export function useApplyConfigTheme(themeValue: string | undefined): void {
+ const { setTheme } = useTheme();
+ // biome-ignore lint/correctness/useExhaustiveDependencies: setTheme excluded by design — re-adding it re-fires on every cross-window theme flip and storms every window (see STORM GUARD above).
+ useEffect(() => {
+ if (themeValue === 'light' || themeValue === 'dark' || themeValue === 'system') {
+ setTheme(themeValue);
+ }
+ }, [themeValue]);
+}