herdr-gentle-shell 1.8.1 → 1.9.1
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 +93 -10
- package/README.md +53 -11
- package/docs/theme-sync.md +65 -15
- package/extensions/gentle-herdr-state.ts +300 -19
- package/extensions/herdr-theme-sync.ts +4 -0
- package/lib/customize-panel.js +46 -17
- package/lib/customize-rows.js +393 -0
- package/package.json +1 -1
package/DESIGN.md
CHANGED
|
@@ -1008,6 +1008,45 @@ nothing:
|
|
|
1008
1008
|
settings entry actually changed, because that entry is the only part that
|
|
1009
1009
|
waits for the next Pi extension load.
|
|
1010
1010
|
|
|
1011
|
+
The command always exists and the page is additive.
|
|
1012
|
+
`/herdr-gentle:customize` is registered in the extension factory, unconditionally
|
|
1013
|
+
and before the pane gate, exactly as it always was; when gentle-shell-bridge
|
|
1014
|
+
answers its handshake — the `gentle-shell-bridge/api/v1` object published on
|
|
1015
|
+
`globalThis`, gated exactly like the bridge's own `isBridgeApi` — the extension
|
|
1016
|
+
ALSO registers one row provider (`registerRows`, a row `category`, never
|
|
1017
|
+
`registerSection`) on the `Herdr` page of Gentle Shell's own `/gentle:customize`
|
|
1018
|
+
menu, holding exactly the four options S1 names: `Herd agents`, `Moshi`,
|
|
1019
|
+
`Theme sync`, `Select theme`. Two surfaces coexisting is by design: Pi gives an
|
|
1020
|
+
extension no way to withdraw a registered command, and a bridge with no host
|
|
1021
|
+
menu must never leave the user with none. The page is asked for at
|
|
1022
|
+
`session_start` and again on the bridge's `gentle-shell-bridge:ready` announce,
|
|
1023
|
+
so a bridge that publishes after this extension or after the session start still
|
|
1024
|
+
produces it; the live provider is its own guard, so a second `session_start` or a
|
|
1025
|
+
repeated announce never stacks a second page, and only the provider is disposed
|
|
1026
|
+
at `session_shutdown` while the command stays as registered.
|
|
1027
|
+
|
|
1028
|
+
Each row is that switch and nothing else: its action calls the same
|
|
1029
|
+
`applyCustomizePanel` the panel calls, so the writes, the `moshi-hook`
|
|
1030
|
+
prerequisite gate and the "a refusal writes nothing" promise are identical by
|
|
1031
|
+
construction, and the model is re-read on every menu build so `current()` is the
|
|
1032
|
+
stored value rather than a copy taken at registration. The page's four lines are
|
|
1033
|
+
the same four switches under their row names — `Herd agents` for
|
|
1034
|
+
`Sidebar agent rows`, `Moshi` for `Moshi notifications`, `Theme sync` and
|
|
1035
|
+
`Select theme` for the two `Herdr Theme` settings — one row per value, applied
|
|
1036
|
+
with `Enter` (the bridge stages `applyOnMove: false` on every row it
|
|
1037
|
+
contributes), with the theme rows hidden while the sync is on instead of
|
|
1038
|
+
refused in place. One accepted limitation: a row action receives only the
|
|
1039
|
+
inline helpers (`input`, `confirm`, `capture`), so it has no reload handle —
|
|
1040
|
+
the Moshi toggle still writes the settings exclusion and then asks for a
|
|
1041
|
+
restart (`Restart Pi so the new Moshi hook exclusion takes effect.`) where the
|
|
1042
|
+
command and the panel reload immediately (`Reloading now to apply the change.`).
|
|
1043
|
+
Every string that sends the user back to these switches names
|
|
1044
|
+
`/herdr-gentle:customize`, byte-identical to the pre-page build: the command
|
|
1045
|
+
always exists, so no message needs a surface-dependent wording — the Moshi gate
|
|
1046
|
+
refusals end `… re-apply On from /herdr-gentle:customize.` and the follower's
|
|
1047
|
+
missing-theme notice says `… pick an installed theme in
|
|
1048
|
+
/herdr-gentle:customize.`
|
|
1049
|
+
|
|
1011
1050
|
`/herdr-gentle:customize status` prints one read-only line; an unknown
|
|
1012
1051
|
argument, Esc, or a cancelled menu writes nothing. With no argument the
|
|
1013
1052
|
command opens the floating panel (`lib/customize-panel.js`, painted through its
|
|
@@ -1162,10 +1201,12 @@ exactly one mechanism writes each piece of state.
|
|
|
1162
1201
|
`worktree_close` / `worktree_session_open` / `worktree_warp`), the warp
|
|
1163
1202
|
panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
|
|
1164
1203
|
ship. This package publishes the Herdr producer sidecar and the Moshi channel
|
|
1165
|
-
only; `bin/gentle-sidebar.js` is its one CLI and
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1204
|
+
only; `bin/gentle-sidebar.js` is its one CLI and the customize switches are
|
|
1205
|
+
reached two ways, additively: `/herdr-gentle:customize`, always, and — when
|
|
1206
|
+
gentle-shell-bridge answers its handshake — the `Herdr` page of Gentle Shell's
|
|
1207
|
+
own `/gentle:customize` menu as well (§7). The former
|
|
1208
|
+
in-process provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
|
|
1209
|
+
stays removed.
|
|
1169
1210
|
- Rollback: disable this plugin → producer stops writing; consumer sweeps
|
|
1170
1211
|
only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
|
|
1171
1212
|
`↳N` behavior with zero data migration.
|
|
@@ -1257,8 +1298,10 @@ list, not silent.
|
|
|
1257
1298
|
## 12. Theme sync (Pi palette → Herdr theme)
|
|
1258
1299
|
|
|
1259
1300
|
Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
|
|
1260
|
-
pinned while the sync is off (S1–S7). The switch lives with the other two
|
|
1261
|
-
`/herdr-gentle:customize
|
|
1301
|
+
pinned while the sync is off (S1–S7). The switch lives with the other two on
|
|
1302
|
+
`/herdr-gentle:customize` and, beside it, on the `Herdr` page of Gentle Shell's
|
|
1303
|
+
own customize menu whenever the bridge answers the handshake (§7), where it is
|
|
1304
|
+
the `Theme sync` and `Select theme` rows; the user-facing reference is
|
|
1262
1305
|
[docs/theme-sync.md](docs/theme-sync.md). Six modules with one owner — this Pi
|
|
1263
1306
|
package — and one direction of data:
|
|
1264
1307
|
|
|
@@ -1482,7 +1525,8 @@ socket/config path). The follower reports `not-herdr`, `remote` and
|
|
|
1482
1525
|
`unsupported` as one `info` notice per session and asks again only when the
|
|
1483
1526
|
palette itself changes.
|
|
1484
1527
|
|
|
1485
|
-
**The panel.** `/herdr-gentle:customize`
|
|
1528
|
+
**The panel.** `/herdr-gentle:customize` — the surface that always exists (§7) —
|
|
1529
|
+
reuses Gentle Shell's own card shape:
|
|
1486
1530
|
one left `CATEGORIES` list, one right pane headed `<Category> · n/m`, one line
|
|
1487
1531
|
per setting with its options inline (`●` stored, `›` cursor elsewhere, `○` the
|
|
1488
1532
|
rest). The arrows move the option cursor and only Enter applies; Enter keeps the
|
|
@@ -1494,16 +1538,55 @@ painted with the host theme, where a theme option shows that theme's own palette
|
|
|
1494
1538
|
through the raw SGR the host hands back. Three footer legends (categories,
|
|
1495
1539
|
option row, panes) are chosen by what the keys do right now and compact instead
|
|
1496
1540
|
of wrapping. The theme list comes from `ctx.ui.getAllThemes()` in the host's own
|
|
1497
|
-
order with `None` first, the `Gentle Shell theme` setting is
|
|
1498
|
-
|
|
1499
|
-
|
|
1541
|
+
order with `None` first, the `Gentle Shell theme` setting is absent — never
|
|
1542
|
+
dim, never a refusal line — while the sync is on, and it returns on the same
|
|
1543
|
+
mounted card the moment the sync is turned off; a theme attempt that still
|
|
1544
|
+
arrives (the plain fallback menu, the apply path) writes nothing and is refused
|
|
1545
|
+
with `Turn Theme sync off to pick a specific theme.`. A host that exposes no
|
|
1546
|
+
list shows one note instead of an empty picker.
|
|
1500
1547
|
The panel writes nothing itself: it calls the extension's apply path, swaps in
|
|
1501
1548
|
the model that path re-read, and keeps the cursor by structural option ids.
|
|
1502
1549
|
|
|
1550
|
+
**The page.** The `Herdr` page of Gentle Shell's own customize menu (§7) is not
|
|
1551
|
+
this card: Gentle Shell paints its own rows and enters their actions. The
|
|
1552
|
+
switch side is the same — two rows, `Theme sync` and `Select theme`, built from
|
|
1553
|
+
the same model by `lib/customize-rows.js`, applied through the same
|
|
1554
|
+
`applyCustomizePanel` — so the notices above are the same strings, a theme row
|
|
1555
|
+
keeps its swatch, and the theme rows are hidden while the sync is on rather
|
|
1556
|
+
than refused in place. The sync never needs a Pi reload on either surface; the
|
|
1557
|
+
one surface-specific difference in this feature is Moshi's, which asks for a
|
|
1558
|
+
restart on the page because a row action has no reload handle (§7).
|
|
1559
|
+
|
|
1560
|
+
The page's row set is FIXED for the life of the menu, and the cache in
|
|
1561
|
+
`lib/customize-rows.js` is what makes that affordable: one model read per paint
|
|
1562
|
+
burst (one synchronous `configure.js --check`, not one per callback), dropped
|
|
1563
|
+
after an `apply` settles and after a one-second TTL. Two properties follow and
|
|
1564
|
+
are accepted rather than promised away. First, an external write while the menu
|
|
1565
|
+
is idle becomes visible on the first read after the cache expires, or on a
|
|
1566
|
+
rebuild: the cache never asks the host to repaint, so a repaint that lands
|
|
1567
|
+
before expiry redraws the previous model and the displayed state has no upper
|
|
1568
|
+
freshness bound. Second, when an external write hides the row the user had
|
|
1569
|
+
focused (the theme
|
|
1570
|
+
picker, with the sync turned on elsewhere), the host clamps the focus to the
|
|
1571
|
+
neighbouring row, so Enter can act on that one; the clamp itself writes nothing.
|
|
1572
|
+
The fixed row set is also why a theme applied from a row is checked against a
|
|
1573
|
+
fresh `ctx.ui.getAllThemes()` read at apply time: a theme removed after the
|
|
1574
|
+
build refuses and writes nothing instead of pinning a name this install no
|
|
1575
|
+
longer has. That check lives on the page's own apply path, so the command's
|
|
1576
|
+
picker and the mounted panel keep the `865d360` write (S2).
|
|
1577
|
+
|
|
1503
1578
|
**Limits** (the §10 style, none of them a promise this design makes):
|
|
1504
1579
|
|
|
1505
1580
|
- The 500 ms tick is the whole observation granularity — there is no event to
|
|
1506
1581
|
subscribe to, so a theme change is noticed within one tick and not sooner.
|
|
1582
|
+
- The page's displayed state has **no upper freshness bound**: its row cache
|
|
1583
|
+
never requests a repaint, so a write from another process while the menu is
|
|
1584
|
+
idle appears on the first read after the cache expires, or on a rebuild, not
|
|
1585
|
+
when it lands; a repaint that lands before expiry redraws the previous model,
|
|
1586
|
+
and on a menu nobody touches the write is not shown at all.
|
|
1587
|
+
- The page cannot keep the cursor on a row an external write hid: the host clamps
|
|
1588
|
+
the focus to the neighbouring row, so the next Enter can act on that neighbour.
|
|
1589
|
+
The clamp writes nothing; it only moves the cursor.
|
|
1507
1590
|
- The automated evidence is a stubbed Pi host plus a real binary stand-in on
|
|
1508
1591
|
disk; **no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
|
|
1509
1592
|
`getAllThemes`, `notify` and the host component contract are used as
|
package/README.md
CHANGED
|
@@ -484,9 +484,34 @@ 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
517
|
and one right pane headed `<Category> · n/m`, where each setting is ONE line
|
|
@@ -528,7 +553,16 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
528
553
|
below and adds or removes the `-extensions/moshi-hooks.ts` exclusion in Pi's
|
|
529
554
|
`settings.json`, running the `moshi-hook` pairing gate before enabling (a
|
|
530
555
|
refusal writes nothing) and reloading Pi only when that settings entry
|
|
531
|
-
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
|
|
532
566
|
(`customize status: sidebar=<on|off|unknown> moshi=<on|off>
|
|
533
567
|
theme-sync=<on|off|unknown> theme=<name|none|unknown>`); an unknown
|
|
534
568
|
argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
|
|
@@ -546,8 +580,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
546
580
|
mkdir -p "$dir" && echo '{"enabled":true}' > "$dir/gentle-moshi.json"
|
|
547
581
|
```
|
|
548
582
|
|
|
549
|
-
|
|
550
|
-
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
|
|
551
585
|
requires the `moshi-hook` CLI on `PATH` with `moshi-hook status --json`
|
|
552
586
|
reporting `paired: true` (an unpaired host is refused and nothing is
|
|
553
587
|
written).
|
|
@@ -597,19 +631,27 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
597
631
|
row), while every other Herdr failure still aborts and opens nothing. The
|
|
598
632
|
other worktree tools and the ODD and issues panels live
|
|
599
633
|
in `odd-worktree` now; the sidebar and Moshi switches stayed here and are
|
|
600
|
-
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
|
|
601
636
|
[docs/herdr-session-open.md](docs/herdr-session-open.md).
|
|
602
637
|
|
|
603
638
|
### Theme sync (Herdr palette follows Pi)
|
|
604
639
|
|
|
605
|
-
|
|
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.
|
|
606
644
|
`Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
|
|
607
645
|
palette of the theme Pi is showing, and it follows a theme change while Pi keeps
|
|
608
646
|
running. While it is off, `Gentle Shell theme` pins one Gentle Shell / Pi theme
|
|
609
647
|
from Pi's own inline list (`None` first, then the host's order) and `None`
|
|
610
|
-
clears the pin
|
|
611
|
-
|
|
612
|
-
|
|
648
|
+
clears the pin. While the sync is on, `Gentle Shell theme` is not offered at
|
|
649
|
+
all: it is absent from the panel and from the page alike, and it comes back on
|
|
650
|
+
the surface you already have the moment the sync is turned off. A theme attempt
|
|
651
|
+
that still arrives (the plain fallback menu, the apply path) writes nothing and
|
|
652
|
+
is refused with `Turn Theme sync off to pick a specific theme.`. Turning the
|
|
653
|
+
sync off writes nothing to Herdr, so **Herdr keeps the last applied palette** — a
|
|
654
|
+
fresh install
|
|
613
655
|
whose sync is off and whose theme is unassigned writes nothing at all. State is
|
|
614
656
|
one file, `gentle-theme.json`, beside `gentle-moshi.json`.
|
|
615
657
|
|
package/docs/theme-sync.md
CHANGED
|
@@ -18,8 +18,14 @@ plugin-side planner and no 1.8.0 managed block.
|
|
|
18
18
|
|
|
19
19
|
## The switch
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
21
|
+
The whole feature is two settings: `Theme sync` and `Select theme`. They are
|
|
22
|
+
served on `/herdr-gentle:customize` → `Herdr Theme` always, and — when
|
|
23
|
+
gentle-shell-bridge answers its handshake (its `gentle-shell-bridge/api/v1`
|
|
24
|
+
object is published on `globalThis`) — also on the `Herdr` page of Gentle Shell's
|
|
25
|
+
own `/gentle:customize` menu, laid out like the rest of the card (see
|
|
26
|
+
[Panel](#panel)). The command always exists and the page is additive; the page's
|
|
27
|
+
rows come from the same model and the same apply path, so everything below holds
|
|
28
|
+
on both:
|
|
23
29
|
|
|
24
30
|
- `Theme sync` is **OFF by default**. `On` makes Herdr's palette the palette of
|
|
25
31
|
the theme Pi is showing, and it follows a change of the active theme while Pi
|
|
@@ -28,8 +34,11 @@ rest of the card (see [Panel](#panel)):
|
|
|
28
34
|
applied palette survives Pi closing.
|
|
29
35
|
- `Gentle Shell theme` assigns one Gentle Shell / Pi theme by name from Pi's own
|
|
30
36
|
list (`None` first, then the host's order). While the stored sync is on the
|
|
31
|
-
setting is
|
|
32
|
-
|
|
37
|
+
setting is not offered at all: it is absent from the panel and from the
|
|
38
|
+
`Herdr` page alike, never painted dim and never a refusal line, and it comes
|
|
39
|
+
back on the surface you already have the moment the sync is turned off. A
|
|
40
|
+
theme attempt that still arrives — the plain fallback menu or the apply path —
|
|
41
|
+
writes nothing and is refused with
|
|
33
42
|
`Turn Theme sync off to pick a specific theme.` Choosing `None` clears the pin
|
|
34
43
|
(`theme: null`); choosing a name stores it. The stored pin is carried across a
|
|
35
44
|
sync toggle untouched, so turning the sync off restores that choice instead of
|
|
@@ -45,14 +54,16 @@ The notices are fixed strings:
|
|
|
45
54
|
| Sync turned on | `Theme sync on; Herdr's palette follows the theme active in Pi.` |
|
|
46
55
|
| Sync turned off | `Theme sync off; Herdr keeps the palette it was last given.` |
|
|
47
56
|
| Toggle already in that state | `Theme sync already on/off; nothing was changed.` |
|
|
48
|
-
| Theme
|
|
57
|
+
| Theme attempt while the sync is on (fallback menu, apply path) | `Turn Theme sync off to pick a specific theme.` |
|
|
49
58
|
| Theme assigned | `Gentle Shell theme set to <name>.` |
|
|
50
|
-
| Pin cleared | `Gentle Shell theme set to Off; Herdr keeps the palette it was last given.` (the stored value stays `null` and the inline list marks `None`; only this notice — and the
|
|
59
|
+
| Pin cleared | `Gentle Shell theme set to Off; Herdr keeps the palette it was last given.` (the stored value stays `null` and the inline list marks `None`; only this notice — and the `Off (no theme assigned)` entry of the fallback menu and of the Gentle Shell page — spell it `Off`) |
|
|
51
60
|
| Host exposes no theme list | `Could not read Pi's theme list (this host exposes no getAllThemes()); nothing was changed.` |
|
|
52
61
|
| Theme store missing | `Could not reach the theme store (lib/theme-store.js is unavailable); nothing was changed.` |
|
|
53
62
|
| State file not writable | `Could not write the theme store: <detail>; nothing was changed.` |
|
|
54
63
|
|
|
55
|
-
`/herdr-gentle:customize status` prints one read-only line and writes nothing
|
|
64
|
+
`/herdr-gentle:customize status` prints one read-only line and writes nothing.
|
|
65
|
+
The subcommand belongs to the command; the menu page offers no `status`
|
|
66
|
+
operation:
|
|
56
67
|
|
|
57
68
|
```text
|
|
58
69
|
customize status: sidebar=<on|off|unknown> moshi=<on|off> theme-sync=<on|off|unknown> theme=<name|none|unknown>
|
|
@@ -85,7 +96,9 @@ then rename), preserve an existing file's mode and create a new one as `0600`.
|
|
|
85
96
|
setting marks no option and carries `state unknown; Enter turns the sync on`,
|
|
86
97
|
the theme list marks nothing, and the follower does nothing. It is
|
|
87
98
|
written over only when you act — toggling the sync writes a fresh document,
|
|
88
|
-
and the theme setting is
|
|
99
|
+
and the theme setting is withheld only by a *stored* `sync: true` (the write
|
|
100
|
+
still refuses such an attempt, with
|
|
101
|
+
`Turn Theme sync off to pick a specific theme.`).
|
|
89
102
|
- **`sync: false` with `theme: null`** is the default install: the follower
|
|
90
103
|
asks for no palette at all, so nothing is written, nothing is reloaded and
|
|
91
104
|
nothing is removed (S7).
|
|
@@ -543,7 +556,12 @@ no-op, and every user-visible outcome is a fixed string:
|
|
|
543
556
|
- **Pinned theme not installed**: `The Pi theme "<name>" is not installed, so
|
|
544
557
|
Herdr's palette was left unchanged; pick an installed theme in
|
|
545
558
|
/herdr-gentle:customize.` — once per session; a later install of that exact
|
|
546
|
-
theme is picked up without a restart.
|
|
559
|
+
theme is picked up without a restart. The notice names the command, which
|
|
560
|
+
always exists, byte-identical to the pre-page build. The customize surfaces
|
|
561
|
+
reuse the same sentence when a theme row outlives the catalogue it was built
|
|
562
|
+
from: applying a theme re-reads `ctx.ui.getAllThemes()` first, and a name that
|
|
563
|
+
is gone refuses as a `warning` write-nothing instead of pinning a theme this
|
|
564
|
+
install no longer has.
|
|
547
565
|
- **Nothing to project**: `Herdr theme not applied: <theme name> has no concrete
|
|
548
566
|
colours to project.` (`the active theme` replaces the name when the active
|
|
549
567
|
theme exposes none) — once per session, `warning`. A palette with no concrete
|
|
@@ -690,10 +708,12 @@ Tests and isolated runs:
|
|
|
690
708
|
|
|
691
709
|
## Panel
|
|
692
710
|
|
|
693
|
-
`/herdr-gentle:customize` with no argument opens the card
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
711
|
+
`/herdr-gentle:customize` with no argument opens the card — the surface that
|
|
712
|
+
always exists, whether or not the bridge adds its page. It behaves like Gentle
|
|
713
|
+
Shell's own: one left `CATEGORIES` list and one
|
|
714
|
+
right pane headed `<Category> · n/m`, with one line per setting and its options
|
|
715
|
+
inline — `●` the stored option, `›` the cursor while it sits elsewhere, `○`
|
|
716
|
+
the rest.
|
|
697
717
|
|
|
698
718
|
- The arrows move the option cursor and **only Enter applies**; Enter keeps the
|
|
699
719
|
card open (only a Moshi settings change that needs a Pi reload closes it),
|
|
@@ -722,7 +742,36 @@ Gentle Shell's own: one left `CATEGORIES` list and one right pane headed
|
|
|
722
742
|
- The theme list is read automatically from the host (`ctx.ui.getAllThemes()`)
|
|
723
743
|
in the host's own order, `None` first; a host that exposes no list shows one
|
|
724
744
|
note (`Themes unavailable; use Pi /settings`) instead of an empty picker, and
|
|
725
|
-
an unreadable store adds `state unknown; Enter pins a theme`.
|
|
745
|
+
an unreadable store adds `state unknown; Enter pins a theme`. While the stored
|
|
746
|
+
sync is on the setting is not offered at all: the card reads
|
|
747
|
+
`Herdr Theme · 1/1`, with no dim line and no note, and the picker is back on
|
|
748
|
+
the same mounted card as soon as the sync is turned off.
|
|
749
|
+
|
|
750
|
+
When gentle-shell-bridge answers, this card is still there and the same two
|
|
751
|
+
settings are ALSO the `Theme sync` and `Select theme` rows of the `Herdr` page in
|
|
752
|
+
Gentle Shell's own menu, painted by that host. One row per value, walked with
|
|
753
|
+
the arrows and applied with `Enter` (the bridge never applies on a cursor move),
|
|
754
|
+
the theme row keeps its own swatch, and the theme rows are simply not shown
|
|
755
|
+
while the sync is on instead of being refused in place — the panel withholds the
|
|
756
|
+
same setting the same way. The notices are the same fixed strings, and the sync
|
|
757
|
+
needs no Pi reload on either surface.
|
|
758
|
+
|
|
759
|
+
The page's rows are FIXED for as long as the menu is open, which is why its
|
|
760
|
+
theme rows cost one model read per paint burst instead of one per row. Two
|
|
761
|
+
consequences are accepted: an external write while the menu is idle becomes
|
|
762
|
+
visible on the first read after the cache expires, or on a rebuild (the cache
|
|
763
|
+
never asks the host to repaint, so a repaint that lands before expiry redraws
|
|
764
|
+
the previous model and the display has no upper freshness bound), and an
|
|
765
|
+
external write that hides the focused row leaves the host to clamp the cursor to
|
|
766
|
+
the neighbouring row, so `Enter` can act on that one — the clamp itself writes
|
|
767
|
+
nothing. Because a row can outlive the catalogue it was built from, the page's
|
|
768
|
+
own apply path re-reads `ctx.ui.getAllThemes()` before it writes: a theme
|
|
769
|
+
removed after the build is refused with the sync's own not-installed notice
|
|
770
|
+
(`The Pi theme "<name>" is not installed, …`) and the store is left untouched,
|
|
771
|
+
and a catalogue that cannot be read at apply time is refused with
|
|
772
|
+
`Could not read Pi's theme list at apply time; nothing was changed.` The
|
|
773
|
+
command's own picker and the mounted panel do not run that check, so both keep
|
|
774
|
+
the `865d360` behavior byte for byte (S2).
|
|
726
775
|
|
|
727
776
|
## Implementation
|
|
728
777
|
|
|
@@ -733,5 +782,6 @@ Gentle Shell's own: one left `CATEGORIES` list and one right pane headed
|
|
|
733
782
|
| `lib/herdr-theme-config.js` | The pure planner — a **line splicer**, not a TOML validator: table-boundary scanning, opaque bytes outside the two theme tables, a strict theme-table grammar, the whole-line `was` marker with byte-exact restoration (the user's latest trailing comment wins), the one regenerated block (`begin` / `begin created` … `end` / `end after a missing line ending`), the ambiguity refusal above a block being removed or moved, the 1.8.0 marker-pair migration, the BOM and the enforced splice invariant. |
|
|
734
783
|
| `lib/herdr-theme-apply.js` | The writer: availability guards, bounded snapshot, compare-and-swap, atomic non-overwriting backup (a regular existing file is accepted as is), retried temp cleanup that reports a survivor and never deletes a temp it did not create, growth limit, `forceReload`, reload. |
|
|
735
784
|
| `extensions/herdr-theme-sync.ts` | The follower: session-start evaluation, 500 ms tick, fingerprint, owed-reload repair, the notices. |
|
|
736
|
-
| `extensions/gentle-herdr-state.ts` | The switch: `applyThemeSync`, `writeThemeChoice`, `applyCustomizePanel`, `customize status
|
|
785
|
+
| `extensions/gentle-herdr-state.ts` | The switch: `applyThemeSync`, `writeThemeChoice`, `applyCustomizePanel`, `customize status`, and the page registration beside the always-registered command (`registerCustomizePage`). |
|
|
737
786
|
| `lib/customize-panel.js` | The card: categories, option lines, sideways window, Preview block, legends, pointer hits. |
|
|
787
|
+
| `lib/customize-rows.js` | The page: the same model and settings translated into the four `Herdr` row lines Gentle Shell renders. |
|