feat!: directional notch — zone-aware auto, per-item direction

README.md

@@ -149,8 +149,17 @@ set -g @themux_module_notch           "off"
   accent text) or `naked` (transparent, accent text — pair with
   `@themux_status_background "none"`). A naked block keeps the shape's caps as an
   outline, so `rounded` leading + `naked` text reads as a capsule.
-- **notch** — `on` makes the leading↔text seam inherit the shape's cap instead
-  of a flat edge.
+- **notch** — the leading↔text seam. `off` (default) is flat; `>` bakes the
+  shape's cap with leading's colour tapering into text; `<` mirrors it,
+  colours reversed (with the `squared` shape both draw the same full-block
+  glyph — only the colour placement differs); `auto` (`on` is an alias) picks
+  a direction per placement: zone-aware for modules/windows (left zone `>`,
+  right zone `<`, centre off), position-aware for panes (`leading_position
+  left` → `>`, `right` → `<`). A different axis from the connectors below —
+  notch shapes the seam *inside* one item, connectors join *between* items.
+  `auto`/`on` only resolve through the layout grammar; a module consumed
+  directly (your own format, `_prepend`/`_append`) keeps no seam at all —
+  see the [Configuration Reference](./docs/reference/configuration.md) for why.
 
 The text-block **variant** prop is `@themux_<item>_text_variant` for all three
 items; on windows the name *content* lives in `@themux_window_name` (the bare

docs/explanation/design.md

@@ -32,14 +32,18 @@ vocabulary.
 | **shape** | `squared` / `rounded` / `slanted` / `powerline` | Block with square / round / slant / arrow (powerline chevron) caps. |
 | | `unstyled` | themux leaves the item alone so you can build it by hand. |
 | **leading** / **text** | `solid` / `soft` / `subtle` / `naked` | The icon-or-number block and the text block each pick a style: accent block / grey block / grey block with accent text / transparent. |
-| **notch** | `on` / `off` | The leading↔text seam inherits the shape's cap. |
+| **notch** | `off` / `>` / `<` / `auto` (`on` alias) | The leading↔text seam direction; `auto` resolves one per placement. |
 
 The props are orthogonal: each item's `shape`, `leading`, `text` and `notch`
 are chosen independently, and any combination is valid — a colored chip with a
 transparent label, a rounded outline capsule, a plain grey pill. A common
 renderer resolves the two block styles, so a new shape is a few cap glyphs, not
 a flag that interacts with every other flag.
 
+One prop bends this locality rule: `notch auto` is the only one whose resolved
+value depends on where the item sits (its status-line zone, or a pane's
+`leading_position`) rather than solely on the item's own options.
+
 `unstyled` is the escape hatch: it makes the law of orthogonality hold even at
 the edges. Anything themux's props do not cover, you build yourself with the
 exposed palette, and themux stays out of the way.

docs/reference/configuration.md

@@ -7,7 +7,7 @@ load, so changing an option and reloading is enough — no `kill-server`.
 
 The three UI items — **status modules**, **windows**, **panes** — are each a
 *component* styled through a few independent props: a **shape**, a
-**leading** style, a **text** style, a **notch** flag, and **padding**.
+**leading** style, a **text** style, a **notch** direction, and **padding**.
 
 ### Anatomy of a component
 
@@ -32,8 +32,8 @@ its text block `subtle` (grey fill, accent text), so the two halves stand apart.
   / `powerline` / `unstyled`).
 - **leading** — the icon block on a module, the number block on a window or pane.
 - **text** — the value on a module, the window or pane name.
-- **notch** — when `on`, the seam between leading and text inherits the shape's
-  cap instead of a flat edge.
+- **notch** — the seam between leading and text: a direction (`>` / `<`), `off`
+  (flat), or the zone-aware `auto` default. See below.
 - **padding** — the spacing inside each block.
 
 ---
@@ -62,7 +62,7 @@ set -g @themux_module_notch           "off"
 | `@themux_<item>_shape` | `squared` · `rounded` · `slanted` · `powerline` · `unstyled` | `squared` |
 | `@themux_<item>_leading_variant` | `solid` · `soft` · `subtle` · `naked` | `solid` |
 | `@themux_<item>_text_variant` † | `solid` · `soft` · `subtle` · `naked` | `soft` |
-| `@themux_<item>_notch` | `on` · `off` | `off` |
+| `@themux_<item>_notch` | `off` · `>` · `<` · `auto` · `on` (alias of `auto`) | `off` |
 | `@themux_<item>_leading_position` | `left` · `right` | `left` |
 | `@themux_<item>_padding` | `"N"` or `"<LL> [LR]\|<TL> [TR]"` cells (see below) | `1` |
 | `@themux_<item>_leading_active_variant` | `solid` · `soft` · `subtle` · `naked` | resting variant |
@@ -129,9 +129,51 @@ A `naked` block keeps the shape's caps as an outline, so a `rounded` leading +
 `naked` text reads as a capsule. Pair naked styles with
 `@themux_status_background "none"` for a fully bare bar.
 
