Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
b83f3c1
cmux-next: glass over art keeps main text readable, like iOS, and sho…
teamleaderleo Oct 18, 2026
88cbefa
Merge remote-tracking branch 'origin/feat-cmux-next' into leo/next-gl…
teamleaderleo Oct 18, 2026
5679f79
cmux-next: glass legibility is set once for every window, from the ro…
teamleaderleo Oct 18, 2026
f34aba4
cmux-next: glass legibility setting is a struct; page text comment ma…
teamleaderleo Oct 18, 2026
063618a
Merge remote-tracking branch 'origin/feat-cmux-next' into leo/next-gl…
teamleaderleo Oct 18, 2026
df0a389
Merge remote-tracking branch 'origin/feat-cmux-next' into leo/next-gl…
teamleaderleo Oct 19, 2026
8f50a90
chore(next): PR autofix at df0a389e5726
Oct 19, 2026
b1de7fb
Merge remote-tracking branch 'origin/feat-cmux-next' into rescue/next…
teamleaderleo Oct 19, 2026
a3e25a8
Keep the Glass Over Art entry in the settings schema export after the…
teamleaderleo Oct 19, 2026
0d69ea8
Merge remote-tracking branch 'origin/feat-cmux-next' into rescue/next…
teamleaderleo Oct 19, 2026
9455e39
chore(next): PR autofix at 0d69ea801b9b
Oct 19, 2026
8a5ba0b
Merge remote-tracking branch 'origin/feat-cmux-next' into rescue/next…
teamleaderleo Oct 19, 2026
fd09552
Merge remote-tracking branch 'origin/feat-cmux-next' into rescue/next…
teamleaderleo Oct 19, 2026
284a488
chore(next): PR autofix at fd0955280eb9
Oct 19, 2026
e2e2a0d
Merge remote-tracking branch 'origin/feat-cmux-next' into rescue/next…
teamleaderleo Oct 19, 2026
654b0dc
Merge remote-tracking branch 'origin/feat-cmux-next' into rescue/next…
teamleaderleo Oct 19, 2026
9e7b17b
next: Glass Over Art lives on the theme scopes, not a global lock
teamleaderleo Oct 19, 2026
9863aec
Merge remote-tracking branch 'origin/feat-cmux-next' into rescue/next…
teamleaderleo Oct 19, 2026
7a78e5e
chore(next): PR autofix at 9863aec4efff
Oct 19, 2026
57f6a05
Merge origin/feat-cmux-next into leo/next-glass-legibility
teamleaderleo Oct 20, 2026
4e118ef
Merge branch 'feat-cmux-next' into leo/next-glass-legibility
teamleaderleo Oct 20, 2026
b90e7cb
Merge origin/feat-cmux-next into leo/next-glass-legibility
teamleaderleo Oct 20, 2026
de8268d
chore(next): PR autofix at b90e7cb7ac3b
Oct 20, 2026
b0f5c17
Merge origin/feat-cmux-next into leo/next-glass-legibility
teamleaderleo Oct 20, 2026
8a8dfc0
Merge branch 'feat-cmux-next' into leo/next-glass-legibility
teamleaderleo Oct 20, 2026
1dd9656
Merge remote-tracking branch 'origin/leo/next-glass-legibility' into …
teamleaderleo Oct 20, 2026
a7ba4bb
Merge branch 'feat-cmux-next' into leo/next-glass-legibility
teamleaderleo Oct 20, 2026
ed2a8c7
test(next): Settings' unset Opacity slider follows Glass Over Art
teamleaderleo Oct 20, 2026
3baba45
fix(next): Settings' unset Opacity slider rests on the Glass Over Art…
teamleaderleo Oct 20, 2026
22dbdc9
chore(next): PR autofix at 3baba45398d5
Oct 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -380,7 +380,7 @@ final class WindowRootView: NSView, WindowSurfacePainting {
var backdrop: WindowBackdrop {
WindowBackdrop(themeTokens, reduceTransparency: reduceTransparency(), art: themeScope.backdropArt,
selection: themeScope.backdropSelection, tuning: themeScope.appearanceTuning,
tintOpacity: themeScope.backdropTintOpacity)
tintOpacity: themeScope.backdropTintOpacity, legibility: themeScope.artLegibility)
}

