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(appearance): solid backing for sticky notes and group frames (#1231)

eneskirca98ac577cfe09
diff --git a/src/renderer/components/settings/sections/AppearanceSection.tsx b/src/renderer/components/settings/sections/AppearanceSection.tsx
index b0ce30d6e..838309f44 100644
--- a/src/renderer/components/settings/sections/AppearanceSection.tsx
+++ b/src/renderer/components/settings/sections/AppearanceSection.tsx
@@ -1,3 +1,4 @@
+import { CANVAS_BACKING_MAX, CANVAS_BACKING_MIN, resolveCanvasBacking } from '@shared/canvas-backing'
import { useEffect, useState } from 'react'
import { useSettings } from '../../../state/settings'
import { useWallpaperBackgroundFor } from '../../../state/wallpaper'
@@ -70,6 +71,14 @@ const ROWS = {
title: 'Tab bar height',
keywords: ['tab', 'bar', 'height', 'strip', 'top', 'title bar', 'thickness', 'compact', 'dense']
},
+ stickyNoteBacking: {
+ title: 'Sticky note background',
+ keywords: ['sticky', 'note', 'notes', 'transparency', 'transparent', 'opacity', 'opaque', 'solid', 'see-through', 'background', 'readability']
+ },
+ groupFrameBacking: {
+ title: 'Group frame background',
+ keywords: ['group', 'frame', 'frames', 'transparency', 'transparent', 'opacity', 'opaque', 'solid', 'see-through', 'background']
+ },
markdownFont: {
title: 'Markdown font',
keywords: ['markdown', 'font', 'family', 'typeface', 'chat', 'preview', 'reading', 'output', 'text', 'serif', 'sans']
@@ -249,6 +258,37 @@ function TabBarHeightRow(): React.JSX.Element {
)
}
+/** How solid a sticky note / group frame is behind its colour tint (issue #1113). 0 = the
+ * original see-through look; the tint itself never changes. */
+function CanvasBackingRow({ kind }: { kind: 'stickyNoteBacking' | 'groupFrameBacking' }): React.JSX.Element {
+ const value = useSettings((s) => s.settings[kind])
+ const update = useSettings((s) => s.update)
+ const sticky = kind === 'stickyNoteBacking'
+ const label = sticky ? 'Sticky note background' : 'Group frame background'
+ return (
+ <FieldRow
+ label={label}
+ htmlFor={kind}
+ description={sticky
+ ? `How much of what lies behind a sticky note shows through it: 0% is see-through (default), 100% is solid. The note keeps its colour either way.`
+ : `How much of the canvas shows through a group frame: 0% is see-through (default), 100% is solid. The frame keeps its colour either way.`}
+ control={
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+ <NumberField
+ value={resolveCanvasBacking(value)}
+ min={CANVAS_BACKING_MIN}
+ max={CANVAS_BACKING_MAX}
+ step={10}
+ ariaLabel={label}
+ onChange={(v) => update({ [kind]: resolveCanvasBacking(v) })}
+ />
+ <span style={{ opacity: 0.6 }}>%</span>
+ </div>
+ }
+ />
+ )
+}
+
/** Applies to the ⌘M output and chat views and the editor's Markdown preview (@shared/markdown-font). */
function MarkdownFontRows(): React.JSX.Element {
const family = useSettings((s) => s.settings.markdownFontFamily)
@@ -538,6 +578,12 @@ export function AppearanceSection({ isActive }: { isActive: boolean }): React.JS
<SearchableRow {...ROWS.tabBarHeight}>
<TabBarHeightRow />
</SearchableRow>
+ <SearchableRow {...ROWS.stickyNoteBacking}>
+ <CanvasBackingRow kind="stickyNoteBacking" />
+ </SearchableRow>
+ <SearchableRow {...ROWS.groupFrameBacking}>
+ <CanvasBackingRow kind="groupFrameBacking" />
+ </SearchableRow>
<MarkdownFontRows />
<SearchableRow {...ROWS.accent}>
<div className="flex items-center justify-between gap-4 py-2.5">
diff --git a/src/renderer/lib/settingsReset.test.ts b/src/renderer/lib/settingsReset.test.ts
index d2a2c3ffc..ee802bf9a 100644
--- a/src/renderer/lib/settingsReset.test.ts
+++ b/src/renderer/lib/settingsReset.test.ts
@@ -31,6 +31,15 @@ describe('reset key lists', () => {
// Deliberate exclusion: the terminal renders with it, but it belongs to the tmux section, and
// resetting a scrollback limit from an appearance button would be a surprise.
+ // Issue #1113: the note/frame backing sliders sit in the Appearance section, so its reset owns
+ // them — otherwise "Reset appearance" leaves an 80% backing behind and reads as pristine.
+ it('claims the sticky-note and group-frame backing', () => {
+ expect(APPEARANCE_RESET_KEYS).toContain('stickyNoteBacking')
+ expect(APPEARANCE_RESET_KEYS).toContain('groupFrameBacking')
+ const touched: Settings = { ...DEFAULT_SETTINGS, stickyNoteBacking: 80 }
+ expect(isPristine(APPEARANCE_RESET_KEYS, touched)).toBe(false)
+ })
+
it('does not claim tmuxScrollback', () => {
expect(TERMINAL_RESET_KEYS).not.toContain('tmuxScrollback')
})
diff --git a/src/renderer/lib/settingsReset.ts b/src/renderer/lib/settingsReset.ts
index 3edbae6e3..1fd1a1558 100644
--- a/src/renderer/lib/settingsReset.ts
+++ b/src/renderer/lib/settingsReset.ts
@@ -47,7 +47,9 @@ export const APPEARANCE_RESET_KEYS = [
'canvasDots',
'glassTint',
'glassBlurWhileMoving',
- 'windowTitleActiveSession'
+ 'windowTitleActiveSession',
+ 'stickyNoteBacking',
+ 'groupFrameBacking'
] as const satisfies readonly (keyof Settings)[]
/** The defaults for `keys`, as a patch for `useSettings.update`. */
diff --git a/src/renderer/nodes/GroupNode.tsx b/src/renderer/nodes/GroupNode.tsx
index b9bb8028b..436a3c9a0 100644
--- a/src/renderer/nodes/GroupNode.tsx
+++ b/src/renderer/nodes/GroupNode.tsx
@@ -10,6 +10,8 @@ import { useWorktrees, WORKTREE_STATUS_POLL_MS } from '../state/worktrees'
import { useSession } from '../session/session'
import { useGitBranch } from '../state/gitBranches'
import { useProjectSetup } from '../state/projectSetup'
+import { useSettings } from '../state/settings'
+import { backedFillStyle } from '@shared/canvas-backing'
export type WorktreeAction = 'merge' | 'remove' | 'unbind' | 'rerun-setup'
@@ -35,6 +37,8 @@ export function setWorktreeActionHandler(
export function GroupNode({ id, data, selected }: NodeProps<CanvasNode>) {
const { updateNodeData, setNodes } = useReactFlow()
const [showColors, setShowColors] = useState(false)
+ // Settings → Appearance → Group frame background (issue #1113); 0 = the old see-through look.
+ const backing = useSettings((s) => s.settings.groupFrameBacking)
// The frame element, observed for viewport visibility by the worktree-status tick below.
const frameRef = useRef<HTMLDivElement | null>(null)
@@ -157,7 +161,8 @@ export function GroupNode({ id, data, selected }: NodeProps<CanvasNode>) {
className={frameClass}
style={{
borderColor: bound && stale ? undefined : data.color,
- background: bound && stale ? undefined : `${data.color}${bound ? '1c' : '0f'}`,
+ // A stale worktree frame keeps its CSS look; everything else gets the tint (+ backing).
+ ...(bound && stale ? {} : backedFillStyle(data.color, bound ? '1c' : '0f', backing)),
// Rounded selection ring (box-shadow follows border-radius, unlike the resizer line).
boxShadow: selected ? `0 0 0 1.5px ${data.color}` : undefined
}}
diff --git a/src/renderer/nodes/StickyNode.tsx b/src/renderer/nodes/StickyNode.tsx
index 430e977c2..b204c8b91 100644
--- a/src/renderer/nodes/StickyNode.tsx
+++ b/src/renderer/nodes/StickyNode.tsx
@@ -8,6 +8,8 @@ import { NodeColorSwatches } from '../components/NodeColorSwatches'
import { ColumnPill } from '../components/kanban/ColumnPill'
import { NoteMarkdown } from '../components/NoteMarkdown'
import { relativeTime } from '../lib/relativeTime'
+import { useSettings } from '../state/settings'
+import { backedFillStyle } from '@shared/canvas-backing'
/**
* A sticky note node: a colored, resizable card with free-text content.
@@ -16,6 +18,8 @@ import { relativeTime } from '../lib/relativeTime'
export function StickyNode({ id, data, selected }: NodeProps<CanvasNode>) {
const { updateNodeData, deleteElements, setNodes } = useReactFlow()
const [showColors, setShowColors] = useState(false)
+ // Settings → Appearance → Sticky note background (issue #1113); 0 = the old see-through look.
+ const backing = useSettings((s) => s.settings.stickyNoteBacking)
/**
* The title is a plain SPAN until it is clicked, exactly as on a terminal node.
*
@@ -55,7 +59,7 @@ export function StickyNode({ id, data, selected }: NodeProps<CanvasNode>) {
<ColumnPill nodeId={id} />
<div
className={`sticky-node${selected ? ' selected' : ''}${collapsed ? ' collapsed' : ''}`}
- style={{ background: `${data.color}22`, borderColor: data.color }}
+ style={{ ...backedFillStyle(data.color, '22', backing), borderColor: data.color }}
>
<NodeResizer minWidth={NODE_MIN_SIZES.sticky.width} minHeight={NODE_MIN_SIZES.sticky.height} isVisible={selected && !collapsed} color={data.color} />
diff --git a/src/renderer/nodes/canvas-backing.wiring.test.tsx b/src/renderer/nodes/canvas-backing.wiring.test.tsx
new file mode 100644
index 000000000..183273ba8
--- /dev/null
+++ b/src/renderer/nodes/canvas-backing.wiring.test.tsx
@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+//
+// Issue #1113: Settings → Appearance → Sticky note / Group frame background reaches the node
+// bodies, and at the default (0) the inline background is the original tint, unchanged.
+import { act } from 'react'
+import { createRoot } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { NodeTerminalApi } from '@shared/types'
+import { SessionProvider, type WorkspaceSession } from '../session/session'
+import { useSettings } from '../state/settings'
+
+vi.mock('@xyflow/react', () => ({
+ NodeResizer: () => null,
+ Handle: () => null,
+ Position: { Left: 'left', Right: 'right' },
+ useReactFlow: () => ({ updateNodeData: vi.fn(), setNodes: vi.fn(), deleteElements: vi.fn() })
+}))
+
+import { GroupNode } from './GroupNode'
+import { StickyNode } from './StickyNode'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+const session: WorkspaceSession = {
+ id: 'fixture', source: 'local', label: 'fixture', status: 'connected',
+ api: { git: {} } as NodeTerminalApi
+}
+
+function render(el: JSX.Element): { host: HTMLDivElement; unmount: () => void } {
+ const host = document.createElement('div')
+ document.body.append(host)
+ const root = createRoot(host)
+ act(() => root.render(<SessionProvider session={session}>{el}</SessionProvider>))
+ return { host, unmount: () => act(() => root.unmount()) }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- React Flow is mocked away
+const props = (data: Record<string, unknown>): any =>
+ ({ id: 'n1', data: { title: 't', color: '#336699', ...data }, selected: false })
+
+afterEach(() => {
+ useSettings.setState((s) => ({ settings: { ...s.settings, stickyNoteBacking: 0, groupFrameBacking: 0 } }))
+})
+
+describe('canvas backing wiring', () => {
+ it('sticky note: old tint at 0, canvas backing under the tint when set', () => {
+ const { host, unmount } = render(<StickyNode {...props({ text: 'hi' })} />)
+ const el = host.querySelector<HTMLElement>('.sticky-node')!
+ expect(el.style.background).toContain('rgba(51, 102, 153, 0.133')
+ expect(el.style.backgroundColor).not.toContain('color-mix')
+ act(() => useSettings.setState((s) => ({ settings: { ...s.settings, stickyNoteBacking: 80 } })))
+ expect(el.style.backgroundColor).toContain('var(--canvas-bg) 80%')
+ expect(el.style.backgroundImage).toContain('linear-gradient')
+ unmount()
+ })
+
+ it('group frame: old tint at 0, canvas backing under the tint when set', () => {
+ const { host, unmount } = render(<GroupNode {...props({})} />)
+ const el = host.querySelector<HTMLElement>('.group-node')!
+ expect(el.style.background).toContain('rgba(51, 102, 153, 0.06)')
+ act(() => useSettings.setState((s) => ({ settings: { ...s.settings, groupFrameBacking: 50 } })))
+ expect(el.style.backgroundColor).toContain('var(--canvas-bg) 50%')
+ unmount()
+ })
+})
diff --git a/src/shared/canvas-backing.test.ts b/src/shared/canvas-backing.test.ts
new file mode 100644
index 000000000..a2c7940f4
--- /dev/null
+++ b/src/shared/canvas-backing.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { CANVAS_BACKING_DEFAULT, backedFillStyle, resolveCanvasBacking } from './canvas-backing'
+import { DEFAULT_SETTINGS } from './types'
+
+describe('resolveCanvasBacking (issue #1113)', () => {
+ it('defaults to 0 (today\'s see-through look) for anything that is not a finite number', () => {
+ for (const bad of [undefined, null, 'x', NaN, Infinity, {}, [50]])
+ expect(resolveCanvasBacking(bad)).toBe(CANVAS_BACKING_DEFAULT)
+ expect(CANVAS_BACKING_DEFAULT).toBe(0)
+ })
+ it('clamps to 0–100 and rounds', () => {
+ expect(resolveCanvasBacking(-20)).toBe(0)
+ expect(resolveCanvasBacking(140)).toBe(100)
+ expect(resolveCanvasBacking(42.6)).toBe(43)
+ })
+ it('ships both settings at the default', () => {
+ expect(DEFAULT_SETTINGS.stickyNoteBacking).toBe(0)
+ expect(DEFAULT_SETTINGS.groupFrameBacking).toBe(0)
+ })
+})
+
+describe('backedFillStyle', () => {
+ it('is byte-identical to the old inline style at the default', () => {
+ expect(backedFillStyle('#ff0000', '22', 0)).toEqual({ background: '#ff000022' })
+ expect(backedFillStyle('#ff0000', '0f', 'junk')).toEqual({ background: '#ff00000f' })
+ })
+ it('keeps the tint and puts a canvas-coloured backing under it', () => {
+ expect(backedFillStyle('#ff0000', '22', 60)).toEqual({
+ backgroundColor: 'color-mix(in srgb, var(--canvas-bg) 60%, transparent)',
+ backgroundImage: 'linear-gradient(#ff000022, #ff000022)'
+ })
+ })
+})
diff --git a/src/shared/canvas-backing.ts b/src/shared/canvas-backing.ts
new file mode 100644
index 000000000..a8c1458fa
--- /dev/null
+++ b/src/shared/canvas-backing.ts
@@ -0,0 +1,39 @@
+// How see-through group frames and sticky notes are (issue #1113, Settings → Appearance).
+//
+// Both kinds paint a faint tint of their colour (a note ~13%, a frame ~6%) straight over the
+// canvas, so a note inside a frame — or over a terminal, an edge, another note — shows everything
+// behind it through two thin washes and reads badly. The setting does NOT change the tint (the
+// colour still means what it meant); it adds a BACKING of the canvas colour under the tint, from
+// 0% (no backing: exactly the old look, the default) to 100% (solid: nothing behind shows).
+//
+// Machine-local and hand-editable, so every reader goes through `resolveCanvasBacking`.
+
+export const CANVAS_BACKING_MIN = 0
+export const CANVAS_BACKING_MAX = 100
+/** 0 = no backing = the look every existing user already has. */
+export const CANVAS_BACKING_DEFAULT = 0
+
+/** A percentage, clamped to 0–100 and rounded; anything not a finite number is the default. */
+export function resolveCanvasBacking(value: unknown): number {
+ if (typeof value !== 'number' || !Number.isFinite(value)) return CANVAS_BACKING_DEFAULT
+ return Math.round(Math.min(CANVAS_BACKING_MAX, Math.max(CANVAS_BACKING_MIN, value)))
+}
+
+export type BackedFillStyle =
+ | { background: string }
+ | { backgroundColor: string; backgroundImage: string }
+
+/**
+ * The inline background for a tinted node body. `color` is the node's hex colour and `alphaHex`
+ * the tint's two-digit alpha suffix (today's `${color}22` / `${color}0f`). At backing 0 the result
+ * is the old `background` value byte for byte; above it the tint is layered over the canvas colour.
+ */
+export function backedFillStyle(color: string, alphaHex: string, backing: unknown): BackedFillStyle {
+ const tint = `${color}${alphaHex}`
+ const b = resolveCanvasBacking(backing)
+ if (b === 0) return { background: tint }
+ return {
+ backgroundColor: `color-mix(in srgb, var(--canvas-bg) ${b}%, transparent)`,
+ backgroundImage: `linear-gradient(${tint}, ${tint})`
+ }
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index d578be792..c699d0a68 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1894,6 +1894,11 @@ export interface Settings {
* the default for anything that is not a finite number. Machine-local: it is one person's
* chrome, not a canvas fact. */
tabBarHeight: number
+ /** How solid sticky notes / group frames are behind their colour tint, 0–100 (Settings →
+ * Appearance, issue #1113). 0 = see-through, the original look. Hand-editable; read through
+ * `resolveCanvasBacking` (@shared/canvas-backing). Machine-local. */
+ stickyNoteBacking: number
+ groupFrameBacking: number
/** Font of the rendered-Markdown reading views — the ⌘M output and chat views and the editor's
* Markdown preview (Settings → Appearance). A CSS font stack. Hand-editable; read through
* `resolveMarkdownFontFamily` (@shared/markdown-font). Code inside Markdown follows the
@@ -2409,6 +2414,8 @@ export const DEFAULT_SETTINGS: Settings = {
snapToGrid: false,
autoAlignGrid: false,
tabBarHeight: TABBAR_HEIGHT_PX,
+ stickyNoteBacking: 0,
+ groupFrameBacking: 0,
markdownFontFamily: DEFAULT_MARKDOWN_FONT_FAMILY,
markdownFontSize: DEFAULT_MARKDOWN_FONT_SIZE,
defaultNodeWidth: 640,