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