-**notch** — `on` makes the leading↔text seam inherit the shape's cap (the
-leading color tapering into the text background) instead of a flat boundary;
-it collapses to nothing when the two blocks share a background.
+**notch** — the seam between the leading and text blocks. `off` (default) keeps
+a flat boundary (a module falls back to `@themux_module_middle_separator`
+there); `>` bakes the shape's cap with the leading (visually first) block's
+colour tapering into the second; `<` mirrors it, the second block's colour
+tapering back into the first, cap and colours reversed. Either direction
+collapses to nothing when the two blocks share one background — no phantom
+cell. With the `squared` shape both directions draw the same full-block glyph
+(there is no taper to mirror), so `>` vs `<` differ only in which side the
+colour lands on, not in the glyph itself.
+
+`auto` (`on` is an alias) resolves a direction per placement instead of a fixed
+one:
+
+| Item | Resolves by | first / left | last / right | centre |
+| --- | --- | --- | --- | --- |
+| module, window | status-line zone | `>` | `<` | `off` |
+| pane | `@themux_<item>_leading_position` | `>` (`left`) | `<` (`right`) | — |
+
+A module referenced in more than one zone gets one seam per zone — each
+occurrence resolves independently. The window list is the one exception:
+`window-status-format` is a single shared tmux option, so if the `windows`
+token appears in more than one zone (or row), the last one themux processes
+wins for all of them.
+
+This is a different axis from the module [connectors](#status-layout) (`>` /
+`<` between adjacent items in a zone): notch shapes the seam *inside* one
+item, between its own leading and text blocks; connectors join *between*
+items. They share glyphs by design — the same taper reads the same way either
+side of the axis — but are configured and resolved independently.
+
+`auto`/`on` only resolve when a module is read through the layout grammar (a
+token in `@themux_status_line_N`, or a pane's `leading_position`) — that is
+what tells themux which zone/side this occurrence sits in. If you consume
+`@themux_module_<name>` directly instead — your own tmux formats, or a
+`_prepend`/`_append` value — there is no zone to resolve against, so the
+internal placeholder byte themux uses to defer that choice is never replaced.
+tmux's status-line renderer silently drops that byte at draw time (it has no
+visible glyph), so the leading and text blocks simply abut with no seam, as if
+notch were `off`. Pin an explicit `>` or `<` on any module you consume
+directly this way.
+
+> **Breaking**: the old `on` always drew the `>` seam. As an alias of `auto`
+> it can now draw `>`, `<`, or nothing depending on where the item sits — pin
+> `>` explicitly (`@themux_<item>_notch ">"`) if you relied on the old fixed
+> direction.
 
 For windows and panes, each part has a resting and an active accent: the resting
 one (`@themux_window_leading_color`, `@themux_pane_leading_color`, and the

run_tests.sh

@@ -19,3 +19,4 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd -P)
 "${script_dir}"/tests/harness.sh --test "${script_dir}"/tests/panes_variant.sh --expected "${script_dir}"/tests/panes_variant_expected.txt "$@"
 "${script_dir}"/tests/harness.sh --test "${script_dir}"/tests/ram_module.sh --expected "${script_dir}"/tests/ram_module_expected.txt "$@"
 "${script_dir}"/tests/harness.sh --test "${script_dir}"/tests/module_variant.sh --expected "${script_dir}"/tests/module_variant_expected.txt "$@"
+"${script_dir}"/tests/harness.sh --test "${script_dir}"/tests/notch_direction.sh --expected "${script_dir}"/tests/notch_direction_expected.txt "$@"

tests/application_module.sh

@@ -15,9 +15,11 @@ print_option @themux_module_application | grep -q "@thm_" &&
 print_option @themux_module_application | sed -E 's/(bash|fish|zsh)/<application>/'
 
 # Notch: the icon<->text seam takes the shape's right cap instead of the plain
-# middle separator (the module color tapering into the text background).
+# middle separator (the module color tapering into the text background). ">" is
+# explicit (not zone-aware), so it bakes directly here without utils/layout.sh
+# splicing in the seam — "auto"/"on" cannot resolve outside a real status line.
 tmux set -g @themux_module_shape "rounded"
-tmux set -g @themux_module_notch "on"
+tmux set -g @themux_module_notch ">"
 tmux source "${script_dir}/../themux_options.conf"
 tmux source "${script_dir}/../themux.conf"
 print_option @themux_module_application | sed -E 's/(bash|fish|zsh)/<application>/'

tests/module_variant.sh

@@ -92,9 +92,11 @@ printf "\nposition_swaps_edges "
 { [ "$ll" = "$rr" ] && [ "$lr" = "$rl" ] && [ "$ll" != "$lr" ]; } && printf "Y" || printf "n"
 
 # notch=off lets the icon and text blocks abut (compact, catppuccin-style — no seam
-# cell). notch=on draws the shape's tapered cap as the seam between them, so the
-# notched module is wider. The metric's solid icon over its subtle text differs in
-# bg like any module, so the seam is drawn there too.
+# cell). notch=on (an alias of auto) leaves a one-byte NOTCH_MARK control-byte
+# placeholder in this RAW core instead of a baked glyph — utils/layout.sh splices
+# the real per-zone seam in later — so this length assertion only measures
+# marker-vs-empty, not the rendered glyph's width. Real glyph coverage (colour,
+# direction, zone resolution) lives in tests/notch_direction.sh.
 tmux set -gu @themux_module_leading_position
 tmux set -g @themux_status_line_1 "host cpu"
 tmux set -g @themux_all_shape "rounded"