herdr-gentle-shell 1.3.0 → 1.5.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.
@@ -5,11 +5,12 @@
5
5
  // Shell's own customize card (odd/tasks/customize-parity-done-idle.md T1, S1).
6
6
  //
7
7
  // One left `CATEGORIES` list, one right pane headed `<Category> · n/m` holding
8
- // the setting rows, and the Shell's footer keys. Each switch is ONE row that
9
- // paints the stored value with `●` and the other with `○`, so Enter (or a click
10
- // on the row) is still the whole toggle. The removed worktree / ODD / Issues /
11
- // Reset sections are gone, and the panel reads the current state handed in by
12
- // the extension instead of a cross-extension provider slot.
8
+ // the setting rows, one line describing what the focused setting does, and the
9
+ // Shell's footer keys. Each switch is ONE row that paints the stored value with
10
+ // `●` and the other with `○`, so Enter (or a click on the row) is still the
11
+ // whole toggle. The removed worktree / ODD / Issues / Reset sections are gone,
12
+ // and the panel reads the current state handed in by the extension instead of a
13
+ // cross-extension provider slot.
13
14
  //
14
15
  // The host component contract (pi-coding-agent `custom`): the factory receives
15
16
  // (hostTui, theme, keybindings, done) and returns
@@ -156,19 +157,39 @@ const CUSTOMIZE_PILL_OTHER = "○";
156
157
  // The switches this package owns. `id` is the apply target the extension knows
157
158
  // (the sidebar rows go through the Herdr plugin's own configure step,
158
159
  // notifications through the `gentle-moshi.json` flag and its Pi settings
159
- // exclusion) and `setting` is the row name the panel paints.
160
+ // exclusion) and `setting` is the row name the panel paints. `description` is
161
+ // the one line the card shows for the focused setting: it says what the switch
162
+ // changes, and the notification switch is the Moshi channel, never the agent
163
+ // notifications the host owns.
160
164
  const CUSTOMIZE_SWITCHES = [
161
- { id: "sidebar", setting: "Sidebar agent rows" },
162
- { id: "moshi", setting: "Notifications" },
165
+ {
166
+ id: "sidebar",
167
+ setting: "Sidebar agent rows",
168
+ description: "Hands the Herdr sidebar to this plugin's managed agent rows.",
169
+ },
170
+ {
171
+ id: "moshi",
172
+ setting: "Notifications",
173
+ description: "Replaces the Moshi hook with this plugin's own notification channel.",
174
+ },
163
175
  ];
164
176
 
165
- // Categories only group rows for display. Notifications appears under both
166
- // headings on purpose: `Herdr Sidebar` is where the plugin's own switches are
167
- // looked for, and `Moshi notifications` keeps the switch the user already
168
- // knows. Both rows read the one flag, so they can never disagree.
177
+ // Two categories, one row each. `Herdr Sidebar` owns the managed agent rows the
178
+ // plugin publishes and nothing else: the Moshi notification channel lives only
179
+ // under `Moshi notifications`, so the sidebar switch can never toggle it.
169
180
  const CUSTOMIZE_CATEGORIES = [
170
- { id: "sidebar", title: "Herdr Sidebar", switches: ["sidebar", "moshi"] },
171
- { id: "moshi", title: "Moshi notifications", switches: ["moshi"] },
181
+ {
182
+ id: "sidebar",
183
+ title: "Herdr Sidebar",
184
+ description: "The managed agent rows this plugin hands to the Herdr sidebar.",
185
+ switches: ["sidebar"],
186
+ },
187
+ {
188
+ id: "moshi",
189
+ title: "Moshi notifications",
190
+ description: "The Moshi notification channel this plugin owns.",
191
+ switches: ["moshi"],
192
+ },
172
193
  ];
173
194
 
174
195
  // One row per switch: it paints the stored value and carries the value Enter
