Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(notch): let the user place the HUD capsule (side + vertical offset)
enes26c4e64e8171
diff --git a/docs/notch-hud.md b/docs/notch-hud.mdindex c63d398b0..a6716705a 100644--- a/docs/notch-hud.md+++ b/docs/notch-hud.md@@ -16,15 +16,18 @@ alwaysOnTop:true, focusable:false, skipTaskbar:true}` + `setAlwaysOnTop(true,'sc`renderer.input`) sharing the existing preload plus a small HUD-specific API.- **Geometry** is the pure `hudGeometry` (`notch-hud-geometry.ts`, unit-tested); the controller- only feeds it `screen.getPrimaryDisplay()`. The window spans the full top edge (`bounds`,- `y = bounds.y`), sized to `bar + HUD_WINDOW_HEIGHT` so the EXPANDED box clears the top strip in- either layout; we never resize the frame. Main sends the renderer everything it needs to draw the+ only feeds it `screen.getPrimaryDisplay()` — the PRIMARY display's LIVE bounds on every call,+ never a cached rectangle. The window spans the full top edge (`bounds`,+ `y = bounds.y`), sized to `bar + HUD_WINDOW_HEIGHT` (+ a positive vertical offset, so a lowered+ panel is not clipped) so the EXPANDED box clears the top strip in+ either layout; we never resize the frame except for that offset (`setTunables` → `reposition`).+ Main sends the renderer everything it needs to draw thecapsule: `bar` (= `workArea.y - bounds.y`, floor `NOTCH_BAR_FLOOR` 24 — the fused top zoneheight), `width`, `notchWidth` (`settings.notchWidth` clamped to `NOTCH_WIDTH_MIN/MAX` 100–320,- falling back to `NOTCH_WIDTH` **168** — Electron exposes no `auxiliaryTopLeftArea`, so assume a- centered notch of this width; 200 left a visible gap), `notchCenterX` (= `bounds.width/2`), and- `hasNotch`. Re-asserted on `screen` `display-metrics-changed` + `display-added/removed`.-+ falling back to `NOTCH_WIDTH_DEFAULT` **168** — Electron exposes no `auxiliaryTopLeftArea`, so+ assume a centered notch of this width; 200 left a visible gap), `notchCenterX`+ (= `bounds.width/2`), and the **placement** below. Re-asserted on `screen`+ `display-metrics-changed` + `display-added/removed`.**`hasNotch` is a RATIO, never an absolute px count** (`display.internal && inset / bounds.height>= NOTCH_BAR_RATIO` 0.03). macOS reserves a menu bar exactly as tall as the notch, so on anotched panel that strip is a fixed SHARE of the display and survives every scaling mode — a 15"@@ -35,6 +38,40 @@ alwaysOnTop:true, focusable:false, skipTaskbar:true}` + `setAlwaysOnTop(true,'scnotchless pill straight into the notch (issue #508). `display.internal` is the second half —notches exist only on built-in panels, so it stops an external at a low resolution from clearingthe ratio on its own.+- **Placement** is the pure `hudPlacement` (same file, unit-tested), fed the geometry plus the+ user's two placement settings — `settings.notchAlign` (`left | center | right`, default+ `center`) and `settings.notchOffsetY` (px, positive = DOWN, default 0) — and it answers with+ everything the renderer positions by: `fused`, `anchor`, `capsuleX`, `capsuleTop`, `panelLeft`,+ `panelWidth` (pushed as CSS variables + root classes; the renderer decides nothing itself).+ **`hasNotch` still decides the SHAPE, and the table says what each combination draws:**++ | display | side | offset | draws |+ |---|---|---|---|+ | notch | center | ≤ 0 | **fused** to the notch — the historical layout, bit-for-bit (a negative offset cannot go above the top edge, so it stays fused at 0) |+ | notch | center | > 0 | a **pill** hanging centred BELOW the notch (a detached surface with square top corners is the "black box below the menu bar" field bug, so it rounds) |+ | notch | left / right | any | a **pill** at that edge (`HUD_EDGE_MARGIN` 12 from it), below the menu-bar strip ± offset |+ | no notch | any | any | a **pill** on that side, below the strip ± offset — the old notchless fallback, now movable |++ Rules the placement keeps: **(1)** a pill's top is `bar + PILL_TOP_GAP + offset`, clamped at+ **0** — there is nothing above the display's top edge, which is why the Settings copy says "up+ stops at the top edge" instead of implying the capsule can leave the screen, and why `-48`+ (`NOTCH_OFFSET_MIN`) is enough travel: it reaches the edge from every real menu bar. **(2)** the+ expanded panel keeps the capsule's side but its left edge is clamped ON SCREEN (`panelLeft`:+ margin-flush at an edge, centred for `center`, and on a display too narrow for panel + margin it+ hugs the CHOSEN edge — a bare clamp dropped the margin on the far side), the #791 class of bug.+ **(3)** click-through follows the capsule for free — the capsule ELEMENT is the hotspot+ (`pointerenter`/`pointerleave` on it toggle `setIgnoreMouseEvents`), so wherever these numbers+ put it, the interactive region is exactly there and the rest of the strip stays transparent.+ **(4)** the grow-left overhang (`syncCapsuleOverhang`) applies to the FUSED shape only: a pill+ has no notch to cover, and the padding would be a dead black tail (which the notchless pill+ drew before this landed) or, at an edge, a black bar over the menu-bar items.+ **(5)** a hand-edited settings.json is hostile input: both values are re-validated at the point+ of use (`sanitizeNotchAlign` → `center` for an unknown string; `sanitizeNotchOffsetY` → 0 for a+ non-number, the nearest bound for out-of-range — the same rule as `sanitizeNotchWidth`), and the+ Settings section reads them through the same sanitizers so a control never binds to a value it+ cannot draw. All three live in `src/shared/notch-hud.ts`, which is also where the slider bounds+ come from — the section used to carry hand-copied `WIDTH_MIN/MAX` with a "keep in sync" comment.+- **Click-through with a hotspot**: window stays mouse-ignoring; the renderer reports pointerenter/leave of the indicator rect over IPC → main toggles `setIgnoreMouseEvents(false/true,{forward:true})`. Click in the hotspot → expand; click outside the expanded panel → collapse@@ -154,39 +191,48 @@ the transparent rest of the window stays click-through. Hidden entirely when idl`IPC.hudDismiss` → `model.dismiss(nodeId)`. It latches the state the row was hidden AT(`dismissedAt`), so a session hung in `working` (agent died mid-turn) stays hidden while anygenuine state change brings the row back. HUD-local only — the node/terminal is untouched.-- **Notchless fallback** (`hasNotch === false`, e.g. an external monitor or a display with no menu- bar): the `.notchless` root class draws the capsule as a **standalone floating pill** — all-corner- `--pill-radius`, since there is no notch to fuse with. Collapsed height = `--pill-height`; the- mascots center in the pill (no `--bar` padding to clear).-- **The pill hangs BELOW the top strip** (`top: calc(var(--bar) + var(--pill-top-gap))`), and that- is load-bearing rather than cosmetic. The window's top edge is the display's, so the first- `--bar` px are the menu-bar / notch strip; a pill placed there is centred on exactly the- coordinates a notch occupies, which made every notch MISdetection invisible instead of merely+- **Pill** (`fused === false` from `hudPlacement` — a notchless display, a left/right side, or a+ centred capsule lowered off the notch): the `.pill` root class (renamed from `.notchless`,+ because the shape is no longer only about the display) draws the capsule as a **standalone+ floating pill** — all-corner `--pill-radius`, since there is no notch to fuse with. Collapsed+ height = `--pill-height`; the mascots center in the pill (no `--bar` padding to clear).++ **The pill rests BELOW the top strip** (`--capsule-top` = `bar + PILL_TOP_GAP + offset`, clamped+ ≥ 0), and that is load-bearing rather than cosmetic. The window's top edge is the display's, so+ the first `--bar` px are the menu-bar / notch strip; a pill placed there is centred on exactly+ the coordinates a notch occupies, which made every notch MISdetection invisible instead of merelywrong — the visible half of issue #508. Clearing the strip means the fallback layout stays safeeven when the detector is not, and on a genuine notchless display the pill no longer paints over- the menu bar it used to overlap.--**Tunables** (main constants in `notch-hud.ts` and `notch-hud-geometry.ts`; CSS vars in-`hud.css :root`, defaults in parens — tune on a Mac): `NOTCH_WIDTH` (168) / `--notch-width` (main-pushes the real value on the first geometry push), `NOTCH_WIDTH_MIN/MAX` (100/320, the settings-clamp), `NOTCH_BAR_RATIO` (0.03, notch-detection threshold as a fraction of display height),-`NOTCH_BAR_FLOOR` (24), `HUD_WINDOW_HEIGHT` (460, added ON TOP of `bar`),+ the menu bar it used to overlap. The user CAN raise it into the strip with a negative offset —+ that is an explicit choice made in Settings, not the detector's guess, and it stops at the edge.++**Tunables** (shared constants in `src/shared/notch-hud.ts`, main constants in+`notch-hud-geometry.ts`; CSS vars in `hud.css :root`, defaults in parens — tune on a Mac):+`NOTCH_WIDTH_DEFAULT` (168) / `--notch-width` (main pushes the real value on the first geometry+push), `NOTCH_WIDTH_MIN/MAX` (100/320, the settings clamp), `NOTCH_OFFSET_MIN/MAX` (-48/240, the+vertical-offset clamp), `NOTCH_BAR_RATIO` (0.03, notch-detection threshold as a fraction of+display height), `NOTCH_BAR_FLOOR` (24), `HUD_WINDOW_HEIGHT` (460, added ON TOP of `bar`),+`HUD_PANEL_WIDTH` (400, pushed as `--panel-width` — main reasons with it for `panelLeft`, so the+CSS must not carry its own number), `PILL_TOP_GAP` (6), `HUD_EDGE_MARGIN` (12),`--capsule-drop` (0 — the bulge was dropped; kept only for the expand math),-`--capsule-radius` (16), `--panel-width` (400), `--panel-max-h` (420), `--capsule-dur` (0.22s)/`--capsule-ease`,-and the notchless `--pill-top-gap` (6) / `--pill-radius` (18) / `--pill-height` (30).+`--capsule-radius` (16), `--panel-max-h` (420), `--capsule-dur` (0.22s)/`--capsule-ease`,+and the pill's `--pill-radius` (18) / `--pill-height` (30).## Settings + lifecycle**Settings → Interface → Notch** (`NotchSection.tsx`, macOS-only: `nav.ts` marks the section-`macOnly` and `visibleSettingsGroups(isMac)` drops it elsewhere) owns all three knobs:-`notchHud` (default **true**), `notchWidth` (default 168 — the assumed notch width, i.e. the-flush-alignment knob, clamped to `NOTCH_WIDTH_MIN/MAX` in main) and `notchHoverExpand`+`macOnly` and `visibleSettingsGroups(isMac)` drops it elsewhere) owns all five knobs:+`notchHud` (default **true**), `notchAlign` (default `center` — Left / Center / Right segmented+pill), `notchOffsetY` (default 0 — the "Vertical position" slider, signed readout, whose copy+says up stops at the screen edge and that lowering the fused capsule detaches it into a pill),+`notchWidth` (default 168 — the assumed notch width, i.e. the flush-alignment knob, clamped to+`NOTCH_WIDTH_MIN/MAX` in main; only the fused shape uses it) and `notchHoverExpand`(default true; off = click-only, the renderer reads it from the `hoverExpand` push field).`initNotchHud(deps, tunables)` from `index.ts`, guarded `process.platform === 'darwin'`;`settingsStore.onChange` → `applyNotchHudSettings(tunables)` creates/destroys the window on the-enable toggle and pushes width/hover into a RUNNING controller (`setTunables`), so the width-slider moves the capsule as you drag it.+enable toggle and pushes width/side/offset/hover into a RUNNING controller (`setTunables`, which+goes through `reposition` because the offset can change the window height), so every slider moves+the capsule as you drag it — no restart, no toggle-off-on.The first-run tour has a macOS-only **notch step** (`OnboardingFlow`'s `STEPS` is ID-keyedprecisely so this step can be absent off macOS, plus `SceneNotch` in `scenes.tsx`): scene on thediff --git a/src/main/index.ts b/src/main/index.tsindex db1f4f1b0..8ef07f641 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -1993,6 +1993,8 @@ app.whenReady().then(async () => {return {enabled: s.notchHud,notchWidth: s.notchWidth,+ align: s.notchAlign,+ offsetY: s.notchOffsetY,hoverExpand: s.notchHoverExpand,percentMode: s.usagePercentMode}diff --git a/src/main/notch-hud-geometry.test.ts b/src/main/notch-hud-geometry.test.tsindex a71109d11..b23dfb637 100644--- a/src/main/notch-hud-geometry.test.ts+++ b/src/main/notch-hud-geometry.test.ts@@ -1,5 +1,16 @@import { describe, it, expect } from 'vitest'-import { hudGeometry, NOTCH_BAR_FLOOR, HUD_WINDOW_HEIGHT, type HudGeometryInput } from './notch-hud-geometry'+import {+ hudGeometry,+ hudPlacement,+ HUD_EDGE_MARGIN,+ HUD_PANEL_WIDTH,+ NOTCH_BAR_FLOOR,+ HUD_WINDOW_HEIGHT,+ PILL_TOP_GAP,+ type HudGeometryInput,+ type HudPlacementInput+} from './notch-hud-geometry'+import type { NotchAlign } from '../shared/notch-hud'/** A display, described the way Electron reports one: full bounds plus a menu-bar-shortened workArea. */function display(width: number, height: number, menuBar: number, internal: boolean): HudGeometryInput {@@ -7,7 +18,8 @@ function display(width: number, height: number, menuBar: number, internal: boolebounds: { x: 0, y: 0, width, height },workArea: { x: 0, y: menuBar, width, height: height - menuBar },internal,- notchWidth: 168+ notchWidth: 168,+ offsetY: 0}}@@ -60,6 +72,15 @@ describe('hudGeometry — window placement', () => {expect(hudGeometry(display(1024, 300, 24, false)).height).toBe(300)})+ it('grows the window by a DOWNWARD offset so a lowered panel is not clipped, and by nothing else', () => {+ const base = hudGeometry(display(1710, 1112, 37, true)).height+ expect(hudGeometry({ ...display(1710, 1112, 37, true), offsetY: 120 }).height).toBe(base + 120)+ // Raising needs no extra room; the historical height is kept bit-for-bit.+ expect(hudGeometry({ ...display(1710, 1112, 37, true), offsetY: -30 }).height).toBe(base)+ // The display edge still wins.+ expect(hudGeometry({ ...display(1024, 300, 24, false), offsetY: 240 }).height).toBe(300)+ })+it('floors a short menu bar so the mascots always have room', () => {expect(hudGeometry(display(1920, 1080, 12, false)).bar).toBe(NOTCH_BAR_FLOOR)})@@ -72,3 +93,112 @@ describe('hudGeometry — window placement', () => {expect(hudGeometry({ ...display(1710, 1112, 37, true), notchWidth: 220 }).notchWidth).toBe(220)})})++// ---- Capsule + panel placement ------------------------------------------------------------++/** A placement query over a 1710-wide notched display with a 37 px strip (15" Air default). */+function place(over: Partial<HudPlacementInput> = {}): HudPlacementInput {+ return {+ width: 1710,+ bar: 37,+ notchWidth: 168,+ notchCenterX: 855,+ hasNotch: true,+ align: 'center',+ offsetY: 0,+ ...over+ }+}++describe('hudPlacement — the shape (fused vs pill) per display × side × offset', () => {+ it('center on a notched display at offset 0 is the historical fused layout, bit-for-bit', () => {+ const p = hudPlacement(place())+ expect(p.fused).toBe(true)+ expect(p.capsuleTop).toBe(0)+ // Right edge pinned to the notch's right edge, as the old CSS computed it.+ expect(p.anchor).toBe('right')+ expect(p.capsuleX).toBe(855 + 84)+ // Expanded: centered under the notch.+ expect(p.panelLeft).toBe(855 - HUD_PANEL_WIDTH / 2)+ expect(p.panelWidth).toBe(HUD_PANEL_WIDTH)+ })++ it('a negative offset cannot raise the fused capsule above the top edge — it stays fused at 0', () => {+ const p = hudPlacement(place({ offsetY: -48 }))+ expect(p.fused).toBe(true)+ expect(p.capsuleTop).toBe(0)+ })++ it('a positive offset detaches the centered capsule into a pill hanging below the notch', () => {+ // A detached surface with square top corners is the "black box below the menu bar" field bug.+ const p = hudPlacement(place({ offsetY: 20 }))+ expect(p.fused).toBe(false)+ expect(p.anchor).toBe('center')+ expect(p.capsuleX).toBe(855)+ expect(p.capsuleTop).toBe(37 + PILL_TOP_GAP + 20)+ })++ it.each<NotchAlign>(['left', 'right'])('%s on a notched display is a pill at that edge, never fused', (align) => {+ const p = hudPlacement(place({ align }))+ expect(p.fused).toBe(false)+ expect(p.anchor).toBe(align)+ expect(p.capsuleX).toBe(align === 'left' ? HUD_EDGE_MARGIN : 1710 - HUD_EDGE_MARGIN)+ expect(p.capsuleTop).toBe(37 + PILL_TOP_GAP)+ })++ it('on a notchless display every side is a pill below the strip, and center is a centered pill', () => {+ const p = hudPlacement(place({ hasNotch: false, bar: 24 }))+ expect(p.fused).toBe(false)+ expect(p.anchor).toBe('center')+ expect(p.capsuleX).toBe(855)+ expect(p.capsuleTop).toBe(24 + PILL_TOP_GAP)+ expect(hudPlacement(place({ hasNotch: false, bar: 24, align: 'left' })).anchor).toBe('left')+ expect(hudPlacement(place({ hasNotch: false, bar: 24, align: 'right' })).anchor).toBe('right')+ })+})++describe('hudPlacement — vertical offset', () => {+ it('moves a pill down by the offset and up by a negative one', () => {+ expect(hudPlacement(place({ align: 'left', offsetY: 100 })).capsuleTop).toBe(37 + PILL_TOP_GAP + 100)+ expect(hudPlacement(place({ align: 'left', offsetY: -20 })).capsuleTop).toBe(37 + PILL_TOP_GAP - 20)+ })++ it('never raises a pill above the display top edge (there is nothing above it)', () => {+ expect(hudPlacement(place({ align: 'left', offsetY: -48 })).capsuleTop).toBe(0)+ expect(hudPlacement(place({ hasNotch: false, bar: 24, offsetY: -48 })).capsuleTop).toBe(0)+ })++ it('does not change the horizontal anchor', () => {+ const a = hudPlacement(place({ align: 'right' }))+ const b = hudPlacement(place({ align: 'right', offsetY: 150 }))+ expect([b.anchor, b.capsuleX, b.panelLeft]).toEqual([a.anchor, a.capsuleX, a.panelLeft])+ })+})++describe('hudPlacement — the expanded panel stays on screen', () => {+ const inside = (p: { panelLeft: number; panelWidth: number }, width: number): boolean =>+ p.panelLeft >= 0 && p.panelLeft + p.panelWidth <= width++ it('opens flush with the margin on the left, and ends at the margin on the right', () => {+ expect(hudPlacement(place({ align: 'left' })).panelLeft).toBe(HUD_EDGE_MARGIN)+ expect(hudPlacement(place({ align: 'right' })).panelLeft).toBe(1710 - HUD_EDGE_MARGIN - HUD_PANEL_WIDTH)+ })++ it.each<NotchAlign>(['left', 'center', 'right'])('is fully visible at %s on every display width we ship to', (align) => {+ for (const width of [1024, 1280, 1440, 1512, 1710, 1728, 2560, 3008]) {+ const p = hudPlacement(place({ align, width, notchCenterX: Math.round(width / 2) }))+ expect(inside(p, width), `${align} @ ${width}`).toBe(true)+ expect(inside(hudPlacement(place({ align, width, notchCenterX: Math.round(width / 2), hasNotch: false })), width)).toBe(true)+ }+ })++ it('on a display narrower than the panel plus its margin, hugs the CHOSEN edge rather than running off it', () => {+ const width = HUD_PANEL_WIDTH + 10+ // A bare clamp would have dropped the margin on the far side (left panel flush RIGHT).+ expect(hudPlacement(place({ align: 'left', width, notchCenterX: 205 })).panelLeft).toBe(0)+ expect(hudPlacement(place({ align: 'right', width, notchCenterX: 205 })).panelLeft).toBe(10)+ // Narrower than the panel itself: still on screen at 0, never negative.+ expect(hudPlacement(place({ align: 'right', width: 300, notchCenterX: 150 })).panelLeft).toBe(0)+ expect(hudPlacement(place({ align: 'center', width: 300, notchCenterX: 150 })).panelLeft).toBe(0)+ })+})diff --git a/src/main/notch-hud-geometry.ts b/src/main/notch-hud-geometry.tsindex b480ef783..38ce10d5d 100644--- a/src/main/notch-hud-geometry.ts+++ b/src/main/notch-hud-geometry.ts@@ -2,7 +2,11 @@//// Split out of notch-hud.ts so vitest can cover notch DETECTION without an Electron runtime: the// controller reads `screen.getPrimaryDisplay()` and hands the plain numbers here. Everything the-// HUD window and its renderer position themselves by is decided in this one function.+// HUD window and its renderer position themselves by is decided in this module: `hudGeometry`+// places the WINDOW (and detects the notch), `hudPlacement` places the CAPSULE and its expanded+// panel inside that window from the user's side / vertical-offset settings.++import type { NotchAlign } from '../shared/notch-hud'/** A rectangle in Electron's logical (point) coordinate space. */export interface Rect {@@ -21,6 +25,9 @@ export interface HudGeometryInput {internal: boolean/** Already-sanitized settings.notchWidth. */notchWidth: number+ /** Already-sanitized settings.notchOffsetY (px, positive = down). Only the window HEIGHT depends+ * on it here — a capsule pushed down needs the window to grow with it (see `hudPlacement`). */+ offsetY: number}export interface HudGeometry {@@ -74,14 +81,121 @@ export function hudGeometry(input: HudGeometryInput): HudGeometry {const bar = Math.max(NOTCH_BAR_FLOOR, inset)// A physical notch requires a built-in panel whose reserved strip is a notch-sized SHARE of it.const hasNotch = input.internal && inset > 0 && b.height > 0 && inset / b.height >= NOTCH_BAR_RATIO+ // A capsule lowered by `offsetY` drags its expanded panel down with it, so the window grows by the+ // same amount — otherwise the panel's bottom rows would be clipped by the window edge. A RAISED+ // capsule (negative) needs nothing extra, and offset 0 keeps the historical height bit-for-bit.+ const extra = Math.max(0, input.offsetY)return {x: b.x,y: b.y,width: b.width,- height: Math.min(bar + HUD_WINDOW_HEIGHT, b.height),+ height: Math.min(bar + HUD_WINDOW_HEIGHT + extra, b.height),bar,notchWidth: input.notchWidth,notchCenterX: Math.round(b.width / 2),hasNotch}}++// ---- Capsule + panel placement inside the window ------------------------------------------++/** Width of the EXPANDED session panel (px). Lives here, not only in hud.css, because the panel's+ * left edge is decided by `hudPlacement` (it has to stay on screen at every alignment) and the+ * renderer paints exactly the width main reasoned with (`--panel-width` is pushed). */+export const HUD_PANEL_WIDTH = 400+/** Gap between the menu-bar / notch strip and a floating pill's top edge (px). The pill's resting+ * place is BELOW the strip — load-bearing, see the `.pill .hud-capsule` note in hud.css. */+export const PILL_TOP_GAP = 6+/** Margin between a left/right-aligned capsule (and its panel) and the display's edge (px). */+export const HUD_EDGE_MARGIN = 12++export interface HudPlacementInput {+ /** Window / display width (px). */+ width: number+ /** Fused top-strip height (`HudGeometry.bar`). */+ bar: number+ notchWidth: number+ notchCenterX: number+ /** Notch present AND the window actually paints over it (main folds its own clamp check in). */+ hasNotch: boolean+ /** Already-sanitized settings.notchAlign / settings.notchOffsetY. */+ align: NotchAlign+ offsetY: number+}++export interface HudPlacement {+ /**+ * The SHAPE. `true` = the capsule is fused to the physical notch (square top corners at y=0,+ * grows left of the notch, expands under it). `false` = a standalone floating pill (all corners+ * rounded) — the only shape that makes sense once the capsule is not touching the notch.+ *+ * What each combination draws:+ * notch + center + offset ≤ 0 → fused to the notch (the historical layout; a negative offset+ * cannot go above the top edge, so it stays fused)+ * notch + center + offset > 0 → a pill hanging centered BELOW the notch+ * notch + left / right → a pill at that edge, below the menu-bar strip (± offset)+ * no notch, any side → a pill on that side, below the strip (± offset)+ */+ fused: boolean+ /** Which edge of the COLLAPSED capsule sits at `capsuleX` (the capsule is shrink-to-fit wide,+ * so it is positioned by an anchor + a CSS translate, not by a left/width pair). Fused = `right`+ * (its right edge butts against the notch's right edge); a pill = the chosen side. */+ anchor: NotchAlign+ /** X of that anchor edge (px, window coords). */+ capsuleX: number+ /** Top of the capsule (px, window coords) — 0 when fused; never negative (nothing is above the+ * display's top edge, so an offset that would raise the capsule past it is clamped there). */+ capsuleTop: number+ /** Left edge of the EXPANDED panel (px, window coords), clamped so the panel is on screen. */+ panelLeft: number+ panelWidth: number+}++/**+ * Where the capsule and its expanded panel sit, from the user's placement settings. Pure: the+ * renderer draws EXACTLY these numbers (pushed as CSS variables), and the click-through hotspot is+ * the capsule element itself, so the interactive region follows whatever this returns.+ */+export function hudPlacement(input: HudPlacementInput): HudPlacement {+ const { width, bar, notchWidth, notchCenterX, align, offsetY } = input+ const panelWidth = HUD_PANEL_WIDTH+ // Fused only when the capsule actually touches the notch. A positive offset detaches it, and a+ // detached capsule with square top corners is the "black box below the menu bar" field bug, so+ // it becomes a pill; a negative offset has nowhere to go (top edge) and stays fused at 0.+ const fused = input.hasNotch && align === 'center' && offsetY <= 0+ // Pill top: below the strip by default, pushed by the offset, and never above the display edge.+ const capsuleTop = fused ? 0 : Math.max(0, bar + PILL_TOP_GAP + offsetY)+ let anchor: NotchAlign+ let capsuleX: number+ if (fused) {+ anchor = 'right'+ capsuleX = notchCenterX + Math.round(notchWidth / 2)+ } else if (align === 'left') {+ anchor = 'left'+ capsuleX = HUD_EDGE_MARGIN+ } else if (align === 'right') {+ anchor = 'right'+ capsuleX = width - HUD_EDGE_MARGIN+ } else {+ anchor = 'center'+ capsuleX = notchCenterX+ }+ // The expanded panel keeps the capsule's side but is clamped INTO the display: anchored hard+ // left/right it must not run off the edge (the #791 class of bug — a surface that opens where it+ // cannot be seen). Center keeps the historical `center - width/2`. On a display too narrow for+ // the panel plus its margin, the margin is dropped on the CHOSEN side (a left panel hugs the+ // left edge, a right panel the right edge) — a bare clamp would have dropped it on the far side.+ const maxLeft = Math.max(0, width - panelWidth)+ const desired =+ align === 'left' && !fused+ ? HUD_EDGE_MARGIN + panelWidth <= width+ ? HUD_EDGE_MARGIN+ : 0+ : align === 'right' && !fused+ ? width - HUD_EDGE_MARGIN - panelWidth >= 0+ ? width - HUD_EDGE_MARGIN - panelWidth+ : maxLeft+ : notchCenterX - panelWidth / 2+ const panelLeft = Math.round(Math.max(0, Math.min(maxLeft, desired)))+ return { fused, anchor, capsuleX, capsuleTop, panelLeft, panelWidth }+}diff --git a/src/main/notch-hud.ts b/src/main/notch-hud.tsindex 68bc35e44..0196c66b2 100644--- a/src/main/notch-hud.ts+++ b/src/main/notch-hud.ts@@ -22,18 +22,17 @@ import {} from '../core/agent-status-mirror'import type { NormalizedAgentEvent } from '../shared/agents/normalize'import { createHudModel, type HudModel } from './notch-hud-model'-import { hudGeometry, type HudGeometry } from './notch-hud-geometry'--/**- * Assumed physical notch WIDTH (px). Electron exposes no `auxiliaryTopLeftArea`, so we assume a- * centered notch of this width, and the capsule butts against its LEFT edge. Field-tuned to 168 px- * (200 left a visible gap — the capsule sat too far left). TUNE ON A MAC: raise it to push the- * capsule LEFT, lower it to slide the capsule RIGHT toward the notch.- */-const NOTCH_WIDTH = 168-/** Bounds for the user-tunable notch width (settings.notchWidth). */-export const NOTCH_WIDTH_MIN = 100-export const NOTCH_WIDTH_MAX = 320+import { hudGeometry, hudPlacement, type HudGeometry } from './notch-hud-geometry'+import {+ sanitizeNotchAlign,+ sanitizeNotchOffsetY,+ sanitizeNotchWidth,+ type NotchAlign+} from '../shared/notch-hud'++// The notch-width constants + `sanitizeNotchWidth` moved to src/shared/notch-hud.ts (2026-09) so+// Settings → Notch reads the same bounds it clamps against; re-exported for existing importers.+export { NOTCH_WIDTH_MIN, NOTCH_WIDTH_MAX } from '../shared/notch-hud'/** Debounce for coalescing feed changes into one push to the HUD renderer. */const PUSH_DEBOUNCE_MS = 150/** Low-frequency sweep so stale (gone + idle > 6h) nodes drop even with no live events. */@@ -90,16 +89,18 @@ export interface NotchHudTunables {enabled: boolean/** Assumed physical notch width in px — the knob that makes the capsule sit flush. */notchWidth: number+ /** Which side of the primary display the capsule sits on (settings.notchAlign). */+ align: NotchAlign+ /** Vertical offset from the capsule's resting place, px, positive = down (settings.notchOffsetY). */+ offsetY: number/** Expand the panel on hover (else click-only). */hoverExpand: boolean/** settings.usagePercentMode — how the rows' context percentages render ("42% used" / "58% left"). */percentMode: 'used' | 'remaining' | 'tokens'}-/** Clamp a hand-editable width to something that can't push the capsule off the display. */-function sanitizeNotchWidth(px: number): number {- return Number.isFinite(px) ? Math.max(NOTCH_WIDTH_MIN, Math.min(NOTCH_WIDTH_MAX, Math.round(px))) : NOTCH_WIDTH-}+/** Everything but `enabled` — the values a RUNNING controller can take live. */+type LiveTunables = Omit<NotchHudTunables, 'enabled'>class NotchHudController {private model: HudModel = createHudModel()@@ -115,7 +116,7 @@ class NotchHudController {constructor(private deps: NotchHudDeps,- private tunables: { notchWidth: number; hoverExpand: boolean; percentMode: 'used' | 'remaining' | 'tokens' }+ private tunables: LiveTunables) {this.onSetIgnoreMouse = (_e, ignore) => {// Ignore-mouse ON = click-through (the strip is transparent to the app beneath); OFF while the@@ -232,20 +233,37 @@ class NotchHudController {this.ipcBound = false}- /** Apply live tunables and re-push, so a slider drag moves the capsule as you drag. */- setTunables(t: { notchWidth: number; hoverExpand: boolean; percentMode: 'used' | 'remaining' | 'tokens' }): void {- this.tunables = { notchWidth: t.notchWidth, hoverExpand: t.hoverExpand, percentMode: t.percentMode }- this.schedulePush()+ /** Apply live tunables and re-push, so a slider drag moves the capsule as you drag. Goes through+ * `reposition` rather than a bare push because the vertical offset changes the window HEIGHT+ * (a lowered panel needs room below it) — `setBounds` with unchanged bounds is a no-op. */+ setTunables(t: LiveTunables): void {+ this.tunables = {+ notchWidth: t.notchWidth,+ align: t.align,+ offsetY: t.offsetY,+ hoverExpand: t.hoverExpand,+ percentMode: t.percentMode+ }+ this.reposition()+ }++ /** The placement settings, re-validated HERE at the point of use (settings.json is hand-editable;+ * the type is compile-time only): an unknown side → center, a bad offset → 0 / the nearest bound. */+ private placementSettings(): { align: NotchAlign; offsetY: number } {+ return { align: sanitizeNotchAlign(this.tunables.align), offsetY: sanitizeNotchOffsetY(this.tunables.offsetY) }}private geometry(): HudGeometry {+ // Always the PRIMARY display's live bounds — never a cached rect — so a display change (or a+ // resolution change under a placement edit) is answered from what the screen reports now.const d = screen.getPrimaryDisplay()return hudGeometry({bounds: d.bounds,workArea: d.workArea,// `internal` is what keeps an external monitor at a low resolution from reading as notched.internal: d.internal === true,- notchWidth: sanitizeNotchWidth(this.tunables.notchWidth)+ notchWidth: sanitizeNotchWidth(this.tunables.notchWidth),+ offsetY: this.placementSettings().offsetY})}@@ -346,6 +364,17 @@ class NotchHudController {// fused top strip would only make the capsule a tall detached box — the exact field bug. Tell// the renderer so it drops the reserved strip and draws a compact pill instead.const clamped = w.getBounds().y > g.y+ // Where the capsule and its panel sit, from the user's side + offset. Fed the SAME hasNotch the+ // renderer used to key its shape on (detection AND the clamp check), so "fused" can never be+ // claimed for a window that cannot paint over the notch.+ const p = hudPlacement({+ width: g.width,+ bar: g.bar,+ notchWidth: g.notchWidth,+ notchCenterX: g.notchCenterX,+ hasNotch: g.hasNotch && !clamped,+ ...this.placementSettings()+ })w.webContents.send(IPC.hudRows, {rows,bar: g.bar,@@ -354,7 +383,12 @@ class NotchHudController {hoverExpand: this.tunables.hoverExpand,percentMode: this.tunables.percentMode,notchCenterX: g.notchCenterX,- hasNotch: g.hasNotch && !clamped+ fused: p.fused,+ anchor: p.anchor,+ capsuleX: p.capsuleX,+ capsuleTop: p.capsuleTop,+ panelLeft: p.panelLeft,+ panelWidth: p.panelWidth})}}@@ -383,8 +417,8 @@ export function initNotchHud(deps: NotchHudDeps, t: NotchHudTunables): void {/*** Live settings apply: create/destroy the window on the enable toggle, and push the geometry- * tunables (notch width, hover-expand) straight through to a running HUD — no restart, so the- * width slider can be dragged while watching the capsule move.+ * tunables (notch width, side, vertical offset, hover-expand) straight through to a running HUD —+ * no restart, so the width / offset sliders can be dragged while watching the capsule move.*/export function applyNotchHudSettings(t: NotchHudTunables): void {if (!supported()) returndiff --git a/src/preload/hud.ts b/src/preload/hud.tsindex dab58a0ff..79e39c520 100644--- a/src/preload/hud.ts+++ b/src/preload/hud.ts@@ -33,10 +33,22 @@ export interface HudPush {width: number/** Assumed physical notch width in px — the capsule's collapsed (fused) width. */notchWidth: number- /** Notch horizontal center in px (= width / 2) — where the capsule anchors. */+ /** Notch horizontal center in px (= width / 2). */notchCenterX: number- /** True when a physical notch is present (fuse to it); false = draw a standalone floating pill. */- hasNotch: boolean+ /** The SHAPE (main's `hudPlacement`): true = the capsule is fused to the physical notch (square+ * top at y=0, grows left of the notch); false = a standalone floating pill. This replaced a bare+ * `hasNotch` — a notched Mac with the capsule on the LEFT is also a pill. */+ fused: boolean+ /** Which capsule edge sits at `capsuleX` (collapsed): fused = right (butts the notch's right+ * edge); a pill = the side the user chose. */+ anchor: 'left' | 'center' | 'right'+ /** X of that anchor edge (px, window coords). */+ capsuleX: number+ /** Capsule top (px, window coords): 0 fused, else below the strip ± the user's offset, ≥ 0. */+ capsuleTop: number+ /** Expanded panel's left edge (px) — already clamped on screen by main — and its width. */+ panelLeft: number+ panelWidth: number/** Expand the panel on hover (settings.notchHoverExpand); false = click-only. */hoverExpand: boolean/** settings.usagePercentMode — how a row's context percentage renders ("42% used" / "58% left"). */diff --git a/src/renderer/components/settings/sections/NotchSection.tsx b/src/renderer/components/settings/sections/NotchSection.tsxindex 10035bc58..9bb72bfba 100644--- a/src/renderer/components/settings/sections/NotchSection.tsx+++ b/src/renderer/components/settings/sections/NotchSection.tsx@@ -3,10 +3,16 @@ import { SettingsSection } from '../SettingsSection'import { SearchableRow } from '../SearchableRow'import { FieldRow } from '../FieldRow'import { Switch } from '@renderer/ui/Switch'--/** Keep in sync with NOTCH_WIDTH_MIN/MAX in src/main/notch-hud.ts (which clamps anyway). */-const WIDTH_MIN = 100-const WIDTH_MAX = 320+import { SegmentedPill } from '@renderer/ui/SegmentedPill'+import {+ NOTCH_OFFSET_MAX,+ NOTCH_OFFSET_MIN,+ NOTCH_WIDTH_MAX,+ NOTCH_WIDTH_MIN,+ sanitizeNotchAlign,+ sanitizeNotchOffsetY,+ type NotchAlign+} from '@shared/notch-hud'const ROWS = {enabled: {@@ -17,6 +23,14 @@ const ROWS = {title: 'Notch width',keywords: ['notch', 'width', 'flush', 'align', 'capsule', 'position', 'offset', 'tune']},+ side: {+ title: 'Capsule side',+ keywords: ['notch', 'side', 'left', 'right', 'center', 'centre', 'align', 'position', 'place', 'corner', 'capsule']+ },+ offset: {+ title: 'Vertical position',+ keywords: ['notch', 'vertical', 'offset', 'raise', 'lower', 'up', 'down', 'height', 'position', 'move', 'capsule']+ },hover: {title: 'Expand on hover',keywords: ['notch', 'hover', 'expand', 'panel', 'click', 'open', 'sessions']@@ -24,17 +38,33 @@ const ROWS = {}const ENTRIES = Object.values(ROWS)+/** "+12 px" / "−8 px" / "0 px" — a signed readout so the direction is legible at a glance. */+function offsetLabel(px: number): string {+ if (px > 0) return `+${px} px`+ if (px < 0) return `−${-px} px`+ return '0 px'+}+/*** Settings → Interface → Notch (macOS only; the page only renders it on darwin).** Everything the notch capsule exposes lives here rather than in Appearance: the enable toggle, the* notch-width knob (macOS exposes no API for the real notch width, so the capsule has to assume one- * — this is how you make it sit flush on YOUR Mac), and hover-vs-click expansion. All three apply- * live: dragging the width slider moves the capsule as you drag.+ * — this is how you make it sit flush on YOUR Mac), the two PLACEMENT controls (which side of the+ * display, and how far up/down), and hover-vs-click expansion. Everything applies live: dragging a+ * slider moves the capsule as you drag.+ *+ * The slider bounds and the sanitizers are the SAME constants main clamps against+ * (`@shared/notch-hud`), so the range on screen cannot drift from the clamp.*/export function NotchSection({ isActive }: { isActive: boolean }): React.JSX.Element {const notchHud = useSettings((s) => s.settings.notchHud)const notchWidth = useSettings((s) => s.settings.notchWidth)+ // Read through the sanitizers: settings.json is hand-editable, and a control bound to a value it+ // cannot represent (an unknown side, NaN) would render blank and overwrite the file on the next+ // interaction. Reading it as main will read it keeps the control honest about what is drawn.+ const notchAlign = useSettings((s) => sanitizeNotchAlign(s.settings.notchAlign))+ const notchOffsetY = useSettings((s) => sanitizeNotchOffsetY(s.settings.notchOffsetY))const hoverExpand = useSettings((s) => s.settings.notchHoverExpand)const update = useSettings((s) => s.update)return (@@ -66,16 +96,59 @@ export function NotchSection({ isActive }: { isActive: boolean }): React.JSX.Ele}aria-disabled={!notchHud}>+ <SearchableRow {...ROWS.side}>+ <FieldRow+ label="Capsule side"+ description="Center hugs the notch (on a screen without one, a floating pill in the middle). Left and Right draw a floating pill at that edge of the screen, just below the menu bar."+ control={+ <SegmentedPill<NotchAlign>+ value={notchAlign}+ options={[+ { value: 'left', label: 'Left' },+ { value: 'center', label: 'Center' },+ { value: 'right', label: 'Right' }+ ]}+ onChange={(v) => update({ notchAlign: v })}+ ariaLabel="Notch capsule side"+ />+ }+ />+ </SearchableRow>++ <SearchableRow {...ROWS.offset}>+ <FieldRow+ label="Vertical position"+ description="Nudges the capsule down (positive) or up (negative) from where it normally sits. Up stops at the top edge of the screen — and the capsule fused to the notch is already there, so it can only move down, which turns it into a floating pill under the notch."+ control={+ <div className="flex items-center gap-3">+ <input+ type="range"+ min={NOTCH_OFFSET_MIN}+ max={NOTCH_OFFSET_MAX}+ step={2}+ value={notchOffsetY}+ aria-label="Notch capsule vertical offset in pixels"+ onChange={(e) => update({ notchOffsetY: Number(e.target.value) })}+ className="w-40 accent-[var(--accent)]"+ />+ <span className="w-14 text-right text-[12px] text-muted tabular-nums">+ {offsetLabel(notchOffsetY)}+ </span>+ </div>+ }+ />+ </SearchableRow>+<SearchableRow {...ROWS.width}><FieldRowlabel="Notch width"- description="macOS doesn't tell apps how wide the notch is, so the capsule assumes it. Nudge this until the capsule sits flush against the notch — larger moves it left, smaller moves it right."+ description="macOS doesn't tell apps how wide the notch is, so the capsule assumes it. Nudge this until the capsule sits flush against the notch — larger moves it left, smaller moves it right. Only the centered, notch-hugging capsule uses it."control={<div className="flex items-center gap-3"><inputtype="range"- min={WIDTH_MIN}- max={WIDTH_MAX}+ min={NOTCH_WIDTH_MIN}+ max={NOTCH_WIDTH_MAX}step={2}value={notchWidth}aria-label="Assumed notch width in pixels"diff --git a/src/renderer/hud/hud.css b/src/renderer/hud/hud.cssindex 8c9db8fdf..5474883a5 100644--- a/src/renderer/hud/hud.css+++ b/src/renderer/hud/hud.css@@ -17,13 +17,18 @@/* Unused while collapsed (the capsule never exceeds --bar); kept for the expand math only. */--capsule-drop: 0px;--capsule-radius: 16px; /* bottom-corner radius of the fused capsule */- --panel-width: 400px; /* expanded panel width */+ --panel-width: 400px; /* expanded panel width (HUD_PANEL_WIDTH, pushed from main) */--panel-max-h: 420px; /* expanded panel max content height (rows scroll past it) */--capsule-bg: #000; /* opaque black — fuses with the physical notch (no seam) */--capsule-ease: cubic-bezier(0.22, 1, 0.36, 1); /* spring-ish grow */--capsule-dur: 0.22s;- /* Notchless fallback (no physical notch): a standalone floating pill. */- --pill-top-gap: 6px; /* gap between the menu-bar strip and the floating pill */+ /* Placement (from main's hudPlacement — see .hud-capsule below); the defaults only cover the+ instant before the first push. */+ --capsule-x: 50%;+ --capsule-top: 0px;+ --panel-left: 50%;+ /* Floating pill (no notch, a side alignment, or lowered off the notch). The pill's top gap is+ PILL_TOP_GAP in notch-hud-geometry.ts and arrives inside --capsule-top. */--pill-radius: 18px; /* all-corner radius of the floating pill */--pill-height: 30px; /* collapsed floating-pill height */}@@ -56,16 +61,23 @@ body {appears WIDER, never taller (owner's call: no extra height). Its right edge butts against thenotch (square), only the bottom-left corner rounds. EXPANDED the same surface re-centres underthe notch and grows DOWNWARD into the session panel. `max-height` (not `height`) drives the- vertical grow so the reveal animates with content of unknown height. */+ vertical grow so the reveal animates with content of unknown height.++ WHERE it sits is not decided here. Main's pure `hudPlacement` (notch-hud-geometry.ts) pushes+ `--capsule-x` (the anchor edge's x), an `anchor-left|center|right` root class (which capsule+ edge sits at that x), `--capsule-top`, and `--panel-left` / `--panel-width` for the expanded+ box — from the user's side + vertical-offset settings and the display's live bounds. The+ renderer only applies them: the capsule element IS the click-through hotspot, so drawing it+ from these numbers is what keeps the interactive region wherever the capsule went. */.hud-capsule {position: absolute;- top: 0;- /* Widened SIDEWAYS, never taller (owner: "notch'a ekstra height vermek istemiyorum") — and- LEFT-ONLY: the right edge is pinned to the notch's right edge, so the capsule can never- creep over the menu-bar status items (or swallow their clicks) however many mascots are- running. main.ts pads the right by exactly the notch width; the mascots occupy the strip- LEFT of it (issue #78). */- left: calc(var(--notch-center-x, 50%) + var(--notch-width, 200px) / 2);+ top: var(--capsule-top, 0px);+ /* Fused: x = notch centre + notch-width/2 with anchor-right, i.e. the right edge pinned to the+ notch's right edge — widened SIDEWAYS, never taller (owner: "notch'a ekstra height vermek+ istemiyorum") and LEFT-ONLY, so the capsule can never creep over the menu-bar status items+ (or swallow their clicks) however many mascots are running. main.ts pads the right by exactly+ the notch width; the mascots occupy the strip LEFT of it (issue #78). */+ left: var(--capsule-x, 50%);transform: translateX(-100%);/* Shrink-to-fit so however many mascots are running, none clip. */width: auto;@@ -86,38 +98,56 @@ body {left var(--capsule-dur) var(--capsule-ease),transform var(--capsule-dur) var(--capsule-ease);}+/* Which edge of the collapsed capsule sits at --capsule-x. Fused pushes anchor-right (the default+ transform above); a pill pushes the side the user chose. */+.anchor-left .hud-capsule {+ transform: none;+}+.anchor-center .hud-capsule {+ transform: translateX(-50%);+}+.anchor-right .hud-capsule {+ transform: translateX(-100%);+}.hud-capsule--hidden {display: none; /* idle: no empty black pill */}-/* EXPANDED: re-centre under the notch and grow DOWNWARD into the panel. The height only appears- on click — collapsed, the strip is never taller than the real notch. */-.hud-capsule.expanded {- left: var(--notch-center-x, 50%);- transform: translateX(-50%);+/* EXPANDED: grow DOWNWARD into the panel, at the left edge main already clamped ON SCREEN for the+ chosen side (centred under the notch for `center`; flush with the margin at an edge — a panel+ anchored hard right must not run off the display, the #791 class of bug). The height only+ appears on click — collapsed, the strip is never taller than the real notch. */+.hud-capsule.expanded,+.anchor-left .hud-capsule.expanded,+.anchor-center .hud-capsule.expanded,+.anchor-right .hud-capsule.expanded {+ left: var(--panel-left, 50%);+ transform: none;width: var(--panel-width);max-height: calc(var(--bar) + var(--panel-max-h) + 20px);border-radius: 0 0 var(--capsule-radius) var(--capsule-radius);}-/* Notchless display: a standalone floating pill (no notch to fuse with) — all-corner radius so it- reads as its own Dynamic-Island-like element, not a black bar at y=0.+/* PILL (`fused: false` from main): a standalone floating capsule — all-corner radius so it reads+ as its own Dynamic-Island-like element, not a black bar at y=0. This class used to be+ `notchless`, and the rename is the point: the shape is no longer only about the display. A+ notched Mac draws a pill too when the capsule is on the LEFT/RIGHT, or lowered off the notch by+ the vertical-offset setting (a detached surface with square top corners is the "black box below+ the menu bar" field bug). A notchless display is a pill at every side.- LOAD-BEARING: the pill hangs BELOW `--bar`, never inside it. The window's top edge is the+ LOAD-BEARING: by default the pill hangs BELOW `--bar`, never inside it (main computes+ `--capsule-top` = bar + PILL_TOP_GAP + offset, clamped ≥ 0). The window's top edge is thedisplay's, so the top `--bar` px are the menu-bar / notch strip; a pill placed there is centredon exactly the coordinates a notch occupies. That made every notch MISdetection invisible ratherthan merely wrong — issue #508, where scaled resolutions pushed the detector below its thresholdand the pill landed behind the notch. Clearing the strip means the fallback layout is safe evenwhen the detector is not, and on a genuine notchless display the pill no longer paints over the- menu bar it used to overlap. */-.notchless .hud-capsule {- /* No notch to butt against — centre the pill instead of hanging it off the notch's left edge. */- left: var(--notch-center-x, 50%);- transform: translateX(-50%);- top: calc(var(--bar) + var(--pill-top-gap));+ menu bar it used to overlap. The user CAN raise it into the strip with a negative offset — that+ is their explicit choice, and it stops at the display's top edge. */+.pill .hud-capsule {max-height: var(--pill-height);border-radius: var(--pill-radius);}-.notchless .hud-capsule.expanded {+.pill .hud-capsule.expanded {max-height: calc(var(--panel-max-h) + 16px);border-radius: var(--pill-radius);}@@ -139,7 +169,7 @@ body {.hud-capsule.expanded .hud-indicator {display: none;}-.notchless .hud-indicator {+.pill .hud-indicator {height: var(--pill-height);padding-top: 0; /* no notch to clear — center in the pill */}@@ -282,7 +312,7 @@ body {opacity: 0;transition: opacity 0.16s ease 0.06s;}-.notchless .hud-panel {+.pill .hud-panel {padding-top: 8px; /* no notch to clear */}.hud-capsule.expanded .hud-panel {diff --git a/src/renderer/hud/main.ts b/src/renderer/hud/main.tsindex eb51b7566..eb0af244c 100644--- a/src/renderer/hud/main.ts+++ b/src/renderer/hud/main.ts@@ -40,9 +40,16 @@ interface HudPush {width: numbernotchWidth: numbernotchCenterX: number- hasNotch: booleanhoverExpand: booleanpercentMode?: 'used' | 'remaining' | 'tokens'+ // Placement (main's pure `hudPlacement`, docs/notch-hud.md): the shape, and where the collapsed+ // capsule / expanded panel sit. The renderer draws EXACTLY these — it decides nothing itself.+ fused: boolean+ anchor: 'left' | 'center' | 'right'+ capsuleX: number+ capsuleTop: number+ panelLeft: number+ panelWidth: number}interface HudApi {onRows(cb: (push: HudPush) => void): () => void@@ -75,8 +82,10 @@ root.append(capsule)let expanded = falselet latestRows: HudRow[] = []-// Notch width from main's geometry push — drives the symmetric right-hand padding.+// Notch width from main's geometry push — drives the fused capsule's right-hand padding.let notchWidthPx = 168+// Shape from main's placement push: fused to the notch (grow-left overhang applies) or a pill.+let fused = true// Hover-to-expand (settings.notchHoverExpand). Off = the capsule only expands on click.let hoverExpand = true// settings.usagePercentMode — the same number/label the other context surfaces render (issue #78).@@ -423,8 +432,11 @@ function buildSubItem(s: HudSubagentRow): HTMLElement {// kadar genişlettiysen sağdan da o kadar"): on a crowded menu bar the symmetric right-hand// overhang sat ON TOP of the status items, and because the capsule is the click-through hotspot,// hovering there also swallowed their clicks (issue #78 — grow-left approved by the owner there).+// FUSED ONLY: a floating pill has no notch to cover, so the padding would just be a dead black+// tail to the right of the mascots (which is what the notchless pill drew before placement+// landed; on a left/right-aligned pill it would also have hung over the menu-bar items).function syncCapsuleOverhang(): void {- if (expanded) {+ if (expanded || !fused) {capsule.style.paddingRight = ''return}@@ -453,8 +465,28 @@ function applyGeometry(push: HudPush): void {if (typeof push.notchCenterX === 'number') rs.setProperty('--notch-center-x', `${push.notchCenterX}px`)if (typeof push.hoverExpand === 'boolean') hoverExpand = push.hoverExpandif (push.percentMode === 'used' || push.percentMode === 'remaining' || push.percentMode === 'tokens') percentMode = push.percentMode- // No physical notch → draw a standalone floating pill instead of fusing to y=0.- document.documentElement.classList.toggle('notchless', push.hasNotch === false)+ applyPlacement(push)+}++/** Placement: the shape class + the anchor class + the four pushed numbers as CSS variables. The+ * capsule element is the click-through hotspot, so moving it here moves the interactive region+ * with it — nothing else tracks where the capsule is. */+function applyPlacement(push: HudPush): void {+ const rs = document.documentElement.style+ const cls = document.documentElement.classList+ fused = push.fused !== false+ // `pill` = not fused: a standalone floating capsule (all corners rounded). It replaced the old+ // `notchless` class because the shape is no longer only about the display — a notched Mac with+ // the capsule on the left, or lowered off the notch, is a pill too.+ cls.toggle('pill', !fused)+ const anchor = push.anchor === 'left' || push.anchor === 'right' ? push.anchor : 'center'+ cls.toggle('anchor-left', anchor === 'left')+ cls.toggle('anchor-center', anchor === 'center')+ cls.toggle('anchor-right', anchor === 'right')+ if (typeof push.capsuleX === 'number') rs.setProperty('--capsule-x', `${push.capsuleX}px`)+ if (typeof push.capsuleTop === 'number') rs.setProperty('--capsule-top', `${push.capsuleTop}px`)+ if (typeof push.panelLeft === 'number') rs.setProperty('--panel-left', `${push.panelLeft}px`)+ if (typeof push.panelWidth === 'number') rs.setProperty('--panel-width', `${push.panelWidth}px`)}window.hud.onRows((push: HudPush) => {diff --git a/src/shared/notch-hud.test.ts b/src/shared/notch-hud.test.tsnew file mode 100644index 000000000..93452e47e--- /dev/null+++ b/src/shared/notch-hud.test.ts@@ -0,0 +1,73 @@+import { describe, it, expect } from 'vitest'+import {+ NOTCH_OFFSET_MAX,+ NOTCH_OFFSET_MIN,+ NOTCH_WIDTH_DEFAULT,+ NOTCH_WIDTH_MAX,+ NOTCH_WIDTH_MIN,+ sanitizeNotchAlign,+ sanitizeNotchOffsetY,+ sanitizeNotchWidth+} from './notch-hud'++// settings.json is hand-editable: every one of these is a value a user (or a future build) can put+// there, and none may reach the window as anything but a value the layout can draw.++describe('sanitizeNotchAlign', () => {+ it('passes the three known sides through', () => {+ expect(sanitizeNotchAlign('left')).toBe('left')+ expect(sanitizeNotchAlign('center')).toBe('center')+ expect(sanitizeNotchAlign('right')).toBe('right')+ })++ it.each([+ ['a typo', 'centre'],+ ['a case mismatch', 'Left'],+ ['a future value', 'top'],+ ['a number', 1],+ ['null', null],+ ['undefined', undefined],+ ['an object with a matching key', { left: true }]+ ])('falls back to center for %s', (_label, v) => {+ expect(sanitizeNotchAlign(v)).toBe('center')+ })+})++describe('sanitizeNotchOffsetY', () => {+ it('keeps an in-range integer, and rounds a fractional one', () => {+ expect(sanitizeNotchOffsetY(12)).toBe(12)+ expect(sanitizeNotchOffsetY(-12)).toBe(-12)+ expect(sanitizeNotchOffsetY(7.6)).toBe(8)+ expect(sanitizeNotchOffsetY(0)).toBe(0)+ })++ it('clamps an out-of-range value to the nearest bound, keeping its direction', () => {+ expect(sanitizeNotchOffsetY(10_000)).toBe(NOTCH_OFFSET_MAX)+ expect(sanitizeNotchOffsetY(-10_000)).toBe(NOTCH_OFFSET_MIN)+ })++ it.each([+ ['NaN', NaN],+ ['Infinity', Infinity],+ ['-Infinity', -Infinity],+ ['a numeric string', '20'],+ ['null', null],+ ['undefined', undefined],+ ['a boolean', true]+ ])('falls back to 0 for %s', (_label, v) => {+ expect(sanitizeNotchOffsetY(v)).toBe(0)+ })+})++describe('sanitizeNotchWidth (moved here from notch-hud.ts, behaviour pinned)', () => {+ it('clamps to the slider bounds and rounds', () => {+ expect(sanitizeNotchWidth(50)).toBe(NOTCH_WIDTH_MIN)+ expect(sanitizeNotchWidth(900)).toBe(NOTCH_WIDTH_MAX)+ expect(sanitizeNotchWidth(180.4)).toBe(180)+ })+ it('falls back to the field-tuned default for a non-number', () => {+ expect(sanitizeNotchWidth(NaN)).toBe(NOTCH_WIDTH_DEFAULT)+ expect(sanitizeNotchWidth('168')).toBe(NOTCH_WIDTH_DEFAULT)+ expect(sanitizeNotchWidth(undefined)).toBe(NOTCH_WIDTH_DEFAULT)+ })+})diff --git a/src/shared/notch-hud.ts b/src/shared/notch-hud.tsnew file mode 100644index 000000000..6f19b39c6--- /dev/null+++ b/src/shared/notch-hud.ts@@ -0,0 +1,58 @@+// macOS Notch HUD — the user-tunable PLACEMENT values and their sanitizers (docs/notch-hud.md).+//+// Shared because two sides consume the same numbers: main clamps them at the point of use+// (`notch-hud.ts` → `hudGeometry` / `hudPlacement`), and Settings → Notch draws its controls from+// the same bounds, so the slider range and the clamp can never drift apart (they used to be two+// hand-copied constants with a "keep in sync" comment).+//+// Every value here comes from settings.json, which is hand-editable — a hostile input. Nothing+// trusts the TypeScript type: `sanitize*` re-validates at runtime and an unrecognised value falls+// back to the default, never to a guess.++/** Which side of the primary display the capsule sits on. `center` is the historical layout. */+export type NotchAlign = 'left' | 'center' | 'right'+export const NOTCH_ALIGNS: readonly NotchAlign[] = ['left', 'center', 'right']+export const NOTCH_ALIGN_DEFAULT: NotchAlign = 'center'++/**+ * Assumed physical notch WIDTH (px). Electron exposes no `auxiliaryTopLeftArea`, so we assume a+ * centered notch of this width, and the capsule butts against its LEFT edge. Field-tuned to 168 px+ * (200 left a visible gap — the capsule sat too far left). TUNE ON A MAC: raise it to push the+ * capsule LEFT, lower it to slide the capsule RIGHT toward the notch.+ */+export const NOTCH_WIDTH_DEFAULT = 168+/** Bounds for the user-tunable notch width (settings.notchWidth). */+export const NOTCH_WIDTH_MIN = 100+export const NOTCH_WIDTH_MAX = 320++/**+ * Bounds for the vertical offset (settings.notchOffsetY, px, positive = DOWN). The offset is+ * relative to where the capsule rests by default, and the effective value is additionally clamped+ * at the display's top edge by `hudPlacement` — there is nothing above it. The minimum only needs+ * to reach that edge from the floating pill's resting place (menu bar ≈ 24–37 px + its gap), so+ * -48 covers every real menu bar; a bigger number would just be dead slider travel.+ */+export const NOTCH_OFFSET_MIN = -48+export const NOTCH_OFFSET_MAX = 240+export const NOTCH_OFFSET_DEFAULT = 0++/** Clamp a hand-editable width to something that can't push the capsule off the display. */+export function sanitizeNotchWidth(px: unknown): number {+ return typeof px === 'number' && Number.isFinite(px)+ ? Math.max(NOTCH_WIDTH_MIN, Math.min(NOTCH_WIDTH_MAX, Math.round(px)))+ : NOTCH_WIDTH_DEFAULT+}++/** An unknown alignment string (typo, a future value on an older build) draws the historical+ * centered layout — never a pill on a side nobody asked for. */+export function sanitizeNotchAlign(v: unknown): NotchAlign {+ return typeof v === 'string' && (NOTCH_ALIGNS as readonly string[]).includes(v) ? (v as NotchAlign) : NOTCH_ALIGN_DEFAULT+}++/** Non-finite / non-numeric → the default resting place (0); out of range → the nearest bound+ * (the same rule as the width: keep the direction the user asked for, drop the excess). */+export function sanitizeNotchOffsetY(v: unknown): number {+ return typeof v === 'number' && Number.isFinite(v)+ ? Math.max(NOTCH_OFFSET_MIN, Math.min(NOTCH_OFFSET_MAX, Math.round(v)))+ : NOTCH_OFFSET_DEFAULT+}diff --git a/src/shared/types.ts b/src/shared/types.tsindex d473d4783..9f4f84ef7 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -14,6 +14,7 @@ import type { ClientId, DinoSnapshot, PeerDiff, PeerIdentity, PeerState } from 'import type { WhisperModelInfo } from './speech'import type { ProjectKanbanGitHub } from './github-issues'import type { CodexAccount } from './codex-account'+import type { NotchAlign } from './notch-hud'import type { ProjectIcon, ProjectIconPickResult } from './project-icon'import type { CanvasLayout, LayoutViewports } from './canvas-layout'import type {@@ -1751,6 +1752,14 @@ export interface Settings {* `auxiliaryTopLeftArea`), so the capsule has to assume one — this is the knob that makes it sit* flush on YOUR Mac. Bigger = the capsule sits further left. */notchWidth: number+ /** Which side of the primary display the capsule sits on. `center` (default) hugs the physical+ * notch; `left` / `right` draw a floating pill at that edge. Re-validated at use+ * (`sanitizeNotchAlign`, shared/notch-hud.ts): an unknown string means `center`. */+ notchAlign: NotchAlign+ /** Vertical offset of the capsule from its resting place, px, positive = DOWN. Up is bounded by+ * the display's top edge (the fused notch capsule is already there, so it only moves down —+ * and moving it detaches it into a pill). Clamped to NOTCH_OFFSET_MIN/MAX; non-finite → 0. */+ notchOffsetY: number/** Expand the notch panel on hover (after a short dwell). Off = click the capsule to expand. */notchHoverExpand: boolean/** Dictation (desktop/server). Written as a whole object by the renderer. */@@ -1916,6 +1925,8 @@ export const DEFAULT_SETTINGS: Settings = {// macOS Notch HUD default ON (guarded to darwin at runtime; a no-op elsewhere).notchHud: true,notchWidth: 168,+ notchAlign: 'center',+ notchOffsetY: 0,notchHoverExpand: true,// model: '' = the explicit "no dictation" state (SPEECH_MODEL_NONE, issue #143). Dictation is// opt-in: nothing is selected — and so nothing downloads and no shortcut records — until the