herdr-gentle-shell 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -484,27 +484,59 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
484
484
  managed Herdr rows and records the owned native-extension exclusion;
485
485
  `disable` removes only our owned rows and exclusion, never a user table.
486
486
  See [docs/sidebar-control.md](docs/sidebar-control.md).
487
- - In-Pi switches (`/herdr-gentle:customize`): three switches, all local
488
- state and all reachable from a plain Pi session outside a Herdr pane. With
489
- no argument the command opens the floating panel in Gentle Shell's own
487
+ - In-Pi switches (`/herdr-gentle:customize`, plus the `Herdr` page of Gentle
488
+ Shell's customize menu when gentle-shell-bridge answers): three switches, all
489
+ local state and all reachable from a plain Pi session outside a Herdr pane.
490
+ The command is registered in the extension factory and always exists; the page
491
+ is ADDITIVE. The second surface is a handshake, never a package dependency:
492
+ when gentle-shell-bridge answers — its `gentle-shell-bridge/api/v1` object is
493
+ published on `globalThis` — the extension also contributes one `Herdr` page to
494
+ Gentle Shell's own `/gentle:customize` menu with exactly the four options
495
+ `Herd agents`, `Moshi`, `Theme sync` and `Select theme`, and contributes no
496
+ page when nothing answers. The page is asked for at session start and again on
497
+ the bridge's announce (`gentle-shell-bridge:ready`), so a bridge that loads
498
+ late still produces it; the live provider is its own guard, so a second
499
+ session start or a repeated announce never stacks a second page, and only the
500
+ page is dropped on session shutdown (`/reload` replaces it) while the command
501
+ stays registered. Two surfaces coexisting is by design — no user can end up
502
+ with none — and a bridge that answers yet refuses the page (no
503
+ `lib/customize-rows.js`, a provider its bus rejects) simply leaves the command
504
+ working. Each row is that same switch through the
505
+ same apply path — `Herd agents` drives `bin/configure.js` exactly as
506
+ `Sidebar agent rows` does, `Moshi` writes the flag and the settings exclusion
507
+ exactly as `Moshi notifications` does, and `Theme sync` and `Select theme`
508
+ are the two `Herdr Theme` settings — so the writes and the "a refusal writes
509
+ nothing" promise are identical on both surfaces. On the page a setting is one
510
+ line of `On`/`Off` (or theme) values that the arrows walk and only `Enter`
511
+ applies, a theme row carries its own swatch and is simply not shown while the
512
+ sync is on, and the rows carry no `status`: `status` belongs to the command,
513
+ the surface that exists without the bridge. With
514
+ no argument that command opens the floating panel in Gentle Shell's own
490
515
  layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
491
516
  `Herdr Theme`)
