Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

83.4 KB
Raw Blame
import 'package:flutter/material.dart';
import 'package:harness/terminal/terminal_text.dart';

import 'app_type.dart';
export 'app_type.dart';
import 'color_palette.dart';

/// The app's live brightness — the single source of truth the color tokens below
/// resolve against. The palette decides it: `_GridTokenScope` (in
/// `app_shell.dart`) sets this from [palette]'s own brightness, so a light
/// palette ([HarnessPalette.paper], [HarnessPalette.mist]) is a light app.
///
/// Every `AppPalette`/`AppSurface`/`AppGlass`/`AppCard` member is a getter that
/// switches on this, so a call site like `color: AppPalette.windowBg` follows the
/// theme with no change to the call site.
abstract final class AppTheme {
  static final BrightnessNotifier brightness = BrightnessNotifier(
    Brightness.dark,
  );

  static final palette = ValueNotifier(HarnessPalette.graphite);

  static bool get isDark => brightness.value == Brightness.dark;

  /// A theme preview can request the opposite brightness without changing the
  /// saved palette. Keep its surface and foreground on the same light/dark ramp.
  static HarnessPalette paletteFor(Brightness value) =>
      palette.value.brightness == value
      ? palette.value
      : value == Brightness.dark
      ? HarnessPalette.graphite
      : HarnessPalette.paper;

  static HarnessPalette get surfacePalette => paletteFor(brightness.value);

  /// Pick between a light and a dark value for the current brightness.
  static T pick<T>(T light, T dark) => isDark ? dark : light;

  /// Read tokens as some *other* brightness would resolve them.
  ///
  /// The tokens resolve against one global ([brightness]), which is what makes a
  /// call site like `AppPalette.windowBg` follow the theme with no plumbing — but
  /// it also means the dark palette is unreadable while the app is light. The
  /// theme preview needs exactly that: three swatches, each showing a palette the
  /// app is *not* currently wearing.
  ///
  /// So: swap the global, read, put it back. Safe because it's synchronous and
  /// restores in a `finally` — nothing can observe the swapped value, and the
  /// swap is [BrightnessNotifier.muted] so it doesn't dirty every widget
  /// watching the theme on the way out and back.
  ///
  /// Do not `await` inside [read]: that would hand the swapped brightness to the
  /// rest of the frame, and the app would paint half a palette.
  static T as<T>(Brightness other, T Function() read) {
    final previous = brightness.value;
    if (previous == other) return read();
    return brightness.muted(() {
      try {
        brightness.value = other;
        return read();
      } finally {
        brightness.value = previous;
      }
    });
  }

  /// Registers the calling widget to rebuild whenever [brightness] flips, and
  /// returns the current value.
  ///
  /// The color tokens read [brightness] `.value` directly — a plain field read
  /// the element tree can't see — so a widget that only reads tokens has no
  /// tracked reason to rebuild when the theme changes. Worse, the app is full of
  /// `const` chrome (`const AppSidebar()`, `const _MainShellBody()`), and a
  /// `const` child is reference-identical across a parent's rebuild, so Flutter
  /// short-circuits it: rebuilding from the top never reaches the sidebar, and it
  /// stays on the old palette until something *else* (a Riverpod change from
  /// clicking a row) happens to rebuild it.
  ///
  /// Calling this at the top of a chrome widget's `build` fixes that at the root:
  /// it depends on the [_BrightnessScope] inherited widget, whose notifier is
  /// [brightness]. An `InheritedNotifier` marks its dependents dirty *directly*
  /// when the notifier fires — it doesn't rebuild through the widget tree — so
  /// every `const` boundary in between is irrelevant. This is exactly how
  /// `Theme.of(context)` makes a widget follow the theme.
  /// It also registers for type changes, via [TerminalFontScope]. The two travel
  /// together deliberately: `AppTheme.watch(context)` is the one line a widget
  /// adds to follow the app's appearance, and splitting it into two calls would
  /// mean every widget that already follows the theme still silently ignores the
  /// font — with the exact same symptom (stuck on the value it first built with)
  /// that this method exists to fix.
  static Brightness watch(BuildContext context) {
    TerminalFontScope.watch(context);
    context.dependOnInheritedWidgetOfExactType<_BrightnessScope>();
    context.dependOnInheritedWidgetOfExactType<_PaletteScope>();
    return brightness.value;
  }
}

/// The brightness global, with one extra power: it can be moved *silently*.
///
/// [AppTheme.as] swaps the brightness to read the other palette and swaps it
/// straight back. A plain `ValueNotifier` broadcasts both of those moves, so
/// every widget watching the theme would be marked dirty twice per swatch — six
/// spurious rebuilds to draw three previews, all to end up back where we
/// started. [muted] suppresses the broadcast for a change that is, from the
/// outside, not a change at all.
class BrightnessNotifier extends ValueNotifier<Brightness> {
  BrightnessNotifier(super.value);

  bool _muted = false;

  /// Run [body] with notifications suppressed. Only for a swap that restores the
  /// original value before anything can observe it — see [AppTheme.as].
  T muted<T>(T Function() body) {
    final previous = _muted;
    _muted = true;
    try {
      return body();
    } finally {
      _muted = previous;
    }
  }

  @override
  void notifyListeners() {
    if (_muted) return;
    super.notifyListeners();
  }
}

/// Wraps the app so any descendant that calls [AppTheme.watch] rebuilds when the
/// brightness flips or the user's type settings change — regardless of the
/// `const` widgets in between. Mount it once, high in the tree (see
/// `grid_app.dart`).
///
/// The name predates the font settings and is kept: it's mounted in one place,
/// and every call site in the app already knows this as the widget that makes
/// [AppTheme.watch] work.
class BrightnessScope extends StatelessWidget {
  const BrightnessScope({super.key, required this.child});

  final Widget child;

  @override
  Widget build(BuildContext context) {
    return TerminalFontScope(
      child: _BrightnessScope(
        notifier: AppTheme.brightness,
        child: _PaletteScope(notifier: AppTheme.palette, child: child),
      ),
    );
  }
}

class _BrightnessScope extends InheritedNotifier<ValueNotifier<Brightness>> {
  const _BrightnessScope({required super.notifier, required super.child});
}

class _PaletteScope extends InheritedNotifier<ValueNotifier<HarnessPalette>> {
  const _PaletteScope({required super.notifier, required super.child});
}

/// The app's palette — a warm paper white with near-black ink in light, a deep
/// charcoal with off-white ink in dark (the design-system "Codex" direction).
/// Centralized so every pane reads the same surfaces/accents instead of re-typing
/// hex literals, and resolves per [AppTheme.brightness].
abstract final class AppPalette {
  // Approved Swarms canvas and native tab-strip palette.
  static Color get swarmField => AppTheme.surfacePalette.workspace;
  // Empty tabs join the selected native tab as one continuous surface.
  static Color get swarmWelcome => AppTheme.surfacePalette.workspace;
  static Color get swarmTabBar => AppTheme.surfacePalette.tabBar;
  static Color get swarmAccent => AppTheme.surfacePalette.accent;
  // Shared with the native search field for a continuous input/results surface.
  static Color get swarmSearchSurface => AppTheme.surfacePalette.search;
  // The Swarm's project sidebar: the workspace color, or a palette's own
  // (Plum's plum). Its ink is `SidebarInk`'s.
  static Color get swarmSidebar => AppTheme.surfacePalette.sidebar;
  // Getters, not consts: a light palette brings its own panel and card.
  static Color get agentEntrySurface =>
      AppTheme.pick(AppTheme.surfacePalette.panel, const Color(0xff101113));
  static Color get agentEntryField =>
      AppTheme.pick(AppTheme.surfacePalette.card, const Color(0xff1d1f22));
  // The command field deliberately stays light, like a browser's new-tab omnibox.
  static const commandField = Color(0xFFF7F8FA);
  static const commandInk = Color(0xFF202124);
  static const commandMuted = Color(0xFF646971);
  static const commandChip = Color(0xFFE9EBEF);

  // the conversation / content area — pure white in light, like Codex.
  //
  // Dark is a charcoal page rather than the near-black it was (#0A0A0A). That
  // moves every surface above it closer: a card lands at 1.065:1 where it had
  // 1.188, a dialog at 1.090 where it had 1.215, and [AppPalette.panelBg]
  // (#141414) is now *darker* than the page it sits on. Depth in dark is
  // therefore carried by the rim and the shadow, not by the fill — §2's stack
  // still holds, it just has less room to say it in.
  //
  // These four come from the palette in both themes: a light palette carries
  // its own light surfaces (color_palette.dart), and it is the palette that
  // decides the brightness in the first place.
  static Color get windowBg => AppTheme.surfacePalette.background;

  // sidebar column — a barely-there cool grey (Codex keeps the rail almost white,
  // set apart by a hairline, not a tone) / charcoal panel in dark.
  static Color get panelBg => AppTheme.surfacePalette.panel;

  // input fills, quiet cards
  static Color get cardBg => AppTheme.surfacePalette.card;

  static Color get cardBgHover => AppTheme.surfacePalette.hover;

  // A hairline separator. Light: a faint cool black; dark: a faint white — a
  // black divider would vanish on charcoal.
  static Color get divider =>
      AppTheme.pick(const Color(0x0F000000), const Color(0x14FFFFFF));

  /// A hairline that has to hold a *shape* rather than just part two blocks —
  /// the tree guide threading the sidebar's projects and their chats.
  ///
  /// Stronger than [divider], and deliberately so. A separator only has to be
  /// findable at the seam the eye is already looking at; a guide is a long thin
  /// run the eye has to follow, and at the divider's weight it stops reading as
  /// one line and breaks into stray ticks wherever anything crosses it.
  /// Measured against the rail it is drawn on (`AppGlass.sidebarFill`, over
  /// [windowBg] in light): divider lands at **1.14:1 light / 1.27:1 dark**,
  /// this at **1.45:1 light / 1.47:1 dark**.
  ///
  /// The two alphas differ because the rails differ — `#F9F9F8` light against
  /// `#242424` dark — and matching the *numbers* rather than the alphas is what
  /// keeps the guide equally present in both themes instead of a step fainter
  /// in light, which is how the divider's pair behaved.
  static Color get guide =>
      AppTheme.pick(const Color(0x29000000), const Color(0x20FFFFFF));

  // primary action — a solid fill with white text on it, so it has to stay dark
  // enough to carry that text (white on this is 5.5:1). Same value in both
  // themes: as a *fill* it reads on either surface.
  static const accent = Color(0xFF2F5BEA);

