Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(settings): Show grid dots toggle in Appearance

iceclatterWT340cec1ca895
diff --git a/CLAUDE.md b/CLAUDE.md
index 41d3d4a4c..5ff5961f6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3774,7 +3774,11 @@ glass never sits over plain black; a wallpaper the user chose is never replaced.
tab bar row included, so Liquid Glass's tab bar is glass over the picture — and is never
transformed, so it stays put while the canvas pans and zooms. React Flow's own root goes
transparent over it (`.react-flow.has-wallpaper`); the dot grid is faded to 30%, not removed,
- because snapping still aligns to it. The kanban overlay paints its own background and is
+ because snapping still aligns to it. **Settings → Appearance → Show grid dots**
+ (`settings.canvasDots`, default ON in every appearance, read through `showCanvasDots` — only a
+ literal `false` hides them) omits the React Flow `<Background>` entirely; it is display only, and
+ snap-to-grid / align-to-grid keep using `gridSize`. Pure renderer + settings.json, so the Server
+ Edition gets it unchanged. The kanban overlay paints its own background and is
unaffected.
- **`background-image` + longhands, never a `background` shorthand next to `var(--canvas-bg)`.**
MEASURED live: Chromium drops a var()-containing value once it passes ~2 MB, and a still's data:
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index c2a3714a4..71333f74c 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -646,6 +646,7 @@ import type { CodexAccount } from '@shared/codex-account'
import { useSystemCodexAccount } from '../state/systemCodexAccount'
import { toKanbanSession } from './toKanbanSession'
import { useWallpaperBackground } from '../state/wallpaper'
+import { showCanvasDots } from '../lib/canvasDots'
const isMac = /Mac/i.test(navigator.platform || navigator.userAgent)
@@ -14915,6 +14916,7 @@ export function Canvas() {
snapToGrid={settings.snapToGrid}
snapGrid={[settings.gridSize, settings.gridSize]}
>
+ {showCanvasDots(settings.canvasDots) && (
<Background
variant={BackgroundVariant.Dots}
gap={settings.gridSize || GRID}
@@ -14929,6 +14931,7 @@ export function Canvas() {
token instead. On white the dark-mode grey reads as noise rather than as a grid. */
color="var(--canvas-dot)"
/>
+ )}
{/* The shared glyph canvas: a <ReactFlow> child (so it is a sibling of the background
and of the node renderer) at z-index 0 — above the dot grid, below every node. Only
mounted in the experimental 'shared' renderer mode; nothing about it exists for the
diff --git a/src/renderer/components/settings/sections/AppearanceSection.tsx b/src/renderer/components/settings/sections/AppearanceSection.tsx
index 54ff21c06..82cae8bc6 100644
--- a/src/renderer/components/settings/sections/AppearanceSection.tsx
+++ b/src/renderer/components/settings/sections/AppearanceSection.tsx
@@ -1,6 +1,7 @@
import { useEffect, useState } from 'react'
import { useSettings } from '../../../state/settings'
import { isLiquidGlass } from '@renderer/lib/appTheme'
+import { showCanvasDots } from '@renderer/lib/canvasDots'
import {
defaultWallpaper,
GRADIENT_WALLPAPERS,
@@ -68,6 +69,10 @@ const ROWS = {
'native'
]
},
+ canvasDots: {
+ title: 'Show grid dots',
+ keywords: ['grid', 'dots', 'dot', 'canvas', 'background', 'pattern']
+ },
resumeCard: {
title: 'Resume card',
keywords: ['resume', 'where you left off', 'breadcrumb', 'card', 'popup', 'trail']
@@ -331,6 +336,7 @@ export function AppearanceSection({ isActive }: { isActive: boolean }): React.JS
const hiddenNodeMenuItems = useSettings((s) => s.settings.hiddenNodeMenuItems)
const hiddenHeaderButtons = useSettings((s) => s.settings.hiddenHeaderButtons)
const showResumeCard = useSettings((s) => s.settings.showResumeCard)
+ const canvasDots = useSettings((s) => s.settings.canvasDots)
const windowTitleActiveSession = useSettings((s) => s.settings.windowTitleActiveSession)
const update = useSettings((s) => s.update)
// Glass over plain black reads as a dark theme with smudges, so choosing Liquid Glass with no
@@ -428,6 +434,19 @@ export function AppearanceSection({ isActive }: { isActive: boolean }): React.JS
}
/>
</SearchableRow>
+ <SearchableRow {...ROWS.canvasDots}>
+ <FieldRow
+ label="Show grid dots"
+ description="Draw the dot grid on the canvas. Only the dots: snapping and align to grid work the same either way."
+ control={
+ <Switch
+ checked={showCanvasDots(canvasDots)}
+ onChange={(v) => update({ canvasDots: v })}
+ ariaLabel="Show grid dots"
+ />
+ }
+ />
+ </SearchableRow>
<SearchableRow {...ROWS.resumeCard}>
<FieldRow
label="Resume card"
diff --git a/src/renderer/lib/canvasDots.test.ts b/src/renderer/lib/canvasDots.test.ts
new file mode 100644
index 000000000..5916aecdf
--- /dev/null
+++ b/src/renderer/lib/canvasDots.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_SETTINGS } from '@shared/types'
+import { showCanvasDots } from './canvasDots'
+
+describe('showCanvasDots', () => {
+ it('ships on', () => {
+ expect(DEFAULT_SETTINGS.canvasDots).toBe(true)
+ expect(showCanvasDots(DEFAULT_SETTINGS.canvasDots)).toBe(true)
+ })
+ it('only a literal false hides the dots; anything hand-edited keeps them', () => {
+ expect(showCanvasDots(false)).toBe(false)
+ for (const v of [true, undefined, null, 0, 'false', {}]) expect(showCanvasDots(v)).toBe(true)
+ })
+})
diff --git a/src/renderer/lib/canvasDots.ts b/src/renderer/lib/canvasDots.ts
new file mode 100644
index 000000000..80e5c5a75
--- /dev/null
+++ b/src/renderer/lib/canvasDots.ts
@@ -0,0 +1,9 @@
+/**
+ * Whether the canvas draws its dot grid (Settings → Appearance → Show grid dots). Display only:
+ * snap-to-grid and align-to-grid keep using `gridSize` either way.
+ *
+ * settings.json is hand-editable, so anything but a literal `false` keeps the default (dots on).
+ */
+export function showCanvasDots(value: unknown): boolean {
+ return value !== false
+}
diff --git a/src/renderer/lib/settingsReset.ts b/src/renderer/lib/settingsReset.ts
index 67df9e709..330c55494 100644
--- a/src/renderer/lib/settingsReset.ts
+++ b/src/renderer/lib/settingsReset.ts
@@ -41,6 +41,7 @@ export const APPEARANCE_RESET_KEYS = [
'hiddenNodeMenuItems',
'hiddenHeaderButtons',
'showResumeCard',
+ 'canvasDots',
'windowTitleActiveSession'
] as const satisfies readonly (keyof Settings)[]
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 4b3610475..a4f9417e1 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1690,6 +1690,9 @@ export interface Settings {
* once-per-app-run popup). OFF by default — it interrupts every project switch, so it is
* opt-in. Cmd+[ / Cmd+] and the Dock buttons walk the trail regardless of this. */
showResumeCard: boolean
+ /** Draw the canvas dot grid (Settings → Appearance). Display only — snapping and align-to-grid
+ * are unchanged. Default ON in every appearance; read through `showCanvasDots`. */
+ canvasDots: boolean
/** Whether usage percentages render as consumed ("32% used"), remaining ("68% left"), or raw
* token counts ("48k/200k tokens" — context-window surfaces only; provider quota surfaces
* have no token counts and fall back to 'used' display). 'remaining' is the historical
@@ -1934,6 +1937,7 @@ export const DEFAULT_SETTINGS: Settings = {
// Opt-in: the resume card pops over the canvas on every qualifying project activation, which
// reads as noise to users who navigate by the trail chords/Dock buttons instead.
showResumeCard: false,
+ canvasDots: true,
usagePercentMode: 'remaining',
defaultAgent: 'claude',
// Sessions start in auto mode out of the box. Existing users pick this up on hydrate