/// An opaque window paints the solid background on this layer. Over a
Expand Down
12 changes: 12 additions & 0 deletions Packages/macOS/CmuxNext/Sources/CmuxNextDesign/ArtLegibility.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
/// Which text the window's glass keeps readable over background art (`appearance.glassLegibility`).
/// The glass's tint never goes below the least opacity at which these roles keep their contrast
/// over the art (``BackdropArtRange``), so this decides how much of the art shows. The live choice
/// lives on the theme scopes (``ThemeScope/artLegibility``).
public nonisolated enum ArtLegibility: String, CaseIterable, Sendable {
/// Primary text at WCAG AA body contrast, as iOS glass does over a wallpaper: secondary and
/// tertiary text may read below their contrast over the art's brightest or darkest parts, and
/// much more of the art shows (Leo 2026-10-18: "IOS IOS").
case primary
/// Every text role at its contrast over any part of the art: denser glass.
case all
}
Original file line number Diff line number Diff line change
Expand Up @@ -47,16 +47,19 @@ public nonisolated struct BackdropArtRange: Sendable, Equatable {
}

public nonisolated extension ThemeTokens {
/// The text roles with the contrast each needs over art: primary and secondary text at WCAG
/// AA body contrast, tertiary text and status marks at the mark contrast.
var backdropTexts: [(color: ThemeRGB, contrast: Double)] {
[(textPrimary, Self.minimumTextContrast), (textSecondary, Self.minimumTextContrast),
(textTertiary, Self.minimumMarkContrast)]
/// The text roles with the contrast each needs over art: primary text at WCAG AA body
/// contrast, and with ``ArtLegibility/all`` secondary text at it too and tertiary text and
/// status marks at the mark contrast.
func backdropTexts(_ legibility: ArtLegibility) -> [(color: ThemeRGB, contrast: Double)] {
let primary = [(color: textPrimary, contrast: Self.minimumTextContrast)]
guard legibility == .all else { return primary }
return primary + [(textSecondary, Self.minimumTextContrast), (textTertiary, Self.minimumMarkContrast)]
}

/// The least window tint over `art`, at or above `requested`, that keeps ``backdropTexts``
/// legible on the surface color.
func legibleTintOpacity(over art: BackdropArtRange = .any, requested: Double) -> Double {
art.scrimOpacity(texts: backdropTexts, scrim: surfaceBackground.withAlpha(1), requested: requested)
/// The least window tint over `art`, at or above `requested`, that keeps
/// ``backdropTexts(_:)`` legible on the surface color.
func legibleTintOpacity(over art: BackdropArtRange = .any, requested: Double,
legibility: ArtLegibility) -> Double {
art.scrimOpacity(texts: backdropTexts(legibility), scrim: surfaceBackground.withAlpha(1), requested: requested)
Comment on lines +61 to +63

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Tint adjustments lower text contrast

With experimental appearance enabled, appearance.saturation: 0 and appearance.glassTransparency: 1, the new primary-only floor can leave primary text below its promised contrast. The floor uses the original surfaceBackground, but WindowMaterialView paints a tint with changed saturation.

For ghosttyDefault over Hokusai, the new floor is 0.63. The gray tint gives white primary text about 4.19:1 contrast over the lightest art color, below 4.5:1. The old all-text floor keeps it above 4.5:1.

Compute the floor from the tint color that will actually be painted, and cover this combination in a test.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

}
}
17 changes: 16 additions & 1 deletion Packages/macOS/CmuxNext/Sources/CmuxNextDesign/ThemeScope.swift
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,10 @@ public final class ThemeScope {
/// Plain glass here even when an ancestor has art (``pinBackdrop(_:)``).
private var pinsNoBackdrop = false
private var selectedAppearanceTuning: AppearanceTuning?
/// The text the glass keeps readable over art (`appearance.glassLegibility`), inherited like
/// art: the settings set it on ``app``.
public var artLegibility: ArtLegibility { selectedArtLegibility ?? parent?.artLegibility ?? .primary }
private var selectedArtLegibility: ArtLegibility?
/// The user's per-surface backgrounds (`appearance.surfaces`), inherited
/// like art: one app-wide setting, read by every surface's owner through
/// `Palette.fill(for:)`.
Expand Down Expand Up @@ -106,6 +110,16 @@ public final class ThemeScope {
}
}

/// Changes which text the glass keeps readable over art (``ArtLegibility``) here and in the
/// descendants that inherit it, and repaints them: the tint floor over art moves with it.
public func setArtLegibility(_ legibility: ArtLegibility) {
ThemeRepaint.batch {
guard selectedArtLegibility != legibility else { return }
selectedArtLegibility = legibility
repaintBackdropArt()
}
}

/// Changes live tuning without changing theme colors or persisted settings.
public func setAppearanceTuning(_ tuning: AppearanceTuning) {
ThemeRepaint.batch {
Expand Down Expand Up @@ -133,14 +147,15 @@ public final class ThemeScope {
var tint: Double?
var surfaces: SurfaceBackgrounds
var tuning: AppearanceTuning
var legibility: ArtLegibility
}
private var displayedBackdrop: BackdropKey?

/// Repaints this scope's views for a background change, then each child whose inherited
/// background changed with it (a child with its own pick keeps its views as they are).
private func repaintBackdropArt(force: Bool = true) {
let key = BackdropKey(selection: backdropSelection, tint: backdropTintOpacity,
surfaces: surfaceBackgrounds, tuning: appearanceTuning)
surfaces: surfaceBackgrounds, tuning: appearanceTuning, legibility: artLegibility)
guard force || key != displayedBackdrop else { return }
displayedBackdrop = key
// Art Color: another work is another accent.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ public extension WindowBackdrop {
/// scope's art selection (the app's outside a scope), so over art the panes stay clear glass
/// and the art reads through the window's one legible tint.
@MainActor static func current(_ tokens: ThemeTokens, reduceTransparency: Bool = false) -> WindowBackdrop {
WindowBackdrop(tokens, reduceTransparency: reduceTransparency, selection: ThemeContext.activeBackdropSelection)
// Glass Over Art is one app-wide setting (`appearance.glassLegibility`), set on the app scope.
WindowBackdrop(tokens, reduceTransparency: reduceTransparency, selection: ThemeContext.activeBackdropSelection,
legibility: ThemeScope.app.artLegibility)
}
}

Expand All @@ -15,7 +17,8 @@ public extension ThemeScope {
var shownWindowOpacity: Double {
guard backdropSelection != nil else { return input.backgroundOpacity }
let backdrop = WindowBackdrop(tokens, art: backdropArt, selection: backdropSelection,
tuning: appearanceTuning, tintOpacity: backdropTintOpacity)
tuning: appearanceTuning, tintOpacity: backdropTintOpacity,
legibility: artLegibility)
return backdrop.isOpaque ? input.backgroundOpacity : backdrop.tintOpacity
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ public nonisolated struct WindowBackdrop: Equatable, Sendable {
public var art: BackdropArt? = nil
/// Optional bundled or system image beneath the material.
public var selection: BackdropSelection? = nil
/// The least tint over art at which every text role stays legible
/// (``ThemeTokens/legibleTintOpacity(over:requested:)``); 0 without art. Neither the opacity setting
/// The least tint over art at which the text the scope's ``ArtLegibility`` names stays legible
/// (``ThemeTokens/legibleTintOpacity(over:requested:legibility:)``); 0 without art. Neither the opacity setting
/// nor the tuner thins the glass below it.
public var legibleTintOpacity: Double = 0
/// The art's own opacity: 1, or ``windowGlassArtOpacity`` under Window Glass (the Clear Glass
Expand Down Expand Up @@ -101,9 +101,11 @@ public nonisolated struct WindowBackdrop: Equatable, Sendable {
/// - Parameter art: Bundled art below the window's material and tint.
/// - Parameter tintOpacity: A workspace's own tint over art (`ThemeScope.backdropTintOpacity`),
/// replacing the work's and the window's; the legibility floor still applies.
/// - Parameter legibility: The text the floor keeps readable over art (`ThemeScope.artLegibility`).
public init(_ tokens: ThemeTokens, reduceTransparency: Bool = false, art: BackdropArt? = nil,
selection: BackdropSelection? = nil, tuning: AppearanceTuning = .identity,
texture: BackdropTexture = .default, tintOpacity workspaceTint: Double? = nil) {
texture: BackdropTexture = .default, tintOpacity workspaceTint: Double? = nil,
legibility: ArtLegibility = .primary) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Opacity slider understates window tint

shownWindowOpacity still calls WindowBackdrop without legibility: artLegibility. With All Text selected and the contrast floor setting the window’s tint, that call uses the new .primary default and reports a lower opacity than the window paints. Settings uses that result for the unset Opacity slider, so its automatic value can be misleading. Pass the scope’s choice through that call too.

let resolvedSelection = selection ?? art.map(BackdropSelection.art)
// A work's own tint replaces the theme's (dark works show more of themselves); the
// legibility floor below still keeps text readable over it.
Expand All @@ -123,7 +125,7 @@ public nonisolated struct WindowBackdrop: Equatable, Sendable {
if windowGlass { artOpacity = Self.windowGlassArtOpacity }
if resolvedSelection != nil, !isOpaque {
let range = windowGlass ? .any : resolvedSelection?.artRange ?? .any
legibleTintOpacity = tokens.legibleTintOpacity(over: range, requested: 0)
legibleTintOpacity = tokens.legibleTintOpacity(over: range, requested: 0, legibility: legibility)
tintOpacity = max(tintOpacity, legibleTintOpacity)
}
self.art = art
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ public final class WindowSurfaceView: NSView, WindowSurfacePainting {
public func backdrop(in window: NSWindow) -> WindowBackdrop {
WindowBackdrop(window.themeScope.tokens, reduceTransparency: reduceTransparency(), art: window.themeScope.backdropArt,
selection: window.themeScope.backdropSelection, tuning: window.themeScope.appearanceTuning,
tintOpacity: window.themeScope.backdropTintOpacity)
tintOpacity: window.themeScope.backdropTintOpacity, legibility: window.themeScope.artLegibility)
}

public func paintWindowSurface(of window: NSWindow) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,8 @@ public struct CmuxConfigSnapshot: Sendable, Equatable {
public var backdropSelection: BackdropSelection? = BackdropSelectionSetting.defaultSelection
/// `appearance.experimentalControls`; off unless explicitly enabled.
public var experimentalAppearance = false
/// `appearance.glassLegibility`; "primary" when unset or invalid.
public var glassLegibility = GlassLegibilitySetting.fallback
/// `appearance.glassTransparency`, `appearance.hue` and
/// `appearance.saturation`; identity values when unset or invalid.
public var appearanceTuning = AppearanceTuningSetting.fallback
Expand Down Expand Up @@ -280,6 +282,7 @@ public struct CmuxConfigSnapshot: Sendable, Equatable {
if case .art(let art) = snapshot.backdropSelection { snapshot.backdropArt = art } else { snapshot.backdropArt = nil }
snapshot.experimentalAppearance = ExperimentalAppearanceSetting().parse(root, diagnostics: &snapshot.diagnostics)
snapshot.appearanceTuning = AppearanceTuningSetting.parse(root, diagnostics: &snapshot.diagnostics)
snapshot.take(GlassLegibilitySetting().parse(root), \.glassLegibility)
snapshot.statusIndicator = StatusIndicatorConfigParser.parse(root, diagnostics: &snapshot.diagnostics)
DiffViewerSetting.parse(root, diagnostics: &snapshot.diagnostics)
ChatSettings.validate(root, diagnostics: &snapshot.diagnostics)
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
public import CmuxNextDesign

/// `appearance.glassLegibility` in cmux.json: "primary" (default) or "all", the text the window's
/// glass keeps readable over background art (``ArtLegibility``).
public nonisolated struct GlassLegibilitySetting {
public nonisolated init() {}
public static let configPath = ["appearance", "glassLegibility"]
public static let fallback: ArtLegibility = .primary

/// A missing key is the default with no diagnostic; a bad value is the default plus a diagnostic.
func parse(_ root: JSONValue) -> (ArtLegibility, SettingsDiagnostic?) {
guard let value = root.value(at: Self.configPath) else { return (Self.fallback, nil) }
guard let text = value.stringValue, let legibility = ArtLegibility(rawValue: text) else {
let choices = ArtLegibility.allCases.map { "\"\($0.rawValue)\"" }.joined(separator: ", ")
return (Self.fallback, SettingsDiagnostic(kind: .invalidValue, path: "appearance.glassLegibility",
message: "expected one of \(choices)"))
}
return (legibility, nil)
}
}
Loading