  /// The fill under a destructive **filled** button — Remove, Delete.
  ///
  /// Not `colorScheme.error`, and the reason is what that colour is *for*: dark's
  /// `#F2544B` is tuned to read as **ink on a dark surface**, which is why
  /// `AppIconButton` needs one lighter still. As a *fill* it leaves white
  /// lettering at 3.42:1, under the 4.5:1 floor — and Material's own `onError`
  /// substitute reaches only 3.83:1, so no foreground rescues it. Darkened until
  /// white clears the bar with the room the app's own accent button already has:
  ///
  /// ```
  ///                        white on fill   fill vs dialog
  /// accent   #2F5BEA           5.52             3.02
  /// this     #C92E26 (dark)    5.38             3.10
  /// this     #B3261E (light)   6.54             6.54
  /// ```
  static Color get dangerFill =>
      AppTheme.pick(const Color(0xFFB3261E), const Color(0xFFC92E26));

  /// Text and marks on [dangerFill], such as a sidebar's red count.
  static const Color onDangerFill = Colors.white;

  /// The accent as a *mark on a surface* — a selected row's icon, an accent
  /// rail — rather than a fill behind white text.
  ///
  /// It has to part from [accent] in dark. A selected rail row composites to
  /// #353535, and #2F5BEA on that is 2.2:1 — under the 3.0 WCAG 1.4.11 asks of
  /// a UI element, which is why the selected icon read as flat charcoal-on-
  /// charcoal there while light (4.6:1) was fine. Lightened to 3.97:1 on that
  /// row, still plainly the same indigo. [accent] can't simply take this value:
  /// it is the fill under white text in ~100 places, and lightening it there
  /// would drop that text to ~3.1:1 — fixing the icon by breaking the buttons.
  static Color get accentOnSurface => AppDesktop.focus;

  /// A quiet location cue around a focused remote pane. Desaturated separately
  /// from teal ink so a full perimeter stays subordinate to terminal content.
  /// Clears 3:1 against every built-in pane ground and workspace gutter.
  static Color get remotePaneFocus =>
      AppTheme.pick(const Color(0xFF567C77), const Color(0xFF6C9691));

  // avatar fill (white text on it); a touch brighter in dark for contrast.
  static Color get accentMuted =>
      AppTheme.pick(const Color(0xFF3550C8), const Color(0xFF4E6BF0));

  /// The initial tile beside a name in a roster — the accent's hue with most of
  /// its saturation taken out, so a column of ten of them reads as a list rather
  /// than as ten buttons.
  ///
  /// **Not [accent] or [accentMuted].** Both are made to be *loud*: one is the
  /// fill under a primary button, the other the base of the account avatar that
  /// marks **you**. A saturated indigo is right for one mark on a screen and
  /// wrong for a mark on every row — a whole panel of them pulled the eye off
  /// the names they were meant to introduce.
  ///
  /// Still a solid fill under white text, and still measured for it: 5.26:1 in
  /// light, 6.19:1 in dark. Softening a mark must not cost the letter inside it,
  /// which is the only part carrying information — a tint at 14% alpha would
  /// have taken the glyph to 4.5:1 at rest and under it on a hovered row.
  ///
  /// Slightly deeper in dark, where the tile stands on charcoal (2.63:1 against
  /// the panel) rather than on white (5.26:1).
  static Color get avatarFill =>
      AppTheme.pick(const Color(0xFF5369AC), const Color(0xFF4B5F9B));

  /// The colours a member's circle is drawn in, one per person — see
  /// `memberAvatarSlot`, which decides which of them an address takes.
  ///
  /// **The same list in both themes, deliberately.** Every other colour here
  /// resolves per brightness; this one must not, because here the colour *is*
  /// the identity. A person who is teal on the dark theme and green on the light
  /// one is two people to the eye, and the whole reason for colouring a roster
  /// is that a face can be found before it is read.
  ///
  /// Eight hues rather than a generated spread: a hash over a continuous wheel
  /// puts neighbouring people two degrees apart as often as not, and a palette
  /// picked by hand is the only way the marks stay *told apart*. All eight carry
  /// white at ≥5:1 (measured: 5.02 green → 7.10 violet), which is what the
  /// letter needs — the disc itself is a container, and lands at 2.3–3.5:1
  /// against the panels it sits on, the same band [avatarFill] occupies today.
  static const avatarPalette = <Color>[
    Color(0xFF1D5BD6), // blue
    Color(0xFF0F766E), // teal
    Color(0xFF15803D), // green
    Color(0xFFA65A08), // amber
    Color(0xFFBE123C), // rose
    Color(0xFF6D28D9), // violet
    Color(0xFFA21CAF), // fuchsia
    Color(0xFF4E5D78), // slate
  ];

  /// The primary action's fill under the pointer — the top bar's Invite button.
  ///
  /// **Deepens in light, brightens in dark**, rather than one shift applied to
  /// both: hover should raise the control's contrast against the page it sits
  /// on, and the page runs the other way in the other theme. The numbers force
  /// it too — the obvious "lift toward [AppCard.accentStrong]" puts dark on
  /// `#5C7CFF`, where the button's own white label falls to **3.63:1**. These
  /// two hold it at 6.50:1 (light) and 4.76:1 (dark).
  static Color get accentHover =>
      AppTheme.pick(const Color(0xFF2850D8), const Color(0xFF4166F2));

  // These three are drawn as TEXT as often as dots (status labels, ledger
  // rows), so their light values clear 4.5:1 on the deepest light-palette
  // ground they meet — Paper's search #E2E2DF / Mist's #DCE4EE — not only on
  // white: teal 4.90, online 5.02, warn 4.93 there (6.4–6.5 on white).

  // Teal ink for badges and labels — legible on either surface.
  static Color get teal =>
      AppTheme.pick(const Color(0xFF0D6B63), const Color(0xFF2DD4BF));

  // green "connected" dot
  static Color get online =>
      AppTheme.pick(const Color(0xFF146C34), const Color(0xFF3FB950));

  // expiring soon
  static Color get warn =>
      AppTheme.pick(const Color(0xFF9A4708), const Color(0xFFFFB020));

  /// A quiet allowance limit in workspace chrome, distinct from an app error.
  static Color get usageLow =>
      AppTheme.pick(const Color(0xFF87632A), const Color(0xFFC4A46C));

  /// Remaining subscription capacity is nearly exhausted (5% or less).
  static Color get usageCritical =>
      AppTheme.pick(const Color(0xFFB3261E), const Color(0xFFFF7068));

  // grey dot — a state mark, so ≥3:1 in light (3.14 on Paper's search ground).
  static Color get offline =>
      AppTheme.pick(const Color(0xFF7F7E78), const Color(0xFF6E6E6E));

  // Grid brand lightning gold — the live/active ⚡ mark, matching the tray bolt.
  // Light is a deeper gold than the tray's: #C98A00 was 2.27–2.95:1 on the
  // light grounds, this is 3.93 at worst.
  static Color get brandBolt =>
      AppTheme.pick(const Color(0xFF946500), const Color(0xFFE0A93B));

  /// The welcome tour's amber (approved onboarding render, 2026-10-08): the
  /// slide kicker, the current pager dot, the install bar and the
  /// illustrations' highlights. Only the tour uses it; it is not an action
  /// colour. Dark is the render's #FF9F0A (8.3:1 on the dark grounds); light is
  /// deepened to stay text: 4.95:1 on Paper's background, 4.6:1 on its panel.
  static Color get onboardingAccent =>
      AppTheme.pick(const Color(0xFFA65A08), const Color(0xFFFF9F0A));

  /// The tour's tagline gold, quieter than [onboardingAccent]. Light holds
  /// 4.8:1 on Paper's deepest ground; dark is the render's #D4A574.
  static Color get onboardingTagline =>
      AppTheme.pick(const Color(0xFF7D5A2C), const Color(0xFFD4A574));

  // A palette may bring its own three grays (Plum, Night, Cloud, Storm); the
  // rest share these ramps.
  static Color get textPrimary =>
      AppTheme.surfacePalette.text ??
      AppTheme.pick(const Color(0xFF1A1A18), const Color(0xFFF5F5F5));

  static Color get textSecondary =>
      AppTheme.surfacePalette.muted ??
      AppTheme.pick(const Color(0xFF62615B), const Color(0xFFA8A8A2));

  /// Meta text and hints. Light is #7A7973, not the #8E8D86 it was: that one
  /// was tuned for a white page and fell to 2.57:1 on Paper's search ground
  /// (#E2E2DF) and 2.60 on Mist's (#DCE4EE). This holds 3.36 / 3.40 there and
  /// 3.49 / 3.51 on the two workspaces, and stays 1.42:1 apart from
  /// [textSecondary] so the three steps still read as three.
  static Color get textFaint =>
      AppTheme.surfacePalette.faint ?? textFaintFor(isDark: AppTheme.isDark);

  /// [textFaint] for a theme being built, whose brightness need not be the
  /// current one. Every field's placeholder is this color.
  static Color textFaintFor({required bool isDark}) =>
      AppTheme.paletteFor(isDark ? Brightness.dark : Brightness.light).faint ??
      (isDark ? const Color(0xFF6E6E68) : const Color(0xFF7A7973));

  /// The page a document is drawn on, and the ink on it.
  ///
  /// The one pair here that does **not** follow the app's theme, deliberately: a
  /// page is the *document*, not the app's chrome. Word keeps dark chrome around
  /// white paper for the reason that decides it — what you edit has to look like
  /// what you send, and a page that turned charcoal in dark mode would show the
  /// author a document nobody else will ever see. Named here rather than typed
  /// into the editor so the rule is stated once and the exception is visible
  /// next to the tokens it breaks with.
  /// Both are `const`, and that is the enforcement rather than a note: a
  /// `AppTheme.pick` here would make the page follow Light/Dark, and a value that
  /// cannot be picked cannot drift. Pure black ink, not the app's near-black
  /// [textPrimary] — Word's "automatic" text colour is #000000, and this text is
  /// going to print.
  static const paper = Color(0xFFFFFFFF);
  static const paperInk = Color(0xFF000000);