492
- and one right pane headed `<Category> · n/m` with its setting rows, each row
493
- painting the stored value with `●` and the other with `○`; one line above the
494
- footer describes the focused setting (`<setting> — <what it changes>`), and
495
- the footer reads
496
- `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`, while `←/→` or
497
- `Tab` moves between the category and value panes, `↑/↓` or `j/k` moves the
498
- cursor, `Enter` applies the focused row and `Esc` closes without a write. The
499
- legend names only keys: it never advertises `Click`, because every token in
500
- it is a key the panel answers to, and a narrow card compacts it instead of
501
- wrapping. Pointer input still works without being advertised — a click on a
502
- category selects it, a click on a row applies it, and a click outside the
503
- panes is ignored. Each category owns its own rows: `Herdr Sidebar`
517
+ and one right pane headed `<Category> · n/m`, where each setting is ONE line
518
+ with its options inline — `●` the stored option, `›` the cursor while it sits
519
+ elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
520
+ applies; `Enter` keeps the card open (a Moshi change that needs a Pi reload
521
+ closes it first), `Esc` closes without a write, `Tab`
522
+ switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose
523
+ options do not fit scrolls sideways behind muted `‹` / `›` markers with an
524
+ `n/m` counter (falling back to a compact `‹ value ›` when not even one option
525
+ fits), and the Preview block below the panes reads
526
+ `Preview · <option> · <title>` plus a sample painted with the host theme (a
527
+ theme option shows that theme's own palette). The footer carries one of three
528
+ legends after a `Click · ` prefix —
529
+ `↑/↓ categories · → open · Esc close`,
530
+ `←/→ choose · Enter apply · ↑/↓ settings · Tab panes · Esc close`, or
531
+ `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close` — and compacts
532
+ instead of wrapping on a narrow card. A click on an option applies exactly
533
+ that option, a click on a setting's name only moves the focus, a click on a
534
+ category selects it, and a click outside the panes is ignored. Each category
535
+ owns its own rows: `Herdr Sidebar`
504
536
  shows the single `Sidebar agent rows` row, and the only Moshi switch is the
505
537
  `Notifications` row under `Moshi notifications`, while `Herdr Theme` owns
506
- both theme rows (the `Theme sync` toggle and the non-toggle
507
- `Gentle Shell theme` value row described in the subsection below). The
538
+ both theme settings (the `Theme sync` toggle and the inline
539
+ `Gentle Shell theme` list described in the subsection below). The
508
540
  sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
509
541
  reads nor writes `gentle-moshi.json`, so turning the agent rows off never
510
542
  turns the notification channel off. Herdr's own
@@ -521,7 +553,16 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
521
553
  below and adds or removes the `-extensions/moshi-hooks.ts` exclusion in Pi's
522
554
  `settings.json`, running the `moshi-hook` pairing gate before enabling (a
523
555
  refusal writes nothing) and reloading Pi only when that settings entry
524
- actually changed. `/herdr-gentle:customize status` prints one read-only line
556
+ actually changed. On the page that last reload is the one accepted
557
+ limitation: a menu row receives no reload handle, so `Moshi` writes the
558
+ exclusion and asks for a restart (`Restart Pi so the new Moshi hook exclusion
559
+ takes effect.`) where the command and the panel reload immediately
560
+ (`Reloading now to apply the change.`). Every message that points back at
561
+ these switches names `/herdr-gentle:customize`
562
+ (`… re-apply On from /herdr-gentle:customize.`), byte-identical to the
563
+ pre-page build, because the command always exists and no string needs a
564
+ surface-dependent wording. `/herdr-gentle:customize status` prints
565
+ one read-only line
525
566
  (`customize status: sidebar=<on|off|unknown> moshi=<on|off>
526
567
  theme-sync=<on|off|unknown> theme=<name|none|unknown>`); an unknown
527
568
  argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
@@ -539,8 +580,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
539
580
  mkdir -p "$dir" && echo '{"enabled":true}' > "$dir/gentle-moshi.json"
540
581
  ```
541
582
 
542
- `/herdr-gentle:customize` → `Moshi notifications` writes this flag for you,
543
- and enabling there first
583
+ `Moshi notifications` in the command, or `Moshi` on the menu's `Herdr` page,
584
+ writes this flag for you, and enabling there first
544
585
  requires the `moshi-hook` CLI on `PATH` with `moshi-hook status --json`
545
586
  reporting `paired: true` (an unpaired host is refused and nothing is
546
587
  written).
@@ -590,24 +631,81 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
590
631
  row), while every other Herdr failure still aborts and opens nothing. The
591
632
  other worktree tools and the ODD and issues panels live
592
633
  in `odd-worktree` now; the sidebar and Moshi switches stayed here and are
593
- reached through `/herdr-gentle:customize`. See
634
+ reached through `/herdr-gentle:customize` and, when gentle-shell-bridge
635
+ answers, also through the Gentle Shell customize menu's `Herdr` page. See
594
636
  [docs/herdr-session-open.md](docs/herdr-session-open.md).
595
637
 
596
638
  ### Theme sync (Herdr palette follows Pi)
597
639
 
598
- `/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned value.
640
+ `Theme sync` and `Select theme` — the `Herdr Theme` settings of
641
+ `/herdr-gentle:customize`, and the `Theme sync` and `Select theme` rows of the
642
+ Gentle Shell customize menu's `Herdr` page when the bridge answers — are one
643
+ switch and one pinned theme.
599
644
  `Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
600
645
  palette of the theme Pi is showing, and it follows a theme change while Pi keeps
601
- running. While it is off, `Gentle Shell theme` assigns one Gentle Shell / Pi
602
- theme by name and the picker's `Off (no theme assigned)` entry clears the pin; the row is refused while the sync is on
646
+ running. While it is off, `Gentle Shell theme` pins one Gentle Shell / Pi theme
647
+ from Pi's own inline list (`None` first, then the host's order) and `None`
648
+ clears the pin; the setting is painted dim and refused while the sync is on
603
649
  (`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
604
650
  nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
605
651
  whose sync is off and whose theme is unassigned writes nothing at all. State is
606
- one file, `gentle-theme.json`, beside `gentle-moshi.json`; the palette reaches
607
- Herdr through the plugin's own `bin/configure-theme.js`, which owns a marked
608
- `[theme]` block and refuses to touch a `[theme]` table you maintain yourself.
609
- See [docs/theme-sync.md](docs/theme-sync.md) for the projection, the CLI and
610
- the limits.
652
+ one file, `gentle-theme.json`, beside `gentle-moshi.json`.
653
+
654
+ The writer runs **in process in this Pi package**
655
+ (`lib/herdr-theme-config.js` plans it, `lib/herdr-theme-apply.js` writes it,
656
+ `extensions/herdr-theme-sync.ts` follows the theme), so the Herdr plugin is not
657
+ involved and needs no update for this feature. It is a **line splicer, not a TOML
658
+ validator**: it finds the boundaries of your `[theme]` and `[theme.custom]`
659
+ tables (a header only counts at a real line start, never inside a multi-line
660
+ string, array or comment) and treats every line outside them as opaque bytes —
661
+ nothing there is validated or rewritten (escapes included), and an invalid line
662
+ outside those tables is left exactly as it is, because Herdr already refuses such
663
+ a file (the scanner only looks at those lines far enough to find where a table
664
+ starts and ends). A
665
+ splice invariant is enforced before a plan is returned: the non-theme lines of
666
+ the output must be byte-identical to the input's.
667
+
668
+ Inside the two theme tables it edits in place and keeps two kinds of value
669
+ apart: a value you already had is replaced where it stands and remembered by one
670
+ comment recording **the whole original line** (one per key; the first original
671
+ wins, and restoring gives back your quoting, spacing and inline comment — or
672
+ **your current comment** when you edited it after the planner wrote the value,
673
+ because the latest edit wins), while
674
+ a token you did not have is written inside ONE marked block — a `begin`/`end`
675
+ comment pair naming this package, spelled `begin created` when the planner also
676
+ created the table and closed with `end after a missing line ending` when placing
677
+ the block also added the file's missing final newline, so clearing gives that
678
+ byte back — at the
679
+ end of `[theme.custom]`, regenerated on every apply. Leaving a theme therefore
680
+ never leaves a stale colour: a token that leaves the projection is restored from
681
+ its comment byte for byte (or when the projection returns to the recorded value),
682
+ or dropped with the block when the package created it, and a token you own
683
+ without such a comment is never touched. Removing or moving that block is refused
684
+ (`ambiguous herdr-gentle-shell marker above the managed block`) when a
685
+ marker-shaped comment directly above `begin` would end up attached to the key
686
+ under it. Everything else — other tables,
687
+ comments, ordering, a BOM, CRLF or mixed endings, a missing final newline — is
688
+ preserved, a one-time `<config>.herdr-gentle-shell.bak` is published atomically
689
+ before the first modification and never overwritten, and a temp file that
690
+ survives a failed replace is named in the error instead of being hidden, while a
691
+ temp path the writer did not create itself is never deleted (the apply reports
692
+ the `EEXIST` and leaves it alone). What
693
+ fails closed, with the line number and no write, is what a theme-table edit
694
+ cannot be done safely over: `auto_switch` with a value other than `false`,
695
+ `dark_name`, `light_name`, a top-level `theme` key, a dotted key extending the
696
+ theme tables, a duplicated `[theme]`/`[theme.custom]` table or duplicated key
697
+ inside them, a line inside the marked block that is not a token assignment, and a
698
+ value the plan must touch that is not a strict single-line string/boolean/number
699
+ (an unterminated multi-line string or array anywhere also blocks the plan,
700
+ because table boundaries depend on it). While the sync is on (or a theme is
701
+ pinned) the package owns the tokens it projects, so another tool that rewrites
702
+ the same keys (a desktop-theme sync, for example) overwrites them on its next run
703
+ and the next palette change here overwrites them back. There is no "full clear":
704
+ a projection always carries a theme name, so a `name` line the planner inserted
705
+ stays, and only the `[theme.custom]` table it created is removed again. See
706
+ [docs/theme-sync.md](docs/theme-sync.md) for the golden example, the exact
707
+ comment and block lines, what is and is not guaranteed, the refusals, the
708
+ notices and the limits.
611
709
 
612
710
  ## Documentation
613
711
 
@@ -619,7 +717,7 @@ the limits.
619
717
  | Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
620
718
  | Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
621
719
  | Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
622
- | Theme sync (Pi palette → Herdr theme) | [docs/theme-sync.md](docs/theme-sync.md) |
720
+ | Theme sync (Pi palette → Herdr theme, written in process) | [docs/theme-sync.md](docs/theme-sync.md) |
623
721
  | Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
624
722
  | Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
625
723