herdr-gentle-shell 1.7.0 → 1.8.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 CHANGED
@@ -989,10 +989,10 @@ report with a higher seq lands. Parity contract: `working` carries the specific
989
989
 
990
990
  The package ships one CLI switch command,
991
991
  `node bin/gentle-sidebar.js (enable|disable|status|toggle)` (§7), and one in-Pi
992
- command, `/herdr-gentle:customize`, with exactly two switches: the managed
993
- sidebar agent rows and the Moshi notification channel. The command registers
994
- before the `enabled()` pane gate, so both switches stay reachable from a plain
995
- Pi session outside a Herdr pane. It owns no state of its own and reimplements
992
+ command, `/herdr-gentle:customize`, with exactly three switches: the managed
993
+ sidebar agent rows, the Moshi notification channel and the Herdr theme sync
994
+ (§12). The command registers before the `enabled()` pane gate, so every switch
995
+ stays reachable from a plain Pi session outside a Herdr pane. It owns no state of its own and reimplements
996
996
  nothing:
997
997
 
998
998
  - `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js` —
@@ -1012,31 +1012,33 @@ nothing:
1012
1012
  argument, Esc, or a cancelled menu writes nothing. With no argument the
1013
1013
  command opens the floating panel (`lib/customize-panel.js`, painted through its
1014
1014
  own palette) over `ctx.ui.custom` in Gentle Shell's own layout: one left
1015
- `CATEGORIES` list, one right pane headed `<Category> · n/m` with its setting
1016
- rows, each row painting the stored value with `●` and the other with `○`; one
1017
- line above the footer describes the focused setting
1018
- (`<setting> — <what it changes>`), and the footer
1019
- `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`. There is no
1020
- `Click` token and no
1021
- `Preview · …` band and no `p profiles` key: this plugin owns no profiles
1022
- concept, so the footer advertises nothing it cannot do — every token in it is a
1023
- key the panel answers to, and a narrow card compacts the legend instead of
1024
- wrapping it. `←/→` or `Tab` moves
1025
- between the category and value panes, `↑/↓` or `j/k` moves the cursor, `Enter`
1026
- applies the focused row and `Esc` closes without a write; a click on a category
1027
- selects it, a click on a row applies it, and a click outside the panes is
1028
- ignored (a press only captures the gesture, so a drag never applies a row).
1029
- Each switch is one row that paints the stored state and carries the opposite
1030
- value. Each category owns exactly one switch: `Herdr Sidebar` shows the single
1031
- `Sidebar agent rows` row and its description names the managed agent rows only,
1032
- while the only Moshi switch is the `Notifications` row under
1033
- `Moshi notifications`, which applies the `gentle-moshi.json` flag through
1034
- `applyMoshiNotifications`. The two channels are never mixed: the sidebar-rows
1015
+ `CATEGORIES` list, one right pane headed `<Category> · n/m`, and one line per
1016
+ setting with its options inline — `●` the stored option, `›` the cursor while it
1017
+ sits elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
1018
+ applies; `Enter` keeps the card open (only a Moshi settings change that needs a
1019
+ Pi reload closes it), `Esc` closes without a write, `Tab`
1020
+ switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose options
1021
+ do not fit scrolls sideways behind muted `‹`/`›` markers with an `n/m` counter,
1022
+ falling back to a compact `‹ value ›`; the Preview block below the panes reads
1023
+ `Preview · <option> · <title>` plus a sample, and a theme option is painted in
1024
+ that theme's own palette; the footer carries one of three legends (categories,
1025
+ option row, panes) after the `Click · ` prefix, chosen by what the keys do right
1026
+ now and compacted instead of wrapped on a narrow card, with no `p profiles` key
1027
+ because this plugin owns no profiles concept. A click on an option applies
1028
+ exactly that option, a click on a setting's name only moves the focus, a click
1029
+ on a category selects it, and a click outside the panes is ignored (a press only
1030
+ captures the gesture, so a drag never applies anything).
1031
+ Each category owns its own settings: `Herdr Sidebar` shows the single
1032
+ `Sidebar agent rows` setting, the only Moshi switch is the `Notifications`
1033
+ setting under `Moshi notifications`, which applies the `gentle-moshi.json` flag
1034
+ through `applyMoshiNotifications`, and `Herdr Theme` owns the `Theme sync`
1035
+ toggle plus the inline `Gentle Shell theme` list (§12). The two channels are
1036
+ never mixed: the sidebar-rows
1035
1037
  switch neither reads nor writes that flag, so disabling the agent rows leaves
1036
1038
  the notification channel exactly as it was.