  /// The furniture *around* the page — the formatting bar and the two rulers.
  ///
  /// Light in both themes, like [paper] above, and for a reason one step on
  /// from it. The page stays white because it is what you send; these stay light
  /// because they are what you set it with, and a ruler mixed for charcoal
  /// while the paper beside it is white belongs to neither. Word and Google Docs
  /// both keep this band light against a dark desk, which is what makes the page
  /// read as a page rather than as a white hole.
  ///
  /// `const` for the same reason [paper] is: a value that cannot be
  /// [AppTheme.pick]ed cannot quietly start following the theme again.
  ///
  /// Measured on [paperChrome]: [paperChromeInk] 11.3:1, [paperChromeInkSoft]
  /// 5.1:1 — both clear §11 with room, which the app's own text tokens would not
  /// have on this surface in dark.
  static const paperChrome = Color(0xFFF2F1ED);

  /// Hairlines, and the ruler's margin band.
  static const paperChromeLine = Color(0xFFD6D5CF);

  /// A pressed toggle, and the lift under a hovered glyph.
  static const paperChromeFill = Color(0xFFE3E2DC);

  /// Labels, glyphs and the ruler's numbers.
  static const paperChromeInk = Color(0xFF33332F);

  /// The resting ink of a control that isn't the one in force.
  static const paperChromeInkSoft = Color(0xFF63625C);

  /// The desk the page sits on.
  ///
  /// It used to follow the theme, and in dark that made it `#141414` — a page
  /// of white paper laid on near-black, which is the harshest edge the app had
  /// and the thing that made this screen tiring to look at. Now that the bar and
  /// the rulers around the page are fixed light, a desk that flipped was also
  /// the one surface still changing theme in the middle of the document, with
  /// chrome above it that didn't.
  ///
  /// So: one warm grey, in both. Deeper than [paperChromeLine] so the desk reads
  /// as *behind* the rulers rather than continuous with them, and far enough
  /// from [paper] that the page keeps its edges — which was the reason the light
  /// value could never be white either.
  static const paperDesk = Color(0xFFC4C3BD);
}

/// The scrollbar thumb, per brightness.
///
/// Kept as plain constants rather than only as [AppSurface] getters because
/// [buildAppTheme] needs the values *before* the global brightness is the one
/// being built for — see the note at its `scrollbarTheme`. The getters below read
/// these same four, so there is one set of numbers rather than two that can drift.
///
/// Translucent, so one thumb takes the tone of whatever it runs over, a menu or
/// a page, rather than sitting on it as a foreign gray.
const Color _scrollThumbLight = Color(0x59000000);
const Color _scrollThumbDark = Color(0x47FFFFFF);
const Color _scrollThumbHoverLight = Color(0x80000000);
const Color _scrollThumbHoverDark = Color(0x70FFFFFF);

/// Surface tokens for the app's chrome — the sidebar's rows, the composer card,
/// a recessed list column. Depth comes from a hairline rim and a soft shadow; the
/// overlays flip from black (on light) to white (on dark) so a hover/selection is
/// visible on either surface.
abstract final class AppSurface {
  /// The sidebar row you're on.
  static Color get selectedFill =>
      AppTheme.pick(const Color(0x0D000000), const Color(0x14FFFFFF));

  /// The sidebar row under the pointer — lighter than [selectedFill], so hover
  /// never reads as "selected".
  static Color get hoverFill =>
      AppTheme.pick(const Color(0x07000000), const Color(0x0DFFFFFF));

  /// A whisper of the accent, washed under the rail's primary action ("New
  /// chat") so it invites the click without hardening into a button. Kept faint
  /// (~8% in light, a touch stronger in dark so it reads on charcoal).
  static Color get accentWash =>
      AppTheme.pick(const Color(0x142F5BEA), const Color(0x242F5BEA));

  /// The same wash a step stronger, for the primary action under the pointer —
  /// so hovering it still reads as a change without ever looking "selected".
  static Color get accentWashHover =>
      AppTheme.pick(const Color(0x1F2F5BEA), const Color(0x332F5BEA));

  /// The icon well inside a list row.
  ///
  /// Translucent on purpose. An opaque fill would be picked against the row's
  /// *resting* colour and then near-vanish the moment the row lifted on hover —
  /// measured at 1.041:1 against the hovered light row. An overlay rides whatever
  /// it sits on, so the well keeps its edge in both states:
  ///
  /// ```
  ///          rest    hover
  /// light    1.168   1.173
  /// dark     1.183   1.200
  /// ```
  ///
  /// The two themes take different alphas because they start from different
  /// grounds — light needs more to separate from `#F3F3F2` than dark does from
  /// `#202020`. The glyph inside keeps 4.79:1 (light) and 5.76:1 (dark).
  static Color get wellFill =>
      AppTheme.pick(const Color(0x12000000), const Color(0x0FFFFFFF));

  /// A recessed well inside a panel.
  static Color get recess =>
      AppTheme.pick(const Color(0x08000000), const Color(0x0FFFFFFF));

  /// The recessed well under the pointer — a step lighter than [recess], so a
  /// hoverable surface (the account pill) lifts a touch to say it's clickable.
  static Color get recessHover =>
      AppTheme.pick(const Color(0x12000000), const Color(0x1AFFFFFF));

  /// A scrollbar thumb at rest.
  ///
  /// Opaque rather than a wash, and per-brightness rather than one alpha, because
  /// Material's default is neither and lands under the 3:1 that WCAG 1.4.11 asks
  /// of a UI element — `onSurface` at 10% is **1.23:1** on the light page, and at
  /// 30% is **2.46:1** on the dark one. Both were measured; both read as "no
  /// scrollbar" until you look for it.
  ///
  /// One alpha can't fix it either: white lifts a dark page fast while black
  /// barely dents a white one, so reaching 3:1 needs 0.40 in dark and 0.50 in
  /// light. These are those two values resolved — 3.55:1 dark, 3.36:1 light —
  /// stated as colours so a list on the panel measures the same as one on the page.
  /// Light was since deepened (#8C8C8C → #787878) for the light palettes'
  /// tinted grounds: the old thumb fell to 2.69:1 on Paper's workspace; this
  /// one holds 3.53 there and 3.55 on Mist's.
  static Color get scrollThumb =>
      AppTheme.pick(_scrollThumbLight, _scrollThumbDark);

  /// The thumb under the pointer or mid-drag: the same hue, plainly grabbed.
  static Color get scrollThumbHover =>
      AppTheme.pick(_scrollThumbHoverLight, _scrollThumbHoverDark);

  /// Soft drop shadow that lifts a floating surface (the composer) off the page.
  /// Deeper/darker in dark mode where a light lift would look like a glow.
  static List<BoxShadow> get shadow => AppTheme.pick(
    const [
      BoxShadow(
        color: Color(0x14000000),
        blurRadius: 24,
        offset: Offset(0, 10),
        spreadRadius: -10,
      ),
      BoxShadow(color: Color(0x0A000000), blurRadius: 4, offset: Offset(0, 1)),
    ],
    const [
      BoxShadow(
        color: Color(0x66000000),
        blurRadius: 24,
        offset: Offset(0, 10),
        spreadRadius: -10,
      ),
      BoxShadow(color: Color(0x40000000), blurRadius: 4, offset: Offset(0, 1)),
    ],
  );

  /// The composer's lift — Codex gives its input a soft shadow that spreads wide
  /// and low so the box clearly floats over the transcript. Two layers: a broad
  /// ambient pool plus a tighter contact shadow right under the rim.
  static List<BoxShadow> get composerShadow => AppTheme.pick(
    const [
      BoxShadow(
        color: Color(0x1F000000),
        blurRadius: 28,
        offset: Offset(0, 10),
        spreadRadius: -6,
      ),
      BoxShadow(
        color: Color(0x14000000),
        blurRadius: 8,
        offset: Offset(0, 2),
        spreadRadius: -2,
      ),
    ],
    const [
      BoxShadow(
        color: Color(0x80000000),
        blurRadius: 30,
        offset: Offset(0, 12),
        spreadRadius: -6,
      ),
      BoxShadow(
        color: Color(0x4D000000),
        blurRadius: 10,
        offset: Offset(0, 3),
        spreadRadius: -3,
      ),
    ],
  );
}

/// The Swarm sidebar's ink (task #3006).
///
/// A theme may draw its sidebar darker than the page around it — Plum's is
/// plum with white text in an otherwise white app. The tokens above follow
/// one global brightness and cannot tell the sidebar from the page, so the
/// sidebar's widgets read their ink here instead: inside [SidebarInk.scope]
/// on such a theme they get the sidebar's own, anywhere else (the same row
/// widgets on another page, or any theme without a sidebar of its own) the
/// page's ordinary tokens.
class SidebarInk extends InheritedWidget {
  const SidebarInk._({required super.child});

  /// Marks [child] as the Swarm sidebar, and gives text and icons that pick
  /// no color of their own the sidebar's ink.
  static Widget scope({required Widget child}) {
    final palette = AppTheme.surfacePalette;
    if (!palette.hasSidebarInk) return SidebarInk._(child: child);
    return SidebarInk._(
      child: IconTheme.merge(
        data: IconThemeData(color: palette.sidebarInk),
        child: DefaultTextStyle.merge(
          style: TextStyle(color: palette.sidebarInk),
          child: child,
        ),
      ),
    );
  }

  /// The default text style of a Material drawn as the sidebar: the theme's,
  /// in the sidebar's ink when it has its own (a Material sets its own
  /// default style, which would hide [scope]'s).
  static TextStyle? textStyle(BuildContext context) => switch (_own(context)) {
    final palette? => Theme.of(
      context,
    ).textTheme.bodyMedium?.copyWith(color: palette.sidebarInk),
    null => null,
  };

  static HarnessPalette? _own(BuildContext context) {
    final palette = AppTheme.surfacePalette;
    return palette.hasSidebarInk &&
            context.dependOnInheritedWidgetOfExactType<SidebarInk>() != null
        ? palette
        : null;
  }

  /// The sidebar's inks, for code that draws only the sidebar.
  static HarnessPalette? get _sidebarOwn =>
      AppTheme.surfacePalette.hasSidebarInk ? AppTheme.surfacePalette : null;
  static Color get ink => _sidebarOwn?.sidebarInk ?? AppPalette.textPrimary;
  static Color get inkMuted => switch (_sidebarOwn) {
    final palette? => palette.sidebarMuted ?? palette.sidebarInk!,
    null => AppPalette.textSecondary,
  };
  static Color get hover => _sidebarOwn?.sidebarHover ?? AppSurface.hoverFill;
  static Color get selected =>
      _sidebarOwn?.sidebarSelected ?? AppSurface.selectedFill;

