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.
@@ -0,0 +1,393 @@
1
+ 'use strict';
2
+
3
+ // The Herdr page of Gentle Shell's own `/gentle:customize` menu
4
+ // (odd/tasks/herdr-customize-page.md T1; specs S1, S3).
5
+ //
6
+ // This module is a PURE TRANSLATION: it reads the customize model the panel
7
+ // already computes (`customizePanelModel` in lib/customize-panel.js) and answers
8
+ // bridge rows for exactly the four options of S1 — `herd agents`, `moshi`,
9
+ // `theme sync`, `select theme` — in that order. It owns no state, reads no file,
10
+ // notifies nobody and reloads nothing: the extension injects `apply`, which is
11
+ // the same choice shape `applyCustomizePanel` accepts, so a row drives the very
12
+ // write path (and therefore the very refusal) the panel and the removed command
13
+ // drive.
14
+ //
15
+ // Two facts about the host decide the shape below, and both were verified against
16
+ // the bridge's own code rather than assumed:
17
+ //
18
+ // 1. The line a user reads is `choice.setting`, NOT `label`: the renderer draws
19
+ // `entry.setting` as the line's name and `choice.value` as each value word
20
+ // (gentle-shell `lib/visual-customize-view.ts:396-404,594`; `docs/contract.md`
21
+ // §4, and the bridge's own toggle rows say so in `src/sections-rows.ts:66-72`
22
+ // — "the id is not a label and never appears here"). So every row of a
23
+ // setting shares the S1 NAME as its `choice.setting`, while the apply path's
24
+ // own setting id (`sidebar`, `moshi`, `theme-sync`, `theme`) rides in the
25
+ // row's closure and is what `apply` receives.
26
+ // 2. The bridge refuses a row whose `label` is not a row name — one to three
27
+ // plain words with no arrow, colon, dot, pipe, slash or bracket
28
+ // (`src/row-names.ts`), and it refuses rather than rewrites. Every label here
29
+ // therefore goes through `rowName()` below, because a host theme name is user
30
+ // data and may freely carry any of those marks.
31
+ //
32
+ // A hidden row is still a row: `visible()` is handed to the host untouched, so
33
+ // the theme rows exist while the sync is on and simply do not show — the honest
34
+ // answer the contract asks for instead of an in-panel refusal.
35
+ //
36
+ // One build is ONE model read (F3). The model the extension hands over runs a
37
+ // synchronous `configure.js --check` subprocess, so a read per callback is
38
+ // unbounded work while the menu opens (41 checks for a 30-theme build, 68 more
39
+ // for the values, ~2.6 s). `customizeRows` therefore takes its snapshot once and
40
+ // every `current()`, `visible()` and `preview()` answers from it; live-ness is
41
+ // across BUILDS, which is exactly what the host does — it rebuilds the rows after
42
+ // every action, and `rows()` calls `customizeRows` again.
43
+
44
+ // The page is a row `category`, never `registerSection`: a section adds a
45
+ // sidebar card, a category is the menu's own page. `Keymaps` is the one
46
+ // reserved category (`src/row-names.ts`) and is never used here.
47
+ const CUSTOMIZE_ROWS_CATEGORY = "Herdr";
48
+
49
+ // The four S1 options, in the order S1 names them, and the panel's own setting
50
+ // ids from the model (`lib/customize-panel.js` `customizePanelModel`). The
51
+ // theme-sync setting lives beside the theme picker in the panel's own category,
52
+ // but S1 puts it third on this page, so the order is stated here instead of
53
+ // inherited from the model's category nesting.
54
+ const SETTINGS = Object.freeze([
55
+ { id: "sidebar", line: "Herd agents" },
56
+ { id: "moshi", line: "Moshi" },
57
+ { id: "theme-sync", line: "Theme sync" },
58
+ ]);
59
+ const THEME_SETTING = Object.freeze({ id: "theme", line: "Select theme" });
60
+
61
+ // The theme picker's structural ids, the same ones lib/customize-panel.js and
62
+ // the extension use: `none` is the "no theme assigned" choice and `theme:<name>`
63
+ // a real theme, so an installed theme literally called `None` or `Off` keeps its
64
+ // own option and stays pinnable.
65
+ const THEME_NONE_OPTION_ID = "none";
66
+ const THEME_OPTION_PREFIX = "theme:";
67
+
68
+ // The unassign entry's text and row name. The text is the extension's documented
69
+ // sentinel and deliberately NOT `Off`: `Off` is what the panel paints for a
70
+ // stored `null`, and a Pi theme may legitimately be named `Off`, so reusing that
71
+ // spelling as the sentinel would make such a theme unpinnable. Its row name is
72
+ // its own too (the sentinel text carries a bracket and four words, so it can
73
+ // never be a row name, and clamping it would keep the `Off` spelling).
74
+ const THEME_UNASSIGN_TEXT = "Off (no theme assigned)";
75
+ const THEME_UNASSIGN_LABEL = "No theme assigned";
76
+
77
+ // The bridge's row-name shape (`src/row-names.ts`): at most three words, and
78
+ // none of the marks that make a name read as a path, a key or a breadcrumb.
79
+ const ROW_NAME_MAX_WORDS = 3;
80
+ const ROW_NAME_MARKS = Object.freeze([
81
+ "\u2192", "\u2190", "\u2191", "\u2193", ":", ".", "|", "/", "\\", "[", "]", "(", ")", "{", "}",
82
+ ]);
83
+
84
+ // THE label rule. `text` is the thing the row names (a value's word, a theme's
85
+ // name); the answer is a name the bridge accepts, or `null` when nothing usable
86
+ // survived. Every mark becomes a word break, along with any other punctuation
87
+ // (`-` and `_` are word characters and stay, so `one-dark` is one word), runs of
88
+ // space collapse, and the first three words are kept. The exact string is never
89
+ // rewritten in a name: a theme's real name rides in its option id
90
+ // (`theme:<name>`) and in the value the host prints, so a row still applies —
91
+ // and shows — precisely the theme it names.
92
+ function rowName(text) {
93
+ if (typeof text !== "string") return null;
94
+ const broken = text.split("").map((char) => (ROW_NAME_MARKS.includes(char) ? " " : char)).join("");
95
+ const words = broken.replace(/[^\p{L}\p{N}_-]+/gu, " ").trim().split(/\s+/).filter((word) => word.length > 0);
96
+ return words.length > 0 ? words.slice(0, ROW_NAME_MAX_WORDS).join(" ") : null;
97
+ }
98
+
99
+ // One build is ONE model read, and a synchronous paint burst is one more at
100
+ // most. The model the extension hands over runs a synchronous
101
+ // `configure.js --check` subprocess, so a read per callback is unbounded work
102
+ // while the menu opens (the verifier measured 41 checks for a 30-theme build plus
103
+ // 68 more for the values, ~2.6 s).
104
+ //
105
+ // The freshness rule is NOT "one snapshot per build". The host does not rebuild
106
+ // the row objects after an action: Gentle Shell's VisualCustomizeView repaints the
107
+ // rows it already holds and calls `choice.current()` and the visibility gate again
108
+ // on the SAME objects (`lib/visual-customize-view.ts:224-231`, `:391-392`). So the
109
+ // snapshot is a CACHE WITH EXPLICIT INVALIDATION: it is dropped whenever an
110
+ // `apply` settles, which is the only moment the stored state can have changed
111
+ // because of this page, and a short TTL covers the reads that arrive while nothing
112
+ // was applied.
113
+
114
+ // How long one snapshot serves repeated reads (milliseconds). Two facts decide it:
115
+ //
116
+ // - A paint burst is synchronous — the host evaluates every `current()`, gate and
117
+ // swatch of the page in one tick — so the cache is what makes a burst cost ONE
118
+ // `--check` instead of ~109.
119
+ // - The arrows only move the cursor (the bridge stages `applyOnMove: false`), so
120
+ // repaints arrive on a human key cadence: one second covers consecutive presses
121
+ // while still noticing a change written by someone else (another process
122
+ // touching the theme store or the managed config) within a second.
123
+ //
124
+ // The TTL is NOT the correctness mechanism: what must be fresh is the state an
125
+ // `apply` produced, and that is `invalidate()` below, never a timer.
126
+ //
127
+ // Two consequences of a FIXED row set repainted on input are ACCEPTED, not fixed,
128
+ // and they are stated here because they follow from this cache by construction:
129
+ //
130
+ // - An external write while the menu is idle becomes visible on the first read
131
+ // after the cache expires, or on a rebuild. The cache never asks the host to
132
+ // repaint, so a repaint that lands before expiry redraws the previous model
133
+ // and the displayed state has no upper freshness bound — on a menu nobody
134
+ // touches the change is not visible at all. That is what buys one `--check`
135
+ // per burst instead of ~109 of them.
136
+ // - If an external write hides the row the user had focused (the theme picker,
137
+ // when the sync is turned on from another process), nothing can keep the cursor
138
+ // on a row that is no longer there: the HOST clamps the focus to the
139
+ // neighbouring row, so Enter acts on that neighbour. The clamp itself writes
140
+ // nothing — the cursor moved, no action ran.
141
+ //
142
+ // Neither is a correctness hole in the stored state: the write a row performs is
143
+ // always checked against a FRESH read of what it writes (a theme name against the
144
+ // host catalogue on the page's own apply path, a switch against its own stored
145
+ // state).
146
+ const MODEL_CACHE_TTL_MS = 1000;
147
+
148
+ // The model is resolved through this cache, never directly by a callback. A
149
+ // function is accepted because the extension's natural source is
150
+ // `() => customizePanelModel(ctx)`; a missing or unreadable model answers no rows
151
+ // instead of throwing.
152
+ function readModel(model) {
153
+ let value = model;
154
+ if (typeof model === "function") {
155
+ try {
156
+ value = model();
157
+ } catch {
158
+ return [];
159
+ }
160
+ }
161
+ return Array.isArray(value) ? value : [];
162
+ }
163
+
164
+ function createModelCache(model) {
165
+ let snapshot = null;
166
+ let expiresAt = 0;
167
+ return {
168
+ read() {
169
+ if (snapshot !== null && Date.now() < expiresAt) return snapshot;
170
+ snapshot = readModel(model);
171
+ expiresAt = Date.now() + MODEL_CACHE_TTL_MS;
172
+ return snapshot;
173
+ },
174
+ // Called when an `apply` settles (resolved OR refused): the host repaints the
175
+ // same rows immediately afterwards, and that repaint must read what the apply
176
+ // wrote. A refusal writes nothing, so dropping the cache is only an extra read.
177
+ invalidate() {
178
+ snapshot = null;
179
+ expiresAt = 0;
180
+ },
181
+ };
182
+ }
183
+
184
+ function findSetting(rows, settingId) {
185
+ for (const category of rows) {
186
+ const settings = category && Array.isArray(category.settings) ? category.settings : [];
187
+ for (const setting of settings) {
188
+ if (setting && setting.id === settingId) return setting;
189
+ }
190
+ }
191
+ return null;
192
+ }
193
+
194
+ function findOption(rows, settingId, optionId) {
195
+ const setting = findSetting(rows, settingId);
196
+ const options = setting && Array.isArray(setting.options) ? setting.options : [];
197
+ for (const option of options) {
198
+ if (option && option.id === optionId) return option;
199
+ }
200
+ return null;
201
+ }
202
+
203
+ // The option ids in the model's own order: this is what makes one row per value,
204
+ // with the structural ids the panel and the fallback menu already apply.
205
+ function optionIds(rows, settingId) {
206
+ const setting = findSetting(rows, settingId);
207
+ const options = setting && Array.isArray(setting.options) ? setting.options : [];
208
+ return options
209
+ .filter((option) => option && typeof option.id === "string")
210
+ .map((option) => option.id);
211
+ }
212
+
213
+ // The stored value, read from the snapshot. An option the model no longer lists
214
+ // (or a state the model could not read, which marks NO option current) is never
215
+ // a guess.
216
+ function isCurrent(rows, settingId, optionId) {
217
+ const option = findOption(rows, settingId, optionId);
218
+ return option !== null && option.current === true;
219
+ }
220
+
221
+ // S3: the picker is only available while the stored sync is off. A store the
222
+ // model could not read is not "sync on", so it hides nothing.
223
+ function themeSyncOn(rows) {
224
+ return isCurrent(rows, "theme-sync", "on");
225
+ }
226
+
227
+ // The word the host prints for one value. The model's own label is reused
228
+ // (`On`, `Off`, the theme's name); the unassign entry keeps the extension's
229
+ // sentinel text instead of the panel's short `None`, because the bridge page has
230
+ // no note line to explain it.
231
+ function valueText(option, optionId) {
232
+ if (option && typeof option.label === "string" && option.label.length > 0) return option.label;
233
+ if (optionId.startsWith(THEME_OPTION_PREFIX)) return optionId.slice(THEME_OPTION_PREFIX.length);
234
+ return optionId;
235
+ }
236
+
237
+ // S6's swatch and every static sample: resolved from the model's optional
238
+ // preview source, so the page paints what the panel paints without carrying a
239
+ // copy of one text. The model may carry the read-only `{ title, sample }` pair or
240
+ // the factory that produces it. Anything unreadable — a throw, a missing source,
241
+ // a pair of the wrong shape — answers `undefined`, which the host paints as
242
+ // `Preview unavailable` instead of the row ever breaking.
243
+ //
244
+ // The panel's per-setting `note` (an unreadable state, a theme catalogue Pi
245
+ // cannot list) rides HERE, live, as the tail of the preview title — never as
246
+ // `choice.hint`. The host gives a hint precedence over the preview title
247
+ // (`lib/visual-customize-view.ts:745`), and the bridge types `hint` as a plain
248
+ // string that cannot be re-read, so a hint taken at build time could outlive the
249
+ // state it describes: after the user repaired an unreadable store by turning the
250
+ // sync on, the mounted row still read `Theme sync — state unknown; Enter turns
251
+ // the sync on` and hid the correct sample. A note inside the preview title is
252
+ // re-read with the rest of the snapshot, so the row can never print a fact that
253
+ // is no longer true — and the title keeps naming the sample while it does.
254
+ function optionPreview(rows, settingId, optionId) {
255
+ const option = findOption(rows, settingId, optionId);
256
+ if (!option) return undefined;
257
+ let value = option.preview;
258
+ if (typeof value === "function") {
259
+ try {
260
+ value = value();
261
+ } catch {
262
+ return undefined;
263
+ }
264
+ }
265
+ if (!value || typeof value !== "object") return undefined;
266
+ const { title, sample } = value;
267
+ if (typeof title !== "string" || typeof sample !== "string") return undefined;
268
+ const setting = findSetting(rows, settingId);
269
+ const note = setting && typeof setting.note === "string" ? setting.note : "";
270
+ return note.length > 0 ? { title: `${title} · ${note}`, sample } : { title, sample };
271
+ }
272
+
273
+ // The one write a row can cause. `apply` is the extension's injected async
274
+ // function (the `{ settingId, optionId }` shape `applyCustomizePanel` accepts)
275
+ // and it is awaited with the row's own setting and option and NOTHING else: the
276
+ // inline helpers the host hands to `action` are not forwarded, so a row cannot
277
+ // open a dialog the apply path does not own. A rejection is never caught here —
278
+ // the bridge turns a throw into the user-visible refusal and records it, so
279
+ // swallowing it (or notifying) would hide the only channel the user has. The
280
+ // cache is dropped in `finally`, because the host's repaint of the SAME rows
281
+ // follows either way.
282
+ async function dispatch(cache, apply, settingId, optionId) {
283
+ try {
284
+ await apply({ settingId, optionId });
285
+ } finally {
286
+ cache.invalidate();
287
+ }
288
+ }
289
+
290
+ function toggleRow(cache, apply, setting, optionId) {
291
+ const snapshot = cache.read();
292
+ const option = findOption(snapshot, setting.id, optionId);
293
+ const text = valueText(option, optionId);
294
+ return {
295
+ category: CUSTOMIZE_ROWS_CATEGORY,
296
+ // A row name, never the value word it happens to sit beside.
297
+ label: rowName(text) ?? setting.line,
298
+ choice: {
299
+ // The line's NAME, shared by every value of this setting, so the host
300
+ // draws one line and ←/→ walks its values (Enter applies: the bridge
301
+ // stages `applyOnMove: false` on every row it contributes). No `hint`: it
302
+ // would be a build-time string the host prefers over the live preview.
303
+ setting: setting.line,
304
+ value: text,
305
+ current: () => isCurrent(cache.read(), setting.id, optionId),
306
+ },
307
+ // The SAME title and sample the panel paints for this setting and value: the
308
+ // page reads the model's preview source (`lib/customize-panel.js` owns the
309
+ // texts through `CUSTOMIZE_SIDEBAR_SAMPLE_*`, `CUSTOMIZE_MOSHI_SAMPLE_*`,
310
+ // `CUSTOMIZE_SYNC_SAMPLE_*` and `CUSTOMIZE_THEME_NONE_SAMPLE`) instead of
311
+ // copying a single line of it, and it is re-read, so the sample follows the
312
+ // grown state without a rebuild.
313
+ preview: () => optionPreview(cache.read(), setting.id, optionId),
314
+ action: () => dispatch(cache, apply, setting.id, optionId),
315
+ };
316
+ }
317
+
318
+ // The unassign entry's printed text, disambiguated against the installed themes
319
+ // exactly like the command's own picker does (`themeSelectionOptions` in
320
+ // extensions/gentle-herdr-state.ts): a theme literally named
321
+ // `Off (no theme assigned)` would otherwise give the page two rows whose value
322
+ // word is identical while their option ids differ — one pins that theme, the
323
+ // other clears the pin. The suffix moves the UNASSIGN entry, never a theme: a
324
+ // theme's text is the name its row applies, so the page still shows it verbatim.
325
+ function unassignText(rows) {
326
+ const texts = [];
327
+ for (const optionId of optionIds(rows, THEME_SETTING.id)) {
328
+ if (optionId === THEME_NONE_OPTION_ID) continue;
329
+ texts.push(valueText(findOption(rows, THEME_SETTING.id, optionId), optionId));
330
+ }
331
+ let text = THEME_UNASSIGN_TEXT;
332
+ let attempt = 2;
333
+ while (texts.includes(text)) {
334
+ text = `${THEME_UNASSIGN_TEXT} ${attempt}`;
335
+ attempt += 1;
336
+ }
337
+ return text;
338
+ }
339
+
340
+ function themeRow(cache, apply, optionId, index, noneText) {
341
+ const snapshot = cache.read();
342
+ const option = findOption(snapshot, THEME_SETTING.id, optionId);
343
+ const isNone = optionId === THEME_NONE_OPTION_ID;
344
+ const text = isNone ? noneText : valueText(option, optionId);
345
+ return {
346
+ category: CUSTOMIZE_ROWS_CATEGORY,
347
+ // The unassign entry's name is its own; a theme is named after itself (its
348
+ // marks already turned into word breaks), and a name that survives as no
349
+ // word at all still gets a legal, distinguishable one — the exact theme is
350
+ // in the option id either way.
351
+ label: isNone ? THEME_UNASSIGN_LABEL : (rowName(text) ?? `Theme ${index + 1}`),
352
+ // No `hint`: the picker's unknown-state note rides in the live preview title
353
+ // (see `optionPreview`), so it can never outlive the state it describes.
354
+ choice: {
355
+ setting: THEME_SETTING.line,
356
+ value: text,
357
+ current: () => isCurrent(cache.read(), THEME_SETTING.id, optionId),
358
+ },
359
+ // The theme's own swatch, read from the model's preview source — the very
360
+ // one the panel draws for the same value.
361
+ preview: () => optionPreview(cache.read(), THEME_SETTING.id, optionId),
362
+ // Present while the sync is off, hidden while it is on — and the answer is
363
+ // re-read on every repaint, so turning the sync on hides the picker on the
364
+ // rows the host already mounted.
365
+ visible: () => !themeSyncOn(cache.read()),
366
+ action: () => dispatch(cache, apply, THEME_SETTING.id, optionId),
367
+ };
368
+ }
369
+
370
+ // The page's rows: the three switches in S1 order, then the theme picker. The
371
+ // cache starts cold, so a build is one model read; the values the host paints
372
+ // afterwards are served by it until an apply settles or the TTL runs out.
373
+ function customizeRows({ model, apply } = {}) {
374
+ const cache = createModelCache(model);
375
+ const rows = cache.read();
376
+ const built = [];
377
+ for (const setting of SETTINGS) {
378
+ for (const optionId of optionIds(rows, setting.id)) {
379
+ built.push(toggleRow(cache, apply, setting, optionId));
380
+ }
381
+ }
382
+ const noneText = unassignText(rows);
383
+ optionIds(rows, THEME_SETTING.id).forEach((optionId, index) => {
384
+ built.push(themeRow(cache, apply, optionId, index, noneText));
385
+ });
386
+ return built;
387
+ }
388
+
389
+ module.exports = {
390
+ CUSTOMIZE_ROWS_CATEGORY,
391
+ MODEL_CACHE_TTL_MS,
392
+ customizeRows,
393
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.8.1",
3
+ "version": "1.9.1",
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",