1037
- An inconclusive sidebar verdict (`unknown`) renders as `● Unknown` with a note
1038
- instead of hiding the row: toggling still attempts the repair and reports the
1039
- apply step's own error, exactly like the menu. The plain
1039
+ An inconclusive sidebar verdict (`unknown`) renders with no option marked `●`
1040
+ and a note instead of hiding the setting: toggling still attempts the repair and
1041
+ reports the apply step's own error, exactly like the menu. The plain
1040
1042
  two-step `ctx.ui.select` menu remains the
1041
1043
  fallback when the TUI helpers or `ctx.ui.custom` are unavailable. The removed
1042
1044
  `Plugin tools` and `Reset` sections and the in-process provider slot
@@ -1161,9 +1163,9 @@ exactly one mechanism writes each piece of state.
1161
1163
  panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
1162
1164
  ship. This package publishes the Herdr producer sidecar and the Moshi channel
1163
1165
  only; `bin/gentle-sidebar.js` is its one CLI and `/herdr-gentle:customize`
1164
- its one in-Pi command, carrying just the sidebar-rows and Moshi switches.
1165
- Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]` stays
1166
- removed, so no other extension renders those two switches.
1166
+ its one in-Pi command, carrying just the sidebar-rows, Moshi and theme-sync
1167
+ switches. Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
1168
+ stays removed, so no other extension renders those switches.
1167
1169
  - Rollback: disable this plugin → producer stops writing; consumer sweeps
1168
1170
  only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
1169
1171
  `↳N` behavior with zero data migration.
@@ -1251,3 +1253,296 @@ confirming each criterion has a normative section:
1251
1253
  Task closes when V1–V6 are all traceable above and the file re-read reports
1252
1254
  path + line count. Any untraceable cell → `status: partial` with the gap
1253
1255
  list, not silent.
1256
+
1257
+ ## 12. Theme sync (Pi palette → Herdr theme)
1258
+
1259
+ 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 in
1261
+ `/herdr-gentle:customize`; the user-facing reference is
1262
+ [docs/theme-sync.md](docs/theme-sync.md). Six modules with one owner — this Pi
1263
+ package — and one direction of data:
1264
+
1265
+ | Module | Owns |
1266
+ | --- | --- |
1267
+ | `lib/theme-store.js` | The one persisted document (`gentle-theme.json`): the state-dir resolution copied verbatim from the sidecar's Moshi flag, a normalised read, and the atomic replace. |
1268
+ | `lib/theme-projection.js` | The pure translation: assignable Herdr theme names, Herdr token order, `HERDR_ROLE_SOURCES`, the `DOTS_FIXED` surface tables, `projectPalette`, `paletteFingerprint`, and the `Off` label the projection exposes. No filesystem, no host import. |
1269
+ | `lib/herdr-theme-config.js` | The pure planner — a **line splicer, not a TOML validator**: table-boundary scanning (headers only at real line starts), 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 single regenerated block (`begin` / `begin created` … `end` / `end after a missing line ending`) and the created table it removes again, the ambiguity refusal for a marker-shaped comment above a block being removed or moved, the 1.8.0 marker-pair migration, the BOM, and the enforced splice invariant. |
1270
+ | `lib/herdr-theme-apply.js` | The writer: the availability guard matrix, the bounded snapshot, the two compare-and-swap checks, the atomic non-overwriting backup (a regular existing file is accepted as it is), retried temp cleanup that names a survivor and only ever removes a path it created itself, the growth limit, `forceReload`, the exclusive temp + `fchmod` (all mode bits) + `fsync` + `rename`, and the reload. |
1271
+ | `extensions/herdr-theme-sync.ts` | The follower: session-start evaluation, 500 ms tick, the two identities, one in-process apply per change, the notices. |
1272
+ | `lib/customize-panel.js` + the theme wiring in `extensions/gentle-herdr-state.ts` | The switch and the card: `applyThemeSync`, `writeThemeChoice`, `applyCustomizePanel`, `customize status`, and the setting lines, Preview block, legends and pointer hits. |
1273
+
1274
+ **In process, and why that is the fix.** The 1.8.0 follower spawned
1275
+ `bin/configure-theme.js` from the *separately installed* Herdr plugin, found
1276
+ through `herdr plugin list`, and that writer refused any `[theme]` table outside
1277
+ its own marker block. A Pi-only update therefore kept running the old plugin's
1278
+ writer — or, on an install that never shipped it, ran no writer at all — while
1279
+ the user's real config, which already owns `[theme]`, was never touched. The
1280
+ reference implementation
1281
+ ([gentle-herdr](https://github.com/MarsSall/gentle-herdr), MIT License,
1282
+ Copyright (c) MarsSall) applies from Pi itself, so this package does the same:
1283
+ `applyHerdrTheme` edits the config inside the running Pi process, and the
1284
+ plugin-side `configure-theme.js`, its planner and the
1285
+ `# BEGIN herdr-gentle-theme` managed block are gone. The plugin is not involved
1286
+ in theme sync and needs no update for it. A config written by 1.8.0 keeps
1287
+ working: the planner drops those two marker lines only when they are the nearest
1288
+ pair and the pair actually encloses a `[theme]`/`[theme.custom]` table (a stale
1289
+ pair around unrelated keys is the user's text and stays, and a pair closing on an
1290
+ unterminated last line migrates without changing the file's final-newline state),
1291
+ then edits the table between them like any other. Pi colours become hex
1292
+ strings in the follower through `colorToHex` from `@earendil-works/pi-tui`,
1293
+ which is why the follower is its own extension rather than a section of the
1294
+ state sidecar: the sidecar is loaded by every suite as a renamed copy with one
1295
+ stubbed host import, and the projection needs no host at all.
1296
+
1297
+ **Ownership rule, and the two classes it implies.** Sync is a switch the user
1298
+ turns on deliberately, so with the sync on — or a theme pinned — this package
1299
+ OWNS the `name` line and every token it projects, and it must be able to give
1300
+ them back. Two classes, which is what makes switching Pi themes safe:
1301
+
1302
+ - **a value the user already had** is replaced in place and remembered by one
1303
+ comment recording **the whole original line** (minus its indentation, so
1304
+ trailing spaces and an inline comment are part of the record) above it: the
1305
+ first original wins, a later palette change reuses it, and a projection that
1306
+ stops carrying that token — or comes back to the recorded value — **restores
1307
+ the line byte for byte** and drops the comment. The one exception is the
1308
+ **latest edit wins**: if the user changed the line's trailing comment after the
1309
+ planner wrote its value, the restore keeps the recorded key/value and the
1310
+ user's *current* comment. A comment is only a marker when
1311
+ its payload parses as the strict `key = <string> [comment]` line for the key
1312
+ under it, and two markers for one key are refused;
1313
+ - **a token the user did not have** is written inside ONE marked block
1314
+ (`# herdr-gentle-shell: begin` … `# herdr-gentle-shell: end`, or
1315
+ `# herdr-gentle-shell: begin created` when the planner also creates the table,
1316
+ and closed with `# herdr-gentle-shell: end after a missing line ending` when
1317
+ placing the block also added the file's missing final line ending, so a later
1318
+ clear takes back only what the planner added)
1319
+ at the end of `[theme.custom]`, regenerated on every plan, and removed entirely
1320
+ when nothing is left to own — so leaving a projection never leaves a stale
1321
+ colour behind. A table the planner created is removed again once its block
1322
+ empties and nothing else lives in it, which is what makes a cycle of
1323
+ projections ending in an empty custom projection return the original
1324
+ `[theme.custom]` byte for byte; only `<token> = "#rrggbb"` lines may sit
1325
+ inside the block, and anything else there is refused rather than deleted.
1326
+ Removing or moving a block is refused
1327
+ (`line <n>: ambiguous herdr-gentle-shell marker above the managed block`) when a
1328
+ marker-shaped comment directly above `begin` would become adjacent to the token
1329
+ key under the block, because the next plan would promote the user's ordinary
1330
+ comment to ownership.
1331
+
1332
+ A token the user owns with no marker (`panel_bg`, `blue`, `yellow`, …) is never
1333
+ written, merged or repaired, even when the projection stops carrying it: it was
1334
+ never ours. A `[theme.custom]` header the **user** wrote stays even when it ends
1335
+ up empty, because the planner cannot prove it created that line. Two
1336
+ consequences are stated rather than papered over: a tool that rewrites the same
1337
+ keys (a desktop-theme sync such as DMS/Niri, for example) overwrites the
1338
+ projected values on its next run, and the next palette change here overwrites
1339
+ them back; and the revert is per token, not per file — a user-written empty header
1340
+ and the `name` marker stay. This is also where
1341
+ the port deliberately differs from the reference: it accepts
1342
+ `auto_switch = false` untouched — the reference refuses that line outright,
1343
+ which is exactly why the user's real config was never written — and it edits
1344
+ tables the reference treats as foreign.
1345
+
1346
+ **The state file is the only persisted truth.** `gentle-theme.json` holds
1347
+ `{sync, theme, updatedAt}` and nothing else is cached, mirrored or inferred: the
1348
+ panel and the follower read the same document, so the setting, the switch and
1349
+ the applied palette can never disagree. Missing is inert (`sync:false`,
1350
+ `theme:null`); a document that cannot be read or parsed is a refusal — `ok:false`,
1351
+ no option marked, a `state unknown` note, follower silent — never a guess, and
1352
+ it is written over only
1353
+ when the user acts. The default install (sync off, no theme) therefore writes
1354
+ nothing at all (S7), and a stored pin is carried across a sync toggle so turning
1355
+ the sync off restores that choice instead of unassigning it.
1356
+
1357
+ **Tick, fingerprint and the follower repairs.** The host publishes no
1358
+ theme-change event, so the palette is a pull-read of `ctx.ui.theme` (or
1359
+ `ctx.ui.getTheme(name)` for a pin): one immediate evaluation on `session_start`
1360
+ and then one every 500 ms, on an unreferenced timer so an idle follower never
1361
+ keeps Pi alive, cleared on `session_shutdown` (a shutdown that lands during the
1362
+ first evaluation wins: no tick is armed afterwards). Each evaluation computes two
1363
+ identities — the requested `[sync, chosen]` and the palette fingerprint
1364
+ (`[theme name, sorted token/hex pairs]`) — and acts only when one differs from
1365
+ the last one it recorded, so a theme recoloured in place (same name, new
1366
+ colours) is noticed without a restart, and the same palette is never applied
1367
+ twice. The observation is recorded **before** the apply, so a failed or refused
1368
+ write is never retried on the next tick and never blocks the next real change
1369
+ either; one apply is in flight at a time. With the sync off and no theme pinned
1370
+ the follower asks for nothing at all (no write, no removal) **and forgets what it
1371
+ applied**, which is what makes re-enabling the sync always re-apply: without that
1372
+ reset the next `On` would look unchanged and a config the user repaired in
1373
+ between would never be written (an already-matching config then answers
1374
+ `unchanged`). A projection with no concrete token is refused before the writer is
1375
+ called — `Herdr theme not applied: <name> has no concrete colours to project.`,
1376
+ once per session — because it would otherwise rewrite the theme name and paint
1377
+ nothing. Availability is decided once, by `applyHerdrTheme`, so the follower can
1378
+ never disagree with the writer about who may write; a subagent child
1379
+ (`GENTLE_PI_AGENTS_CHILD=1`) never registers the follower at all, and every
1380
+ user-visible outcome is one of the fixed notices in
1381
+ [docs/theme-sync.md](docs/theme-sync.md). A `partial/reload` sets an **owed
1382
+ reload**: the next apply attempt of the same session is sent with
1383
+ `forceReload`, and a success pays the debt off. It is session memory on purpose
1384
+ (a tick never reloads while the debt stands), which is why the notice ends with
1385
+ `Run 'herdr server reload-config' to apply it.`
1386
+
1387
+ **A splicer, and a strict core.** The writer edits the user's own `[theme]` and
1388
+ `[theme.custom]` tables and preserves every byte it does not own: other tables
1389
+ and keys, comments, blank lines, ordering, indentation, spacing around `=`, a
1390
+ trailing comment on a rewritten line, CRLF or mixed endings, a leading UTF-8 BOM
1391
+ and a missing final newline. **Outside those two tables nothing is validated**:
1392
+ the planner only tracks the three contexts that can hide a line
1393
+ break (multi-line strings, multi-line arrays, inline tables) plus comments, so it
1394
+ can find table boundaries — a header-shaped line must parse and a multi-line
1395
+ construct must be terminated, or the plan refuses — and it treats the rest of the
1396
+ document as opaque bytes: an input that is already invalid TOML there is the
1397
+ user's pre-existing breakage (Herdr refuses to load it) and is left exactly as it
1398
+ is. Escapes there are never validated (a backslash only consumes the next
1399
+ character, in single-line and multi-line strings alike) and a run of three or
1400
+ more quotes closes a multi-line string; the scan validates escapes only where it
1401
+ must read a value back (a quoted key and a strict theme-table line).
1402
+ **Inside the two tables it is strict**: comments, blank lines and
1403
+ `key = value [comment]` with a single-line string, boolean, integer or float; a
1404
+ key the plan must touch in any other form is refused with its line number, while
1405
+ a key it does not touch is kept byte for byte whenever the scanner can find where
1406
+ that line ends. It refuses: `auto_switch` with a value other than `false`,
1407
+ `dark_name`/`light_name`, a top-level `theme` key, a dotted key extending
1408
+ `[theme]` or a Herdr token in `[theme.custom]`, a second `[theme]`/`[theme.custom]`
1409
+ table, a third `[theme.*]` table, `[[theme]]` array-of-tables, `name`/
1410
+ `auto_switch` repeated in `[theme]`, a token repeated in `[theme.custom]` or in
1411
+ both the block and the user's keys, two markers for one key, a touched value that
1412
+ is not a strict single-line string (or a multi-line form, refused as "cannot
1413
+ record the original value … safely"), a control character, a bare carriage
1414
+ return, a malformed block (outside `[theme.custom]`, unterminated, a second
1415
+ begin, an end without a begin, any line in it that is not
1416
+ `<token> = "#rrggbb"`), the ambiguous marker above a block that is about to be
1417
+ removed or moved (`ambiguous herdr-gentle-shell marker above the managed
1418
+ block`), and a table header or unterminated multi-line string/array/inline table
1419
+ the boundary scan cannot resolve. A malformed
1420
+ projection is refused the same way without a line number, because that one is a
1421
+ package bug. **The splice invariant is enforced in code**: before `ok: true` the
1422
+ planner re-derives the non-theme lines of its own output and compares them with
1423
+ the input's (only the 1.8.0 marker lines it wrote may be missing, and only the
1424
+ single terminator needed to append a table after an unterminated last line may be
1425
+ added); a mismatch returns `internal splice invariant violated; no changes
1426
+ proposed.` rather than a document that moved a byte it promised not to touch. The
1427
+ file-level refusals belong to the snapshot and the write: a non-absolute or
1428
+ non-canonical path, a symlinked parent directory, not a regular single-link
1429
+ file, over 256 KiB, invalid UTF-8, a backup path that is not a regular file, a
1430
+ planned document past the 256 KiB limit, bytes that changed between the snapshot
1431
+ and the replacement (`Herdr config changed before replacement`), a backup temp
1432
+ that cannot be removed, a missing config (never bootstrapped), and a failed
1433
+ rename. Every refusal writes nothing, backs up nothing and reloads nothing.
1434
+
1435
+ **Safe write, and exactly one reload.** The snapshot is one bounded strictly
1436
+ decoded read with stat identity checks; a leading BOM is decoded as part of the
1437
+ text (`ignoreBOM`) so a changed write keeps it and the backup and the file agree
1438
+ on those bytes. The plan is refused **before anything is written** if the
1439
+ document would grow past the same 256 KiB limit. The original bytes are re-read
1440
+ and compared immediately before the backup and again immediately before the
1441
+ swap, so a projection computed from stale bytes is never renamed into place. The new text
1442
+ is staged at a path chosen **before the file exists**, so every failure — open,
1443
+ write, `fsync`, `fchmod` — leaves the writer able to remove it: exclusive `0600`,
1444
+ `fchmod`-ed to the original mode (`0o7777`, so setuid/setgid/sticky survive),
1445
+ compared once more, then `rename`d. Temp cleanup is best-effort **and never
1446
+ silent**: the unlink is retried once and then force-removed, and a survivor is
1447
+ reported instead of hiding — if the **backup's** temp survives, the apply fails
1448
+ with `Herdr backup temporary could not be removed: <path>` (so it can never
1449
+ answer `requested` with a stray file), and a surviving **staged** temp appends
1450
+ `; temporary file left behind: <path>` to the `partial`/`config` error. Cleanup
1451
+ only ever removes a path the call created itself: a foreign file at that exact
1452
+ temp name makes the exclusive open fail with `EEXIST`, the apply answers
1453
+ `partial`/`config` with that text, and the file is left alone (config and backup
1454
+ untouched). The
1455
+ backup itself is **published atomically and never overwritten**: written to a
1456
+ temp name and hard-linked into place, so a crash or a full disk leaves no
1457
+ truncated `.bak` that a later run would mistake for "already backed up". A
1458
+ regular file already at the backup path — pre-existing or raced — **is** the
1459
+ existing backup: accepted as it is, never compared and never overwritten (it may
1460
+ be an older original from before the user's last edit), while a non-regular
1461
+ entry (directory, symlink, socket) is refused. `unchanged` writes
1462
+ nothing and reloads nothing — Herdr already holds that palette, and a reload on
1463
+ every tick would make the sidebar flicker for nothing. `forceReload` is the one
1464
+ exception, and it exists for the owed-reload repair above: it reloads an
1465
+ unchanged plan and answers `requested`. A real write is followed by exactly one
1466
+ `herdr server reload-config` through `execFile` with `HERDR_BIN_PATH` (default
1467
+ `herdr`), no shell, a 5 s timeout and a 4096-byte output cap; a reload failure is
1468
+ reported as partial state because the config is already committed. **CAS limit:**
1469
+ an edit that lands between the final compare and the `rename` cannot be detected
1470
+ without holding a lock on the config, which this writer deliberately does not
1471
+ do — everything earlier (snapshot, plan, backup, staging) is still caught. A
1472
+ **pre-existing truncated backup** is a second documented limit: because a regular
1473
+ file at that path is accepted as it is and never repaired or compared, a `.bak`
1474
+ damaged by an earlier failure or another tool stays damaged.
1475
+
1476
+ **The guard matrix.** `applyHerdrTheme` answers `unavailable` with one reason
1477
+ before it opens any file: `not-herdr` (no `HERDR_ENV=1` plus a pane id and an
1478
+ absolute socket path), `child` (a subagent's Pi must never write the user's
1479
+ config), `remote` (an SSH session, where Herdr reads another machine's config),
1480
+ and `unsupported` (a `herdr-dev` binary, a non-Linux host, or a non-absolute
1481
+ socket/config path). The follower reports `not-herdr`, `remote` and
1482
+ `unsupported` as one `info` notice per session and asks again only when the
1483
+ palette itself changes.
1484
+
1485
+ **The panel.** `/herdr-gentle:customize` reuses Gentle Shell's own card shape:
1486
+ one left `CATEGORIES` list, one right pane headed `<Category> · n/m`, one line
1487
+ per setting with its options inline (`●` stored, `›` cursor elsewhere, `○` the
1488
+ rest). The arrows move the option cursor and only Enter applies; Enter keeps the
1489
+ card open (only the Moshi reload closes it), Esc closes without a write, Tab
1490
+ switches panes. A line whose options do not fit scrolls sideways behind muted
1491
+ `‹`/`›` with an `n/m` counter, falling back to a compact `‹ value ›`. The
1492
+ Preview block below the panes is `Preview · <option> · <title>` plus a sample
1493
+ painted with the host theme, where a theme option shows that theme's own palette
1494
+ through the raw SGR the host hands back. Three footer legends (categories,
1495
+ option row, panes) are chosen by what the keys do right now and compact instead
1496
+ 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 painted dim and
1498
+ refused with `Turn Theme sync off to pick a specific theme.` while the sync is
1499
+ on, and a host that exposes no list shows one note instead of an empty picker.
1500
+ The panel writes nothing itself: it calls the extension's apply path, swaps in
1501
+ the model that path re-read, and keeps the cursor by structural option ids.
1502
+
1503
+ **Limits** (the §10 style, none of them a promise this design makes):
1504
+
1505
+ - The 500 ms tick is the whole observation granularity — there is no event to
1506
+ subscribe to, so a theme change is noticed within one tick and not sooner.
1507
+ - The automated evidence is a stubbed Pi host plus a real binary stand-in on
1508
+ disk; **no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
1509
+ `getAllThemes`, `notify` and the host component contract are used as
1510
+ documented, and a host missing one degrades to "nothing changed" rather than
1511
+ to a guess.
1512
+ - Remote sessions are inactive: in SSH the Herdr client reads the config of the
1513
+ machine it runs on, so writing the server-side file would change nothing on
1514
+ screen and the guard refuses.
1515
+ - Two writers of the same keys fight. The sync owns what it projects, so a
1516
+ desktop-theme sync and this feature overwrite each other on their next run;
1517
+ there is no merge, lock or arbitration, only the `was` comments, the marked
1518
+ block and the one-time backup.
1519
+ - The compare-and-swap has one unavoidable window: an edit between the final
1520
+ compare and the rename is undetectable without a config lock, which this
1521
+ writer does not take.
1522
+ - The planner is a **splicer, not a validator**: it guarantees table boundaries
1523
+ for terminated multi-line constructs and byte-identical non-theme lines (checked
1524
+ by the splice invariant), and it deliberately checks nothing outside the theme
1525
+ tables — invalid TOML there is left as it is, because Herdr already refuses
1526
+ that file. A theme-table line the plan must touch has to be the strict
1527
+ single-line form; the revert is per token, so a user-written empty
1528
+ `[theme.custom]` header and the `name` marker stay behind (a table the planner
1529
+ created is removed, so a full cycle is byte-identical).
1530
+ - A pre-existing truncated backup is kept, not repaired (see above), which is why
1531
+ the `was` comments are the per-value revert path.
1532
+ - There is no "full clear" distinct from an empty custom projection: a projection
1533
+ always carries the theme name, so a `name` line the planner inserted stays (an
1534
+ existing name is restored) and a `[theme]` table it created is not removed —
1535
+ only the `[theme.custom]` table it created is, once its block empties.
1536
+ - Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
1537
+ `selection_bg`, `surface*`) and `peach` are not projected: Pi names
1538
+ foregrounds and accents, not panel backgrounds, so backgrounds and status
1539
+ colours stay with the Herdr base theme — except the `DOTS_FIXED` tables for
1540
+ `Gentleman-Cute`, `Gentleman-Sexy` and `Gentle`, which are the surfaces the
1541
+ user's own Herdr profiles already use.
1542
+ - One machine: another Herdr client reads its own `config.toml`, so this is a
1543
+ local sync and not a fleet setting.
1544
+ - No automatic repair: a `[theme]` table the user or another tool keeps editing
1545
+ is re-projected on the next palette change and never reconciled, and a document
1546
+ whose table boundaries cannot be found (an unterminated multi-line string,
1547
+ array or inline table) stops the writer until it is fixed. A missing
1548
+ `config.toml` is refused, never created.
package/README.md CHANGED
@@ -484,26 +484,37 @@ 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`): two switches, both local
488
- state and both reachable from a plain Pi session outside a Herdr pane. With
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
489
  no argument the command opens the floating panel in Gentle Shell's own
490
- layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`)
491
- and one right pane headed `<Category> · n/m` with its setting rows, each row
492
- painting the stored value with `●` and the other with `○`; one line above the
493
- footer describes the focused setting (`<setting> — <what it changes>`), and
494
- the footer reads
495
- `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`, while `←/→` or
496
- `Tab` moves between the category and value panes, `↑/↓` or `j/k` moves the
497
- cursor, `Enter` applies the focused row and `Esc` closes without a write. The
498
- legend names only keys: it never advertises `Click`, because every token in
499
- it is a key the panel answers to, and a narrow card compacts it instead of
500
- wrapping. Pointer input still works without being advertised — a click on a
501
- category selects it, a click on a row applies it, and a click outside the
502
- panes is ignored. Each category owns exactly one switch: `Herdr Sidebar`
490
+ layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
491
+ `Herdr Theme`)
492
+ and one right pane headed `<Category> · n/m`, where each setting is ONE line
493
+ with its options inline — `●` the stored option, `›` the cursor while it sits
494
+ elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
495
+ applies; `Enter` keeps the card open (a Moshi change that needs a Pi reload
496
+ closes it first), `Esc` closes without a write, `Tab`
497
+ switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose
498
+ options do not fit scrolls sideways behind muted `‹` / `›` markers with an
499
+ `n/m` counter (falling back to a compact `‹ value ›` when not even one option
500
+ fits), and the Preview block below the panes reads
501
+ `Preview · <option> · <title>` plus a sample painted with the host theme (a
502
+ theme option shows that theme's own palette). The footer carries one of three
503
+ legends after a `Click · ` prefix —
504
+ `↑/↓ categories · → open · Esc close`,
505
+ `←/→ choose · Enter apply · ↑/↓ settings · Tab panes · Esc close`, or
506
+ `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close` — and compacts
507
+ instead of wrapping on a narrow card. A click on an option applies exactly
508
+ that option, a click on a setting's name only moves the focus, a click on a
509
+ category selects it, and a click outside the panes is ignored. Each category
510
+ owns its own rows: `Herdr Sidebar`
503
511
  shows the single `Sidebar agent rows` row, and the only Moshi switch is the
504
- `Notifications` row under `Moshi notifications`. The two are never mixed —
505
- `Sidebar agent rows` neither reads nor writes `gentle-moshi.json`, so turning
506
- the agent rows off never turns the notification channel off. Herdr's own
512
+ `Notifications` row under `Moshi notifications`, while `Herdr Theme` owns
513
+ both theme settings (the `Theme sync` toggle and the inline
514
+ `Gentle Shell theme` list described in the subsection below). The
515
+ sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
516
+ reads nor writes `gentle-moshi.json`, so turning the agent rows off never
517
+ turns the notification channel off. Herdr's own
507
518
  done/ask attention (the finished and needs-attention pop-ups and their
508
519
  sound) is Herdr's native behavior, configured in Herdr itself — its config
509
520
  and its settings — and this package deliberately offers no switch for it:
@@ -518,7 +529,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
518
529
  `settings.json`, running the `moshi-hook` pairing gate before enabling (a
519
530
  refusal writes nothing) and reloading Pi only when that settings entry
520
531
  actually changed. `/herdr-gentle:customize status` prints one read-only line
521
- (`customize status: sidebar=<on|off|unknown> moshi=<on|off>`); an unknown
532
+ (`customize status: sidebar=<on|off|unknown> moshi=<on|off>
533
+ theme-sync=<on|off|unknown> theme=<name|none|unknown>`); an unknown
522
534
  argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
523
535
  `unknown` is never a refusal: the panel says the state is unknown and
524
536
  choosing `On` still runs the apply step, reporting that step's own error
@@ -588,6 +600,75 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
588
600
  reached through `/herdr-gentle:customize`. See
589
601
  [docs/herdr-session-open.md](docs/herdr-session-open.md).
590
602
 
603
+ ### Theme sync (Herdr palette follows Pi)
604
+
605
+ `/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned theme.
606
+ `Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
607
+ palette of the theme Pi is showing, and it follows a theme change while Pi keeps
608
+ running. While it is off, `Gentle Shell theme` pins one Gentle Shell / Pi theme
609
+ from Pi's own inline list (`None` first, then the host's order) and `None`
610
+ clears the pin; the setting is painted dim and refused while the sync is on
611
+ (`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
612
+ nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
613
+ whose sync is off and whose theme is unassigned writes nothing at all. State is
614
+ one file, `gentle-theme.json`, beside `gentle-moshi.json`.
615
+
616
+ The writer runs **in process in this Pi package**
617
+ (`lib/herdr-theme-config.js` plans it, `lib/herdr-theme-apply.js` writes it,
618
+ `extensions/herdr-theme-sync.ts` follows the theme), so the Herdr plugin is not
619
+ involved and needs no update for this feature. It is a **line splicer, not a TOML
620
+ validator**: it finds the boundaries of your `[theme]` and `[theme.custom]`
621
+ tables (a header only counts at a real line start, never inside a multi-line
622
+ string, array or comment) and treats every line outside them as opaque bytes —
623
+ nothing there is validated or rewritten (escapes included), and an invalid line
624
+ outside those tables is left exactly as it is, because Herdr already refuses such
625
+ a file (the scanner only looks at those lines far enough to find where a table
626
+ starts and ends). A
627
+ splice invariant is enforced before a plan is returned: the non-theme lines of
628
+ the output must be byte-identical to the input's.
629
+
630
+ Inside the two theme tables it edits in place and keeps two kinds of value
631
+ apart: a value you already had is replaced where it stands and remembered by one
632
+ comment recording **the whole original line** (one per key; the first original
633
+ wins, and restoring gives back your quoting, spacing and inline comment — or
634
+ **your current comment** when you edited it after the planner wrote the value,
635
+ because the latest edit wins), while
636
+ a token you did not have is written inside ONE marked block — a `begin`/`end`
637
+ comment pair naming this package, spelled `begin created` when the planner also
638
+ created the table and closed with `end after a missing line ending` when placing
639
+ the block also added the file's missing final newline, so clearing gives that
640
+ byte back — at the
641
+ end of `[theme.custom]`, regenerated on every apply. Leaving a theme therefore
642
+ never leaves a stale colour: a token that leaves the projection is restored from
643
+ its comment byte for byte (or when the projection returns to the recorded value),
644
+ or dropped with the block when the package created it, and a token you own
645
+ without such a comment is never touched. Removing or moving that block is refused
646
+ (`ambiguous herdr-gentle-shell marker above the managed block`) when a
647
+ marker-shaped comment directly above `begin` would end up attached to the key
648
+ under it. Everything else — other tables,
649
+ comments, ordering, a BOM, CRLF or mixed endings, a missing final newline — is
650
+ preserved, a one-time `<config>.herdr-gentle-shell.bak` is published atomically
651
+ before the first modification and never overwritten, and a temp file that
652
+ survives a failed replace is named in the error instead of being hidden, while a
653
+ temp path the writer did not create itself is never deleted (the apply reports
654
+ the `EEXIST` and leaves it alone). What
655
+ fails closed, with the line number and no write, is what a theme-table edit
656
+ cannot be done safely over: `auto_switch` with a value other than `false`,
657
+ `dark_name`, `light_name`, a top-level `theme` key, a dotted key extending the
658
+ theme tables, a duplicated `[theme]`/`[theme.custom]` table or duplicated key
659
+ inside them, a line inside the marked block that is not a token assignment, and a
660
+ value the plan must touch that is not a strict single-line string/boolean/number
661
+ (an unterminated multi-line string or array anywhere also blocks the plan,
662
+ because table boundaries depend on it). While the sync is on (or a theme is
663
+ pinned) the package owns the tokens it projects, so another tool that rewrites
664
+ the same keys (a desktop-theme sync, for example) overwrites them on its next run
665
+ and the next palette change here overwrites them back. There is no "full clear":
666
+ a projection always carries a theme name, so a `name` line the planner inserted
667
+ stays, and only the `[theme.custom]` table it created is removed again. See
668
+ [docs/theme-sync.md](docs/theme-sync.md) for the golden example, the exact
669
+ comment and block lines, what is and is not guaranteed, the refusals, the
670
+ notices and the limits.
671
+
591
672
  ## Documentation
592
673
 
593
674
  | Your task | Start here |
@@ -598,6 +679,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
598
679
  | Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
599
680
  | Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
600
681
  | Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
682
+ | Theme sync (Pi palette → Herdr theme, written in process) | [docs/theme-sync.md](docs/theme-sync.md) |
601
683
  | Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
602
684
  | Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
603
685