  /// The same, for a widget that is drawn in the sidebar and elsewhere: the
  /// sidebar's inside [scope], the page's outside it.
  static Color foreground(BuildContext context) =>
      _own(context)?.sidebarInk ?? AppPalette.textPrimary;

  static Color muted(BuildContext context) => switch (_own(context)) {
    final palette? => palette.sidebarMuted ?? palette.sidebarInk!,
    null => AppPalette.textSecondary,
  };

  /// A disabled control's ink: the sidebar's own at half strength on a
  /// sidebar with its own ink, else the page's faint.
  static Color faint(BuildContext context) =>
      _own(context)?.sidebarInk?.withValues(alpha: .5) ?? AppPalette.textFaint;

  static Color hoverFill(BuildContext context) =>
      _own(context)?.sidebarHover ?? AppSurface.hoverFill;

  static Color selectedFill(BuildContext context) =>
      _own(context)?.sidebarSelected ?? AppSurface.selectedFill;

  @override
  bool updateShouldNotify(SidebarInk oldWidget) => false;
}

/// Translucent Codex-like chrome surfaces used behind a backdrop blur (the
/// sidebar, the top bar, floating pills). Fills are semi-transparent so the blur
/// shows through; kept separate from [AppCard] because these surfaces are chrome,
/// not dense content cards.
abstract final class AppGlass {
  // Near-opaque so the rail reads as a calm flat surface, not a frosted panel.
  //
  // Dark is fully opaque and says the value it means. Nothing is blurred behind
  // the rail (see [AppSidebar]), so the alpha did one thing: pull the fill 6%
  // back towards the page under it and land the rail on #191919 rather than the
  // number written here — a token that could only be read by compositing it.
  // At #242424 the rail is 1.27:1 against the page, so it reads as a surface
  // the content lies beside rather than the same charcoal with a hairline on it.
  static Color get sidebarFill =>
      AppTheme.pick(const Color(0xF7F9F9F8), const Color(0xFF242424));

  // Pills/menus are solid white in Codex (their softness comes from the rim and
  // a whisper of shadow, not from translucency).
  static Color get surfaceFill =>
      AppTheme.pick(const Color(0xFFFFFFFF), const Color(0xFF202020));

  static Color get surfaceHoverFill =>
      AppTheme.pick(const Color(0xFFF7F7F6), const Color(0xFF272727));

  static Color get hair =>
      AppTheme.pick(const Color(0x14000000), const Color(0x1FFFFFFF));

  /// A more present rim for the surfaces that should read as *lifted* — the
  /// composer, above all. The plain [hair] disappears into a white pane; this one
  /// is a clear soft grey (~#DADADA on white) so the input keeps a visible edge
  /// like Codex, without hardening into a boxy outline.
  static Color get lift =>
      AppTheme.pick(const Color(0x2E000000), const Color(0x2EFFFFFF));

  static Color get bubbleFill =>
      AppTheme.pick(const Color(0xFFF3F3F1), const Color(0xFF242424));

  static List<BoxShadow> get shadow => AppTheme.pick(
    const [
      BoxShadow(
        color: Color(0x14000000),
        blurRadius: 16,
        offset: Offset(0, 6),
        spreadRadius: -6,
      ),
      BoxShadow(color: Color(0x0A000000), blurRadius: 2, offset: Offset(0, 1)),
    ],
    const [
      BoxShadow(
        color: Color(0x66000000),
        blurRadius: 18,
        offset: Offset(0, 7),
        spreadRadius: -7,
      ),
      BoxShadow(color: Color(0x33000000), blurRadius: 3, offset: Offset(0, 1)),
    ],
  );

  // A whisper — the soft, tight lift Codex gives its floating pills and menus,
  // not a big ambient drop.
  /// A list row sitting directly on the page, at rest.
  ///
  /// **Not [surfaceFill], and light is the whole reason.** `windowBg` in light is
  /// pure `#FFFFFF` and so is `surfaceFill`, which put the row and the page it
  /// sits on at **1.000:1** — the same colour. The list had no rows in light at
  /// all until the pointer moved over one, because `surfaceHoverFill` (`#F7F7F6`,
  /// 1.072:1) was the first fill that differed from the page.
  ///
  /// A raised block cannot be raised by fill on a pure-white page: lighter than
  /// white does not exist. So light recesses instead — a grey card on white, the
  /// ordinary light-UI idiom — while dark keeps lifting. Measured, and shaped to
  /// match dark's separation rather than guessed at:
  ///
  /// ```
  ///           rest      hover     hover vs rest
  /// dark      1.090     1.189     1.091
  /// light     1.110     1.205     1.086
  /// ```
  ///
  /// Light's rest is [AppPalette.cardBg] rather than a new colour; only the hover
  /// step needed one. Text keeps its room on both: `textSecondary` reads 5.60:1
  /// at rest and 5.15:1 hovered.
  static Color get rowFill =>
      AppTheme.pick(const Color(0xFFF3F3F2), const Color(0xFF202020));

  /// The same row under the pointer.
  ///
  /// Moves *away* from the page in both themes — darker in light, lighter in dark
  /// — because a hover that drifts toward the background erases the row it is
  /// meant to be highlighting.
  static Color get rowHoverFill =>
      AppTheme.pick(const Color(0xFFEAEAE7), const Color(0xFF272727));

  static List<BoxShadow> get cardShadow => AppTheme.pick(
    const [
      BoxShadow(
        color: Color(0x0F000000),
        blurRadius: 8,
        offset: Offset(0, 3),
        spreadRadius: -3,
      ),
      BoxShadow(color: Color(0x08000000), blurRadius: 1, offset: Offset(0, 1)),
    ],
    const [
      BoxShadow(
        color: Color(0x59000000),
        blurRadius: 10,
        offset: Offset(0, 4),
        spreadRadius: -4,
      ),
    ],
  );
}

/// The floating-panel recipe — **one** source for every menu, popover and
/// tooltip in the app, so the three cannot drift apart.
///
/// They already had. Before this the app carried *four* recipes for the same
/// surface, and no two agreed:
///
/// ```
///                              fill (dark)   elevation   radius   rim
///   menuTheme / popupMenuTheme   #1E1E1E         8          6      no
///   appMenuStyle()               #2A2A2A        12         10      yes
///   tooltipTheme                 #1E1E1E         —         10      yes
///   the account footer, inline   cardBg         18          8      yes
/// ```
///
/// The cost was exactly what a second recipe always costs: the account footer's
/// `MenuAnchor` (since removed with the machine rail) passed no style at all, so
/// it opened the rimless themed default — the surface `appMenuStyle` had been
/// written to replace.
///
/// ⚠️ The fill is deliberately **not** the themed default. `#1E1E1E` sits within
/// 1.02:1 of a raised block ([AppGlass.surfaceFill], `#202020`), and in light
/// both are pure white — a menu opened over a dialog then has no edge at all and
/// its rows appear to float loose on the page. These lift clear of *both*
/// grounds a menu can open over: the page (`#181818` / `#FFFFFF`) and that
/// block. Measured with `tool/contrast.py`, 2026-09-03:
///
/// ```
///   dark   panel #2A2A2A vs page  #181818  =  1.237 : 1
///   dark   panel #2A2A2A vs block #202020  =  1.135 : 1
///   light  panel #FFFFFF vs page  #FFFFFF  =  1.000 : 1   ← the rim does it
///   light  panel #FFFFFF vs block #FFFFFF  =  1.000 : 1   ← and here
/// ```
///
/// Light is why the rim exists. On a white page the panel and the ground under
/// it are *the same colour*, so the rim is the only thing drawing the edge —
/// which is what earns it the one exception §1 allows. Fill alone cannot
/// separate two surfaces (§9.1); the rim and the shadow do it together, which is
/// also why the rim is not held to §16's 3.0 — see the note in `contrast.py`.
///
/// ⚠️ These are measurements with a date. Move `windowBg` or `surfaceFill` and
/// all four are stale — re-run the script, don't trust the comment.
///
/// ⚠️ The `*Light`/`*Dark` const twins exist for the same reason `_scrollThumb*`
/// do: [buildAppTheme] builds a theme for a brightness it has been *handed*,
/// while a getter answers for the brightness the app is *wearing*, and the two
/// differ in exactly the call that produces `darkTheme`. Inside that function
/// use [styleFor] and the consts; everywhere else use [style] and the getters.
abstract final class AppMenu {
  static const Color fillLight = Color(0xFFFFFFFF);

  /// One step above the page (#282828), so a panel lifts off what it opens over.
  static const Color fillDark = Color(0xFF2E2E2E);
  static Color get fill => AppTheme.pick(fillLight, fillDark);

  /// The panel's rim — the same hairline [AppGlass.hair] resolves to, stated as
  /// consts so [buildAppTheme] can read it.
  static const Color rimLight = Color(0x14000000);
  static const Color rimDark = Color(0x1FFFFFFF);
  static Color get rim => AppTheme.pick(rimLight, rimDark);

  /// Menu frame and inset rows follow the same concentric geometry.
  static const double panelRadius = AppDesktop.menuRadius;

  /// Deeper than Material's menu default (8): this panel opens over chrome that
  /// already carries a lift of its own, and at 8 it reads as lying *on* that
  /// chrome rather than over it.
  static const double elevation = 12;

  /// ⚠️ Vertical only. Rows carry their own horizontal gutter so their hover
  /// highlight reads as an inset pill; side padding here would double it.
  static const EdgeInsets panelPadding = EdgeInsets.symmetric(vertical: 5);

  /// The style every menu panel in the app takes.
  ///
  /// [minWidth]/[maxWidth] are for a panel whose width is part of its meaning —
  /// the account menu holds an email address and must not resize as the address
  /// changes. [maxHeight] defaults to [AppControl.menuMaxHeight]; override it
  /// only for a panel that is taller by design, and read that token's note
  /// first: a menu that opens *upward* places itself by summing the height it is
  /// about to take.
  static MenuStyle style({
    double? minWidth,
    double? maxWidth,
    double? maxHeight,
  }) => _style(
    isDark: AppTheme.isDark,
    minWidth: minWidth,
    maxWidth: maxWidth,
    maxHeight: maxHeight,
  );

  /// [style] resolved against a brightness handed in rather than the one the app
  /// is wearing. Only [buildAppTheme] needs this — see the ⚠️ above.
  static MenuStyle styleFor({required bool isDark}) => _style(isDark: isDark);