@@ -181,6 +202,7 @@ function toggleRow(definition, active) {
181
202
  id: current === "on" ? "off" : "on",
182
203
  switchId: definition.id,
183
204
  setting: definition.setting,
205
+ description: definition.description,
184
206
  current,
185
207
  currentLabel: current === "on" ? "On" : current === "off" ? "Off" : "Unknown",
186
208
  otherLabel: current === "on" ? "Off" : "On",
@@ -199,6 +221,7 @@ function customizePanelModel({ sidebar, moshi } = {}) {
199
221
  return CUSTOMIZE_CATEGORIES.map((category) => ({
200
222
  id: category.id,
201
223
  title: category.title,
224
+ description: category.description,
202
225
  rows: category.switches.map((switchId) => toggleRow(
203
226
  CUSTOMIZE_SWITCHES.find((entry) => entry.id === switchId),
204
227
  current[switchId],
@@ -210,9 +233,9 @@ function customizePanelModel({ sidebar, moshi } = {}) {
210
233
  // role and the rest as its description. `short` is the compact form, and
211
234
  // `priority` is the drop order, so the close key outlives every other hint.
212
235
  // There is no `p profiles` entry: this plugin owns no profiles concept, and a
213
- // dead key in the footer would be a lie.
236
+ // dead key in the footer would be a lie. The pointer needs no entry either:
237
+ // every legend token names a key the panel answers to.
214
238
  const CUSTOMIZE_FOOTER_KEYS = [
215
- { text: "Click", short: "Click", priority: 10 },
216
239
  { key: "←/→", text: "←/→ or Tab panes", short: "←/→ panes", priority: 60 },
217
240
  { key: "↑/↓", text: "↑/↓ move", short: "↑/↓ move", priority: 70 },
218
241
  { key: "Enter", text: "Enter apply", short: "Enter apply", priority: 80 },
@@ -358,7 +381,10 @@ function customizeIsKeyRelease(helpers, data) {
358
381
  // One setting line: the name column, then the Shell's pill pair — `●` on the
359
382
  // stored value and `○` on the other. A pair wider than the pane falls back to
360
383
  // the stored pill alone, so the narrow width keeps showing the real state.
361
- function customizeSettingLine(helpers, theme, row, nameWidth, size, focused) {
384
+ // `focused` marks the row Enter would apply (visible in either pane, so the
385
+ // keyboard always shows its target) and `active` adds the band, which only the
386
+ // pane that owns the focus paints.
387
+ function customizeSettingLine(helpers, theme, row, nameWidth, size, focused, active) {
362
388
  const name = String(row.setting);
363
389
  const namePad = " ".repeat(Math.max(0, nameWidth - customizeMeasure(helpers, name)));
364
390
  const prefix = focused ? "▸ " : " ";
@@ -368,7 +394,7 @@ function customizeSettingLine(helpers, theme, row, nameWidth, size, focused) {
368
394
  const pair = `${stored} ${other}`;
369
395
  const showPair = customizeMeasure(helpers, `${lead}${pair}`) <= size;
370
396
  const body = showPair ? pair : stored;
371
- if (focused && theme && typeof theme.bg === "function") {
397
+ if (active && theme && typeof theme.bg === "function") {
372
398
  try {
373
399
  const plain = customizeFit(helpers, `${lead}${body}`, Math.max(0, size));
374
400
  const band = theme.bg("selectedBg", plain + " ".repeat(Math.max(0, size - customizeMeasure(helpers, plain))));
@@ -408,6 +434,15 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
408
434
  const category = model[state.cat];
409
435
  return { category, row: category.rows[state.row[state.cat]] || null };
410
436
  }
437
+ // What the card describes on its own row: the setting the values pane holds
438
+ // the focus on, or the category while the left list owns it.
439
+ function focusedDescription() {
440
+ const category = model[state.cat];
441
+ const row = state.pane === "values" ? focused().row : null;
442
+ return row
443
+ ? { title: row.setting, description: row.description }
444
+ : { title: category.title, description: category.description };
445
+ }
411
446
  function render(width) {
412
447
  const w = typeof width === "number" && Number.isFinite(width) ? Math.floor(width) : 0;
413
448
  state.frame = null;
@@ -435,11 +470,17 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
435
470
  const category = model[state.cat];
436
471
  const rows = category.rows;
437
472
  const showHeading = height >= 6;
473
+ // The description rides directly above the legend, so it needs one more row
474
+ // than the heading and the legend alone; a 6-row card keeps the keys and
475
+ // drops the prose instead of the other way round.
476
+ const showDescription = height >= 7;
438
477
  // Right pane: one line per setting (name column plus the pill pair) and,
439
478
  // when the stored state is unreadable, one muted note under it.
440
479
  const rightLines = rows.map((row, index) => ({ kind: "row", index, row }));
441
480
  for (const row of rows) if (row.note) rightLines.push({ kind: "note", text: row.note });
442
- const contentHeight = Math.max(1, height - 2 - 1 - (showHeading ? 2 : 0));
481
+ // Title, then heading + description + legend when they fit, above two borders.
482
+ const chrome = 1 + (showHeading ? 2 : 0) + (showDescription ? 1 : 0);
483
+ const contentHeight = Math.max(1, height - 2 - chrome);
443
484
  const position = navOnly ? state.cat : state.row[state.cat];
444
485
  const listLength = navOnly ? model.length : rightLines.length;
445
486
  const start = Math.min(Math.max(0, position - contentHeight + 1), Math.max(0, listLength - contentHeight));
@@ -497,6 +538,7 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
497
538
  item.row,
498
539
  nameWidth,
499
540
  rightWidth,
541
+ at === state.row[state.cat],
500
542
  at === state.row[state.cat] && state.pane === "values",
501
543
  );
502
544
  } else if (item && item.kind === "note") {
@@ -512,6 +554,13 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
512
554
  if (navOnly && item) hits.push({ kind: "category", index: at, y, x: rightStart + 2, end: rightStart + rightWidth });
513
555
  else if (item && item.kind === "row") hits.push({ kind: "row", index: item.index, y, x: rightStart + 2, end: rightStart + rightWidth });
514
556
  }
557
+ if (showDescription) {
558
+ const described = focusedDescription();
559
+ lines.push(compose([
560
+ { kind: "value", text: `${described.title} — ` },
561
+ { kind: "description", text: described.description },
562
+ ], inner));
563
+ }
515
564
  if (showHeading) {
516
565
  lines.push(customizePad(helpers, customizeFooter(helpers, theme, CUSTOMIZE_FOOTER_KEYS, inner), inner));
517
566
  }
@@ -566,33 +615,53 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
566
615
  }
567
616
  // Pointer contract: x/y are local to this component's rendered frame, the
568
617
  // card border included. A press only captures the gesture; the click that
569
- // follows activates the hit, so a drag never applies a row by accident.
570
- // Anything outside a pane's text is ignored, which is also the answer for a
571
- // click on a border, the title, the heading or the footer.
618
+ // follows activates the hit, so a drag never applies a row by accident, and
619
+ // a move only carries the focus. Anything outside a pane's text is ignored,
620
+ // which is also the answer for a click on a border, the title, the heading
621
+ // or the footer.
622
+ //
623
+ // The reported `width`/`height` are the box the host rendered, which the
624
+ // overlay may have clipped shorter than the rows this panel budgeted. The hit
625
+ // test therefore reads the frame it rendered and only clamps the row into it:
626
+ // a geometry comparison the user cannot see must never swallow a real click.
627
+ function focusHit(hit) {
628
+ if (hit.kind === "category") {
629
+ if (state.pane === "categories" && state.cat === hit.index) return false;
630
+ state.cat = hit.index;
631
+ state.pane = "categories";
632
+ return true;
633
+ }
634
+ const target = model[state.cat];
635
+ if (!target || !target.rows[hit.index]) return false;
636
+ if (state.pane === "values" && state.row[state.cat] === hit.index) return false;
637
+ state.pane = "values";
638
+ state.row[state.cat] = hit.index;
639
+ return true;
640
+ }
572
641
  function handleMouse(event) {
573
- if (!event || event.button !== "left") return undefined;
574
- if (event.type !== "press" && event.type !== "click") return undefined;
642
+ if (!event) return undefined;
643
+ const moving = event.type === "move";
644
+ if (!moving && (event.button !== "left" || (event.type !== "press" && event.type !== "click"))) return undefined;
575
645
  const frame = state.frame;
576
646
  if (!frame) return undefined;
577
647
  if (!Number.isFinite(event.x) || !Number.isFinite(event.y)) return undefined;
578
- const sized = (!Number.isFinite(event.width) || event.width === frame.width)
579
- && (!Number.isFinite(event.height) || event.height === frame.height);
580
- if (!sized) return undefined;
581
- const hit = frame.hits.find((entry) => entry.y === event.y && event.x >= entry.x && event.x < entry.end);
648
+ const y = Math.min(Math.max(0, Math.floor(event.y)), Math.max(0, frame.height - 1));
649
+ const hit = frame.hits.find((entry) => entry.y === y && event.x >= entry.x && event.x < entry.end);
582
650
  if (!hit) return undefined;
651
+ if (moving) return { handled: true, render: focusHit(hit) };
583
652
  if (event.type === "press") return { handled: true, capture: true, render: false };
584
653
  const target = model[state.cat];
585
654
  if (hit.kind === "category") {
586
655
  state.cat = hit.index;
587
656
  state.pane = "categories";
588
- return { handled: true, render: true };
657
+ return { handled: true, render: true, focus: true };
589
658
  }
590
659
  const row = target ? target.rows[hit.index] : null;
591
660
  if (!row) return undefined;
592
661
  state.pane = "values";
593
662
  state.row[state.cat] = hit.index;
594
663
  done({ categoryId: target.id, switchId: row.switchId, valueId: row.id });
595
- return { handled: true, render: true };
664
+ return { handled: true, render: true, focus: true };
596
665
  }
597
666
  function invalidate() {}
598
667
  return { render, handleInput, handleMouse, invalidate, state };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.3.0",
3
+ "version": "1.5.0",
4
4
  "description": "Pi package for Herdr sidebar states: the Pi extension sidecar that publishes session facts as Herdr pane-metadata tokens, the optional Moshi notification channel, and the Pi-side helpers the Herdr Gentle Shell plugin drives.",
5
5
  "keywords": [
6
6
  "pi-package",