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/DESIGN.md +384 -101
- package/README.md +128 -30
- package/docs/theme-sync.md +676 -182
- package/extensions/gentle-herdr-state.ts +413 -55
- package/extensions/herdr-theme-sync.ts +188 -159
- package/lib/customize-panel.js +602 -308
- package/lib/customize-rows.js +366 -0
- package/lib/herdr-theme-apply.js +361 -0
- package/lib/herdr-theme-config.js +1133 -0
- package/lib/theme-projection.js +48 -9
- package/package.json +1 -1
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`
|
|
488
|
-
|
|
489
|
-
|
|
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
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
the
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
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
|
|
507
|
-
`Gentle Shell theme`
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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`
|
|
602
|
-
|
|
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
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
the
|
|
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
|
|