  static MenuStyle _style({
    required bool isDark,
    double? minWidth,
    double? maxWidth,
    double? maxHeight,
  }) => MenuStyle(
    backgroundColor: WidgetStatePropertyAll(isDark ? fillDark : fillLight),
    surfaceTintColor: const WidgetStatePropertyAll(Colors.transparent),
    elevation: const WidgetStatePropertyAll(elevation),
    padding: const WidgetStatePropertyAll(panelPadding),
    minimumSize: minWidth == null
        ? null
        : WidgetStatePropertyAll(Size(minWidth, 0)),
    maximumSize: WidgetStatePropertyAll(
      Size(maxWidth ?? double.infinity, maxHeight ?? AppControl.menuMaxHeight),
    ),
    shape: WidgetStatePropertyAll(
      RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(panelRadius),
        side: BorderSide(color: isDark ? rimDark : rimLight),
      ),
    ),
  );
}

/// Content-card recipe — a surface with a hairline rim and a soft lift. Distinct
/// from [AppSurface] (the chrome): cards carry dense content, so they stay quiet
/// and let the text do the work. Applied via [GlassCard].
abstract final class AppCard {
  static const accent = AppPalette.accent;
  static Color get accentStrong =>
      AppTheme.pick(const Color(0xFF1E40AF), const Color(0xFF5C7CFF));

  // card surface
  static Color get base =>
      AppTheme.pick(const Color(0xFFFFFFFF), const Color(0xFF2E2E2E));

  // recessed inner box / list tile
  static Color get inset =>
      AppTheme.pick(const Color(0xFFF7F7F5), const Color(0xFF181818));

  static Color get hair => AppPalette.divider; // card rim
  static Color get insetHair =>
      AppTheme.pick(const Color(0x0F000000), const Color(0x14FFFFFF));

  // Accent tints — used sparingly, for the focal card's wash and rim. Slightly
  // stronger in dark so the wash reads on charcoal.
  static Color get tint10 =>
      AppTheme.pick(const Color(0x0A2F5BEA), const Color(0x1A2F5BEA));
  static Color get tint18 =>
      AppTheme.pick(const Color(0x142F5BEA), const Color(0x282F5BEA));
  static Color get tint25 =>
      AppTheme.pick(const Color(0x332F5BEA), const Color(0x422F5BEA));

  static Color get highlightEdge =>
      AppTheme.pick(const Color(0x0A000000), const Color(0x1FFFFFFF));

  /// Corner rounding, on macOS's scale rather than iOS's.
  ///
  /// A Mac window is ~10 and a sheet/popover ~12; iOS and the web round far
  /// harder, and at 18 a card read as an iOS sheet that had wandered onto a
  /// desktop. It also disagreed with the buttons *inside* it ([AppControl.radius]
  /// is 8), so a card and its own action were speaking two shape languages.
  ///
  /// The inset tile drops to 8 to match those buttons: an inset sits inside a
  /// card, and nesting a rounder box inside a less-round one is what makes a
  /// tile look pasted on rather than set in.
  static const double radius = 12;
  static const double insetRadius = 8;

  /// Soft ambient drop that lifts a card off the page.
  static List<BoxShadow> get shadow => AppTheme.pick(
    const [
      BoxShadow(
        color: Color(0x12000000),
        blurRadius: 20,
        offset: Offset(0, 8),
        spreadRadius: -8,
      ),
    ],
    const [
      BoxShadow(
        color: Color(0x66000000),
        blurRadius: 20,
        offset: Offset(0, 8),
        spreadRadius: -8,
      ),
    ],
  );

  /// The focal (hero) card's stronger lift.
  static List<BoxShadow> get heroShadow => AppTheme.pick(
    [
      const BoxShadow(
        color: Color(0x1A000000),
        blurRadius: 28,
        offset: Offset(0, 12),
        spreadRadius: -8,
      ),
      BoxShadow(
        color: tint18,
        blurRadius: 32,
        offset: const Offset(0, 10),
        spreadRadius: -8,
      ),
    ],
    [
      const BoxShadow(
        color: Color(0x73000000),
        blurRadius: 28,
        offset: Offset(0, 12),
        spreadRadius: -8,
      ),
      BoxShadow(
        color: tint18,
        blurRadius: 32,
        offset: const Offset(0, 10),
        spreadRadius: -8,
      ),
    ],
  );
}

/// The app's theme for a given [brightness]. Both the light and dark themes are
/// built from this one function so the two never drift; the color tokens above
/// resolve against [AppTheme.brightness] at paint time.
ThemeData buildAppTheme({
  Brightness brightness = Brightness.light,
  bool highContrast = false,
}) {
  final isDark = brightness == Brightness.dark;
  final baseScheme = isDark
      ? ColorScheme.dark(
          primary: AppPalette.accent,
          onPrimary: Colors.white,
          secondary: AppPalette.accent,
          surface: AppTheme.paletteFor(brightness).background,
          onSurface:
              AppTheme.paletteFor(brightness).text ?? const Color(0xFFF5F5F5),
          onSurfaceVariant:
              AppTheme.paletteFor(brightness).muted ?? const Color(0xFFA8A8A2),
          surfaceContainerHighest: AppTheme.paletteFor(brightness).card,
          outline: const Color(0x14FFFFFF),
          outlineVariant: const Color(0x14FFFFFF),
          error:
              AppTheme.paletteFor(brightness).errorInk ??
              const Color(0xFFFF7068),
        )
      : ColorScheme.light(
          primary: AppPalette.accent,
          onPrimary: Colors.white,
          secondary: AppPalette.accent,
          // The light palette's own ground — matches AppPalette.windowBg, as
          // the dark scheme's does.
          surface: AppTheme.paletteFor(brightness).background,
          onSurface: AppTheme.paletteFor(brightness).foreground,
          onSurfaceVariant:
              AppTheme.paletteFor(brightness).muted ?? const Color(0xFF62615B),
          // The field fill. Not the card, which is pure white on both light
          // palettes: a white field in a white dialog has no edge at all. The
          // panel tone is the step the old light theme's #F3F3F2 was.
          surfaceContainerHighest: AppTheme.paletteFor(brightness).panel,
          outline: const Color(0x0F000000),
          outlineVariant: const Color(0x0F000000),
          error:
              AppTheme.paletteFor(brightness).errorInk ??
              const Color(0xFFB3261E),
        );
  final scheme = highContrast
      ? baseScheme.copyWith(
          outline: baseScheme.onSurface.withValues(alpha: .6),
          outlineVariant: baseScheme.onSurface.withValues(alpha: .4),
        )
      : baseScheme;

  // The chrome fills used by menus, dialogs and toasts. A getter-backed token
  // can't be a compile-time const, so these are resolved here per-brightness —
  // and, more importantly, from `isDark` rather than off a token, for the reason
  // spelled out at `scrollbarTheme` below.
  //
  // Two fills, not one. A *floating panel* (menu, popover, tooltip) opens over
  // chrome that may itself be raised, so it takes [AppMenu]'s lifted fill; a
  // *dialog* is the raised block, so it takes the block's own fill. Before this
  // both were `#1E1E1E`, which is [AppCard.base] — a content card's colour, one
  // step *below* the block it was supposed to be.
  final panelFill = isDark ? AppMenu.fillDark : AppMenu.fillLight;
  final dialogFill = panelFill;
  final textTheme = _appTextTheme(scheme.onSurface, scheme.onSurfaceVariant);

  return ThemeData(
    filledButtonTheme: FilledButtonThemeData(
      style: _filledButtonStyle(scheme, highContrast: highContrast),
    ),
    outlinedButtonTheme: OutlinedButtonThemeData(
      style: _outlinedButtonStyle(scheme, highContrast: highContrast),
    ),
    textButtonTheme: TextButtonThemeData(
      style: _textButtonStyle(scheme, highContrast: highContrast),
    ),
    useMaterial3: true,
    brightness: brightness,
    colorScheme: scheme,
    // Also stated at ThemeData level, not only inside the ramp: Material builds
    // text of its own (a dialog's semantics label, a field's error line) that
    // never passes through `textTheme`, and without this those fall through to
    // Roboto instead of the system face.
    fontFamily: AppFont.sans,
    fontFamilyFallback: AppFont.sansFallback,
    scaffoldBackgroundColor: scheme.surface,
    canvasColor: scheme.surface,
    dividerColor: scheme.outline,
    dividerTheme: DividerThemeData(
      color: scheme.outline,
      thickness: 1,
      space: 1,
    ),
    // Set once here rather than per-Scrollbar: the three call sites that predate
    // this each accepted Material's default, which measures 1.23:1 on the light
    // page and 2.46:1 on the dark one — under the 3:1 floor for a UI element.
    // See `AppSurface.scrollThumb` for the numbers.
    scrollbarTheme: ScrollbarThemeData(
      // Resolved from `isDark`, not read off `AppSurface` — this function is
      // called twice up front, and the dark pass runs while the global
      // brightness still says light, so a getter-backed token would bake the
      // light thumb into `darkTheme`. The `AppPalette.accent` reads above never
      // exposed this: that one is a const with the same value in both themes.
      thumbColor: WidgetStateProperty.resolveWith(
        (states) =>
            states.contains(WidgetState.hovered) ||
                states.contains(WidgetState.dragged)
            ? (isDark ? _scrollThumbHoverDark : _scrollThumbHoverLight)
            : (isDark ? _scrollThumbDark : _scrollThumbLight),
      ),
      // No track: a filled channel down the edge of every pane is a border by
      // another name, and §2 allows exactly one of those.
      trackColor: WidgetStateProperty.all(Colors.transparent),
      trackBorderColor: WidgetStateProperty.all(Colors.transparent),
      // 3px, one clear of the edge: it runs inside the 6px gutter every menu row
      // and list keeps, so it never covers a row's fill or text.
      thickness: WidgetStateProperty.all(3),
      crossAxisMargin: 1,
      mainAxisMargin: 4,
      radius: const Radius.circular(1.5),
      // The thumb is only meaningful while there is more list than pane, and
      // fading it in on scroll keeps a short list from wearing furniture.
      thumbVisibility: WidgetStateProperty.all(false),
      interactive: true,
    ),
    // Material opens a tooltip the instant the pointer enters. In a transcript
    // that scrolls under a still pointer that means tooltips popping open on
    // rows flying past — and worse: a tooltip shown mid-scroll gets its overlay
    // hit-tested before it has been laid out, which throws inside the mouse
    // tracker and then re-throws every frame after (see ErrorBurstFilter). A
    // delay is the fix for both, set once here rather than at the nine call
    // sites that each reached for their own number.
    //
    // Everything below the delay is the app's floating-panel recipe, the same
    // one `appMenuStyle` uses, because a tooltip is one: the menu fill, the
    // hairline rim, the panel radius and the lift. Material's own is an
    // *inverse* surface — deliberately the opposite of the window — so on a dark
    // build it opened a white slab in the middle of a near-black app.
    //
    // The rim earns its place here for the reason it does on a menu: in light
    // the fill is the same white as the surface underneath, so the rim is the
    // only thing drawing the edge, and in dark it firms up a lift that a shadow
    // alone renders too softly against near-black.
    tooltipTheme: TooltipThemeData(
      waitDuration: const Duration(milliseconds: 500),
      decoration: BoxDecoration(
        color: panelFill,
        borderRadius: BorderRadius.circular(AppMenu.panelRadius),
        // Resolved from `isDark` rather than read off the `AppMenu` getters:
        // those answer for the brightness the app is *showing*, and this function
        // builds the theme for a brightness it has been handed.
        border: Border.all(color: isDark ? AppMenu.rimDark : AppMenu.rimLight),
        boxShadow: isDark
            ? const [
                BoxShadow(
                  color: Color(0x66000000),
                  blurRadius: 24,
                  offset: Offset(0, 10),
                  spreadRadius: -10,
                ),
                BoxShadow(
                  color: Color(0x40000000),
                  blurRadius: 4,
                  offset: Offset(0, 1),
                ),
              ]
            : const [
                BoxShadow(
                  color: Color(0x14000000),
                  blurRadius: 24,
                  offset: Offset(0, 10),
                  spreadRadius: -10,
                ),
                BoxShadow(
                  color: Color(0x0A000000),
                  blurRadius: 4,
                  offset: Offset(0, 1),
                ),
              ],
      ),
      // Room for multiline text.
      textStyle: AppType.caption(height: 1.45, color: scheme.onSurface),
      padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 8),
      // Long quoted lines would otherwise take the tooltip out to the window's
      // full width — a panel wider than the conversation it is explaining.
      constraints: const BoxConstraints(maxWidth: 420),
    ),
    // macOS controls do not ripple. §10.1 lists the ink ripple among the four
    // things a raw `MenuItemButton` gets wrong, and §11 names it again for
    // `IconButton` and `SegmentedButton` — so turning it off once here is the
    // same rule applied at the root instead of at every call site.
    splashFactory: NoSplash.splashFactory,
    textTheme: textTheme,
    primaryTextTheme: textTheme,
    iconTheme: IconThemeData(color: scheme.onSurfaceVariant, size: 18),
    iconButtonTheme: IconButtonThemeData(
      style: ButtonStyle(
        side: WidgetStatePropertyAll(
          BorderSide(width: highContrast ? 2 : 1.5, color: Colors.transparent),
        ),
        shape: WidgetStatePropertyAll(
          RoundedRectangleBorder(borderRadius: BorderRadius.circular(7)),
        ),
        overlayColor: WidgetStateProperty.resolveWith((states) {
          if (states.contains(WidgetState.disabled)) return Colors.transparent;
          if (states.contains(WidgetState.pressed)) {
            return isDark ? const Color(0x1AFFFFFF) : const Color(0x0D000000);
          }
          if (states.contains(WidgetState.hovered) ||
              states.contains(WidgetState.focused)) {
            return isDark ? const Color(0x0DFFFFFF) : const Color(0x07000000);
          }
          return Colors.transparent;
        }),
      ),
    ),
    switchTheme: SwitchThemeData(
      thumbColor: WidgetStateProperty.all(Colors.white),
      trackColor: WidgetStateProperty.resolveWith(
        (s) => s.contains(WidgetState.selected)
            ? AppPalette.accent
            // Light's off track is a UI mark (3:1): #A3A29C was 2.56 on a
            // white dialog; #858480 is 3.74 there, 3.37 on the panel.
            : (isDark ? const Color(0xFF3A3A3A) : const Color(0xFF858480)),
      ),
      trackOutlineColor: WidgetStateProperty.all(Colors.transparent),
    ),
    // A text field must show where the keyboard is going. This used to set
    // BorderSide.none on all three states, so every field that took the theme
    // default — most of the app — had no focus ring at all: you could not tell
    // a focused field from an idle one. macOS rings the focused control in the
    // accent; that's what these borders restore.
    inputDecorationTheme: InputDecorationTheme(
      isDense: true,
      filled: true,
      fillColor: scheme.surfaceContainerHighest,
      // A field hint is set like the field's own text.
      // (The typed text is set on the field via
      // [kFieldTextStyle]; `InputDecorationTheme` has no `style` of its own, so
      // a field's own text can't be themed globally here.)
      hintStyle: _fieldTextStyle(AppPalette.textFaintFor(isDark: isDark)),
      // Material builds a field for a phone: its default padding, plus the 48px
      // touch target it gives a prefixIcon, rendered this 48 tall next to a 32px
      // button. That's what these constraints exist to hold back.
      //
      // The height is [AppControl.heightField], not [AppControl.height]: a field
      // is typed in, not clicked, and at a button's 32 it reads cramped — see
      // that token. Derived here rather than typed as a number that happens to
      // land near it.
      //
      // The arithmetic: the box is padding + one line of AppControl.fontSize.
      // `isDense` already tightens Material's own vertical slack, so the padding
      // is what's left over once the line has taken its share.
      constraints: BoxConstraints(minHeight: AppControl.heightFieldScaled),
      contentPadding: EdgeInsets.symmetric(
        horizontal: 10,
        vertical:
            (AppControl.heightFieldScaled - AppControl.fontSize * 1.35) / 2,
      ),
      // The glyph sits on the text's line, not in a tap target of its own. A
      // step above [AppControl.iconSize]: that size is tuned to a button's cap
      // height, and this field is taller, so the button's glyph looks
      // undersized in it.
      prefixIconConstraints: BoxConstraints(
        minWidth: 32 * AppFont.uiScale,
        minHeight: kFieldIconSize * AppFont.uiScale,
      ),
      border: _fieldBorder(scheme.outline),
      enabledBorder: _fieldBorder(scheme.outline),
      // No colored focus line: a focused field has its caret.
      focusedBorder: _fieldBorder(scheme.outline),
      errorBorder: _fieldBorder(scheme.error),
      focusedErrorBorder: _fieldBorder(
        scheme.error,
        width: highContrast ? 2 : 1.5,
      ),
    ),
    // Fill, rim and elevation come from [AppMenu] so a Material popup cannot
    // disagree with a MenuAnchor about what a menu looks like.
    //
    // The radius does not: [AppControl.menuRadius] (6) is the §3 step for
    // *Material's own* popup, which draws tighter than the app's panel (10).
    popupMenuTheme: PopupMenuThemeData(
      color: panelFill,
      surfaceTintColor: Colors.transparent,
      elevation: AppMenu.elevation,
      shape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(AppControl.menuRadius),
        side: BorderSide(color: isDark ? AppMenu.rimDark : AppMenu.rimLight),
      ),
    ),
    // The default every `MenuAnchor` gets, identical to what [AppMenu.style]
    // hands a call site that asks for one explicitly. That identity is the whole
    // point: a MenuAnchor that forgets to pass a style used to fall back to a
    // rimless panel, which is the bug the hand-written style existed to fix.
    menuTheme: MenuThemeData(style: AppMenu.styleFor(isDark: isDark)),
    menuButtonTheme: MenuButtonThemeData(
      style: ButtonStyle(
        textStyle: WidgetStatePropertyAll(AppType.body(height: 1.25)),
        minimumSize: const WidgetStatePropertyAll(Size(0, AppControl.height)),
        shape: WidgetStatePropertyAll(
          RoundedRectangleBorder(
            borderRadius: BorderRadius.circular(AppDesktop.rowRadius),
          ),
        ),
        foregroundColor: WidgetStateProperty.resolveWith(
          (states) => states.contains(WidgetState.disabled)
              ? scheme.onSurface.withValues(alpha: .38)
              : states.contains(WidgetState.hovered) ||
                    states.contains(WidgetState.focused)
              ? AppDesktop.onSelection
              : scheme.onSurface,
        ),
        backgroundColor: WidgetStateProperty.resolveWith(
          (states) =>
              !states.contains(WidgetState.disabled) &&
                  (states.contains(WidgetState.hovered) ||
                      states.contains(WidgetState.focused))
              ? AppDesktop.selection
              : Colors.transparent,
        ),
        overlayColor: const WidgetStatePropertyAll(Colors.transparent),
        mouseCursor: WidgetStateProperty.resolveWith(
          (states) => states.contains(WidgetState.disabled)
              ? SystemMouseCursors.basic
              : SystemMouseCursors.click,
        ),
      ),
    ),
    // An ExpansionTile defaults `backgroundColor` (expanded) and
    // `collapsedBackgroundColor` to *different* values and cross-fades between
    // them, so opening one flashes a tint over whatever surface it sits on. Our
    // tiles are always laid into a card that has already painted its own
    // background, so both states must simply be transparent — then expanding
    // moves the disclosure and nothing else.
    expansionTileTheme: const ExpansionTileThemeData(
      backgroundColor: Colors.transparent,
      collapsedBackgroundColor: Colors.transparent,
      // Same reason for the divider lines each tile was clearing by hand.
      shape: Border(),
      collapsedShape: Border(),
    ),
    dialogTheme: DialogThemeData(
      // Standard Dialog and custom DesktopDialogSurface use one frame recipe.
      backgroundColor: dialogFill,
      surfaceTintColor: Colors.transparent,
      elevation: AppDesktop.dialogElevation,
      shadowColor: AppDesktop.shadow,
      shape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(AppDesktop.dialogRadius),
        side: BorderSide(color: isDark ? AppMenu.rimDark : AppMenu.rimLight),
      ),
      titleTextStyle: AppType.heading(color: scheme.onSurface),
      contentTextStyle: AppType.body(color: scheme.onSurface),
    ),
    // ⚠️ [AppPalette.accentOnSurface], NOT `colorScheme.primary`.
    //
    // A spinner is the textbook case that token exists for: a MARK ON A SURFACE,
    // not a fill carrying white text. Left to `primary` the arc draws #2F5BEA on
    // the dark page, which measures 3.218:1 — over §16's 3.0 floor for a UI
    // element, but only just, and it is the one thing on screen saying the app
    // is still working. The lifted tint reaches 5.750:1.
    //
    // Resolved from `isDark` rather than read off the getter — see the note at
    // `scrollbarTheme`.
    progressIndicatorTheme: ProgressIndicatorThemeData(
      color: isDark ? AppDesktop.focusDark : const Color(0xFF2F5BEA),
      linearTrackColor: scheme.outline,
    ),
    snackBarTheme: SnackBarThemeData(
      behavior: SnackBarBehavior.floating,
      width: 520,
      // A snackbar floats over everything, so it takes the panel fill.
      backgroundColor: panelFill,
      contentTextStyle: AppType.body(color: scheme.onSurface),
      actionTextColor: AppPalette.accent,
      closeIconColor: scheme.onSurfaceVariant,
      elevation: 10,
      shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(13)),
    ),
  );
}

/// The one set of numbers every button in the app is built from.
///
/// Shared desktop controls: 13-point system labels, 32-point capsule buttons,
/// and softly rounded fields. Change geometry here, not in individual dialogs.
abstract final class AppControl {
  /// Standard control height. macOS's regular push button sits at 32; the app's
  /// own most-used value was 34, and 32 reads correctly next to a 13pt label.
  static const double height = 32;

  /// A compact control (inline actions inside a dense row or a card header).
  static const double heightSmall = 28;

  /// A search field at the head of a list column.
  ///
  /// Taller than [height], and deliberately: a push button is sized to be hit,
  /// but this field is sized to be *typed in* and to anchor the column under it.
  /// Finder and Mail both give their sidebar search more room than a button in
  /// the same window for exactly that reason — at [height] it reads as cramped,
  /// which is what a control set to a button's scale looks like when it isn't
  /// one.
  static const double heightField = 36;

  /// Text-field radius. Action buttons use the shared capsule shape.
  static const double radius = AppDesktop.fieldRadius;

  /// Menu/popover radius, shared with custom desktop choosers.
  static const double menuRadius = AppDesktop.menuRadius;

  /// The air between a menu panel and the control it hangs off.
  ///
  /// One number for every menu in the app, in both directions: a downward menu
  /// passes `Offset(0, menuGap)`, an upward one `Offset(0, -menuGap)`. It was
  /// three numbers before — 6 nearly everywhere, 8 on the composer's agent and
  /// approval pills, and none at all on its model pill, so the three menus that
  /// open off the *same* toolbar each sat at a different height.
  static const double menuGap = 6;

  /// The tallest a menu panel ever draws, whatever it lists — `appMenuStyle`
  /// caps every menu here.
  ///
  /// A token rather than a number inside that style, because the menus that
  /// open *upward* have to place themselves by summing the height they are
  /// about to take: a caller that predicts 310 for a panel the style then draws
  /// at 240 lifts it 70px clear of its button. That is what floated the chat
  /// model list off the composer and over the conversation.
  /// [anchoredMenuPosition] clamps to this by default.
  static const double menuMaxHeight = 240;

  /// A button's label: [AppType.label].
  static const double fontSize = AppType.bodySize;
  static const FontWeight fontWeight = AppFont.medium;

  /// A leading glyph inside a button, sized to sit on the cap height of a 13pt
  /// label rather than tower over it.
  static const double iconSize = 16;

  /// A compact glyph for an inline chip.
  static const double iconSizeChip = 13;

  /// The minimum height keeps normal-size controls compact. Vertical padding
  /// lets enlarged system text grow the capsule without touching its rim.
  ///
  /// One side padding for every button kind: at 14 and 10 a primary, a capsule
  /// and a dialog button of the same height each held their text differently.
  static const EdgeInsets padding = EdgeInsets.symmetric(
    horizontal: 12,
    vertical: 6,
  );
  static const EdgeInsets paddingSmall = EdgeInsets.symmetric(
    horizontal: 12,
    vertical: 6,
  );

  /// A button that leads with a glyph, at the compact scale.
  ///
  /// Wider on the leading edge than the trailing one, and the asymmetry is the
  /// point: [paddingSmall] is even, which measures as centred and *reads* as
  /// pushed left. A glyph is a solid shape that fills its box to the edge, while
  /// a label's first letter carries its own sidebearing — so at an equal 10px
  /// the glyph sits visibly tighter to the rim than the text does at the other
  /// end. Extra leading pad buys back what the glyph lacks.
  ///
  /// Only for `.icon` constructors; a text-only button stays on [paddingSmall].
  static const EdgeInsets paddingSmallIcon = EdgeInsets.only(
    left: 14,
    right: 12,
  );

  // — the same numbers, grown with the user's UI size —
  //
  // The constants above stay constants on purpose. They appear in ~40 `const`
  // expressions across the app (`const Size(0, AppControl.height)`, `const
  // Icon(…, size: AppControl.iconSize)`), and turning them into getters would
  // break every one of those for no gain: a `const Icon` inside a themed button
  // is already re-laid-out when the button's own box grows.
  //
  // What actually has to grow is the *box*, and every box in the app comes from
  // one of the button/field styles built below in [buildAppTheme] — so these
  // scaled forms are read there, in one place, rather than at the call sites.

  /// [height], grown for the current UI size.
  static double get heightScaled => height * AppFont.uiScale;

  /// [heightField], grown for the current UI size.
  static double get heightFieldScaled => heightField * AppFont.uiScale;

  /// [padding], grown for the current UI size — a wider label needs the
  /// sidebearing to grow with it, or the text crowds the capsule's ends.
  static EdgeInsets get paddingScaled => padding * AppFont.uiScale;

  static EdgeInsets get paddingSmallScaled => paddingSmall * AppFont.uiScale;
}

/// The desktop's geometry and interaction tokens. Dialogs, menu anchors, search,
/// creation and ordinary themed controls all resolve through this one recipe.
/// Terminal geometry and the user's terminal palette remain independent.
abstract final class AppDesktop {
  static const double dialogRadius = 20;
  static const double dialogElevation = 16;
  static const Color shadow = Color(0x3D000000);

  static const double menuRadius = 16;
  static const double rowRadius = 10;
  static const double fieldRadius = 10;
  static const double paneRadius = 10;
  static const double tabRadius = 10;
  static const double tabShoulder = 8;
  static const double tabTopInset = 0;

  /// A tab's ×: the pane close button's 28pt square target, centred on the
  /// tab's body (the 40pt row less [tabTopInset]) with one 6pt gap above,
  /// below, and to the body's straight right side, [tabShoulder] in.
  static const double tabCloseSize = 28;
  static const double tabCloseInset = tabShoulder + 6;
  static const double tabMinWidth = 128;
  static const double tabMaxWidth = 256;
  static const double tabBarTrailingInset = 12;
  static const double paneCloseInset = 4;
  static const double panelPadding = 24;
  static const double groupGap = 16;
  static const double controlGap = 8;

  /// The Swarm composer's box, as the phone draws it (Huy, 11-04): the text
  /// [composerTop] below the top and [composerSide] in from each side, and
  /// [composerRowGap] between the text and the row of actions under it. A
  /// rounded pill, as iMessage's (anh Dee's mockup, 11-07, #4529).
  static const double composerRadius = 20;
  static const double composerTop = 12;
  static const double composerSide = groupGap;
  static const double composerRowGap = 12;

  /// Between one sidebar row and the next (design system: Geometry).
  static const double listRowGap = 2;

  /// A count badge's text from its capsule's ends, as in Notifications' count.
  static const double badgeInset = 5;
  static const double menuInset = 6;
  static const double iconSize = 16;
  static const double identitySize = 28;

  /// A chat or thread message's face: round at 28, as every other avatar
  /// (anh Dee, 11-07, #4467; was Slack's 36 rounded square).
  static const double messageAvatarSize = 28;

  /// A chat bubble's text from its edges (anh Dee's mockup, 11-07, #4529).
  static const EdgeInsets bubblePadding = EdgeInsets.symmetric(
    horizontal: 12,
    vertical: 7,
  );

  /// A chat card's content from its edges: a little more than a bubble's.
  static const EdgeInsets chatCardPadding = EdgeInsets.fromLTRB(14, 10, 14, 10);

  /// A centered chat time: a pause's room above it, its line's below.
  static const EdgeInsets chatTimePadding = EdgeInsets.only(top: 12, bottom: 4);

  /// A small line under or beside a bubble (a fold's More, a line's status)
  /// from it.
  static const double bubbleNoteGap = 4;

  /// A group chat's name over its first bubble: in from the bubble's edge as
  /// its text is, and close above it.
  static const EdgeInsets bubbleNamePadding = EdgeInsets.only(
    left: 12,
    bottom: 2,
  );
  static const double formWidth = 460;
  static const double focusWidth = 1.5;

  static Color get surface => AppMenu.fill;
  static Color get rim => AppMenu.rim;
  static Color get field =>
      AppTheme.pick(const Color(0xFFF2F2F4), const Color(0xFF303030));
  static const Color focusDark = Color(0xFF8BA9FF);
  static Color get focus => AppTheme.pick(AppPalette.accent, focusDark);
  static Color get selection => AppPalette.accent;
  static const Color onSelection = Colors.white;
  static const Color selectionDetail = Color(0xEBFFFFFF);

  static const darkVeil = Color(0xF2000000);
  static const lightVeil = Color(0xF2FFFFFF);
  static Color veil(Brightness brightness) =>
      brightness == Brightness.dark ? darkVeil : lightVeil;

  /// The chat's picture viewer: a see-through dark veil in both appearances,
  /// as a picture reads best on dark (River, 11-04), and the ink and control
  /// fills drawn on it. The one exception to [veil]
  /// (desktop-design-system.md).
  static const mediaVeil = Color(0xF2000000);
  static const mediaInk = Color(0xFFFFFFFF);
  static const mediaInkMuted = Color(0xB3FFFFFF);
  static const mediaControl = Color(0x26FFFFFF);
  static const mediaControlHover = Color(0x40FFFFFF);
}

/// Desktop feedback is visible on the next frame. Keep these shared names so
/// hover, selection, panels, and meters cannot grow independent animation delays.
/// Progress indicators may still animate while real work is in flight.
abstract final class AppMotion {
  static const Duration hover = Duration.zero;
  static const Duration swap = Duration.zero;
  static const Duration fold = Duration.zero;
  static const Duration meter = Duration.zero;
  static const Duration press = Duration.zero;
  static const Curve curve = Curves.easeOut;
}

/// The app's two faces and its weight ladder. Sizes live in [AppType].
abstract final class AppFont {
  /// The system UI face. See [AppType] for the rule on which face text gets.
  static String get sans => AppType.sansFamily;
  static List<String> get sansFallback => AppType.sansFallback;

  /// The terminal's face, used for terminal chrome and copyable strings.
  static String get mono => AppType.monoFamily;
  static List<String> get monoFallback => AppType.monoFallback;

  /// Digits that hold a fixed width, so a stat doesn't reflow as its value
  /// changes and a column of numbers lines up.
  static const List<FontFeature> tabularFigures = [
    FontFeature.tabularFigures(),
  ];

  // — the weight ladder —
  //
  // Three steps, and the app should not need a fourth. Named rather than typed
  // as `FontWeight.w500` at the call site, because the numbers moved once
  // already: the app was drawn at w600 for every label and w700 for every
  // heading, which is a step heavier than macOS itself sets the same things.
  // Finder's sidebar, System Settings' rows and a push button's label are all
  // *medium*; semibold is what Apple reserves for a window title or a section
  // header that has to out-rank the rows under it.
  //
  // At 13pt on a Retina panel that one step is the difference between a UI that
  // reads as crisp and one that reads as shouted — every label competing with
  // every other, and nothing left to promote a heading with.

  /// Body copy, and anything that is simply being read.
  static const FontWeight regular = FontWeight.w400;

  /// The app's workhorse: control labels, sidebar items, row titles, table
  /// headers — anything that names something without being a heading.
  ///
  /// This is the weight that used to be [semibold] in 133 places.
  static const FontWeight medium = FontWeight.w500;

  /// Reserved for type that has to out-rank the medium text beside it: a screen
  /// or section heading, the selected row in a menu.
  ///
  /// If everything on a screen is semibold, nothing is — which is the state the
  /// ladder was introduced to fix. Reach for [medium] first.
  static const FontWeight semibold = FontWeight.w600;

  /// Tracking for the sans face; see [AppType.trackingFor].
  static double trackingFor(double size) => AppType.trackingFor(size);

  /// The UI no longer scales with the terminal's size setting: ⌘+ and ⌘−
  /// resize the terminal alone, so control geometry stays as drawn.
  static const double uiScale = 1;

  /// The terminal's size, for a surface that shows terminal output verbatim.
  static double get codeSize => terminalFontStore.size;

  /// A block of code or a log: the terminal face at the UI's mono size.
  static TextStyle codeStyle({
    Color? color,
    double? height,
    FontWeight? fontWeight,
  }) => AppType.mono(color: color, height: height, fontWeight: fontWeight);
}

/// A text field's rim at one state. Radius matches [AppControl.radius] so a
/// field and the button next to it are cut from the same shape language.
OutlineInputBorder _fieldBorder(Color color, {double width = 1}) =>
    OutlineInputBorder(
      borderRadius: BorderRadius.circular(AppControl.radius),
      borderSide: BorderSide(color: color, width: width),
    );

/// The label style shared by every button: a `ButtonStyle.textStyle` does
/// **not** inherit `fontFamily` from the text theme, so a button must receive
/// the UI font explicitly.
TextStyle get _buttonTextStyle =>
    AppType.body(fontWeight: AppControl.fontWeight, height: 1.25);

/// Ordinary form fields use the system UI face. Code, paths, credentials,
/// and terminal editors opt into their explicit monospace styles.
/// `InputDecorationTheme` has no `style` slot (it themes the *decoration*, not
/// the editable text), so a field must be handed this explicitly:
/// `TextField(style: kFieldTextStyle, ...)`.
TextStyle get kFieldTextStyle => _fieldTextStyle(AppPalette.textPrimary);

TextStyle _fieldTextStyle(Color color) => AppType.body(color: color);

/// A field's leading glyph — the magnifier on a search box, and its kind.
///
/// A step above [AppControl.iconSize], which is tuned to sit on the cap height
/// of a button's 13pt label. A field is [AppControl.heightField] tall, so the
/// button's glyph reads undersized in it — the icon has to follow the box it
/// sits in, not the token next to it. Themed via `prefixIconConstraints`, but
/// the `Icon` itself still has to be handed this size at the call site.
const double kFieldIconSize = 18;

StadiumBorder get _buttonShape => const StadiumBorder();

/// The primary action: a solid accent capsule.
/// A filled button that destroys something.
///
/// Exists so the three that do — the two connector confirms and the skill delete
/// — cannot each pick their own red and their own label colour. Before this they
/// had three answers between them, and all three failed in dark: two set white
/// on [AppPalette.dangerFill]'s predecessor (3.42:1) and one left the label to
/// Material (3.83:1).
///
/// `foregroundColor` is named rather than left to `colorScheme.onError`, which
/// this app's scheme never sets — so Material fills in its own and lands under
/// the floor.
ButtonStyle dangerButtonStyle() => FilledButton.styleFrom(
  backgroundColor: AppPalette.dangerFill,
  foregroundColor: Colors.white,
);

ButtonStyle _filledButtonStyle(
  ColorScheme scheme, {
  bool highContrast = false,
}) => FilledButton.styleFrom(
  backgroundColor: scheme.primary,
  foregroundColor: scheme.onPrimary,
  disabledBackgroundColor: scheme.onSurface.withValues(alpha: .08),
  disabledForegroundColor: scheme.onSurface.withValues(alpha: .38),
  animationDuration: Duration.zero,
  minimumSize: Size(0, AppControl.heightScaled),
  padding: AppControl.paddingScaled,
  shape: _buttonShape,
  textStyle: _buttonTextStyle,
  // Material pads every button out to a 48px tap target — on a desktop app
  // that leaves a 32px button floating in a 48px box and wrecks every row it
  // sits in.
  tapTargetSize: MaterialTapTargetSize.shrinkWrap,
  enabledMouseCursor: SystemMouseCursors.click,
  visualDensity: VisualDensity.standard,
  // Its own wash, not [AppSurface.hoverFill]: this button already carries the
  // accent as a FILL, so the hover has to read against that rather than against
  // the page. White at 12% lifts the accent a step without turning it into a
  // second colour. See [_textButtonStyle] for why any of these are needed at
  // all — `NoSplash` took the ripple away and left nothing behind it.
  overlayColor: const Color(0x1FFFFFFF),
).copyWith(side: _controlRim(scheme, filled: true, highContrast: highContrast));

/// The secondary action: a hairline rim, no fill — Apple's "bordered" button.
ButtonStyle _outlinedButtonStyle(
  ColorScheme scheme, {
  bool highContrast = false,
}) => OutlinedButton.styleFrom(
  animationDuration: Duration.zero,
  minimumSize: Size(0, AppControl.heightScaled),
  padding: AppControl.paddingScaled,
  shape: _buttonShape,
  textStyle: _buttonTextStyle,
  side: BorderSide(color: scheme.onSurface.withValues(alpha: .14)),
  backgroundColor: scheme.onSurface.withValues(alpha: .04),
  foregroundColor: scheme.onSurface,
  tapTargetSize: MaterialTapTargetSize.shrinkWrap,
  enabledMouseCursor: SystemMouseCursors.click,
  visualDensity: VisualDensity.standard,
).copyWith(side: _controlRim(scheme, highContrast: highContrast));

/// A quiet capsule for secondary dialog and workspace actions.
ButtonStyle _textButtonStyle(
  ColorScheme scheme, {
  bool highContrast = false,
}) => TextButton.styleFrom(
  foregroundColor: scheme.onSurface,
  backgroundColor: scheme.onSurface.withValues(alpha: .055),
  side: BorderSide(color: scheme.onSurface.withValues(alpha: .10)),
  animationDuration: Duration.zero,
  minimumSize: Size(0, AppControl.heightScaled),
  padding: AppControl.paddingSmallScaled,
  shape: _buttonShape,
  textStyle: _buttonTextStyle,
  tapTargetSize: MaterialTapTargetSize.shrinkWrap,
  enabledMouseCursor: SystemMouseCursors.click,
  visualDensity: VisualDensity.standard,
  // ⚠️ Without this a text button has NO hover state at all.
  //
  // `splashFactory: NoSplash` turns Material's ripple off app-wide — right, it
  // is an Android idiom — but the ripple was also the only thing this theme
  // left drawing a response to the pointer. M3 derives its own overlay from
  // `foregroundColor`, and `styleFrom` here passes none, so the resolved
  // overlay came back **null**: the button lit up on press and on focus and did
  // nothing whatsoever on hover. On a desktop app, where the pointer is how you
  // find out what is clickable, that is a control that reads as a label.
  //
  // [AppSurface.hoverFill] is the same wash the rows and menu items already
  // use, so a button now answers the pointer the way everything around it does.
  overlayColor: AppSurface.hoverFill,
).copyWith(side: _controlRim(scheme, highContrast: highContrast));

/// Keep a real focus boundary without changing the control's layout. A filled
/// primary uses its contrasting label color; neutral controls use the accent.
WidgetStateProperty<BorderSide> _controlRim(
  ColorScheme scheme, {
  bool filled = false,
  bool highContrast = false,
}) => WidgetStateProperty.resolveWith((states) {
  final disabled = states.contains(WidgetState.disabled);
  return BorderSide(
    width: highContrast ? 2 : 1.5,
    color: filled
        ? Colors.transparent
        : scheme.onSurface.withValues(
            alpha: disabled
                ? .06
                : highContrast
                ? .6
                : .09,
          ),
  );
});

TextTheme _appTextTheme(Color primary, Color secondary) {
  // App controls share the system type hierarchy. Monospace is requested
  // explicitly by terminal content, code, and identifiers.
  final display = AppType.display(color: primary);
  final title = AppType.title(color: primary);
  final heading = AppType.heading(color: primary);
  final body = AppType.body(color: primary);
  final label = AppType.label(color: primary);
  return TextTheme(
    displayLarge: display,
    displayMedium: display,
    displaySmall: display,
    headlineLarge: title,
    headlineMedium: title,
    headlineSmall: title,
    titleLarge: title,
    titleMedium: heading,
    titleSmall: label,
    bodyLarge: body,
    bodyMedium: body,
    bodySmall: body.copyWith(color: secondary),
    labelLarge: label,
    labelMedium: label,
    labelSmall: AppType.caption(color: primary, fontWeight: AppFont.medium),
  );
}