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.
@@ -2075,6 +2075,11 @@ function lastFinishedLabel(taskMap) {
2075
2075
  // unavailable. The removed `Plugin tools` and `Reset` sections and the
2076
2076
  // cross-extension provider slot are deliberately NOT restored: they switched
2077
2077
  // worktree/ODD/issues surfaces this package no longer contains.
2078
+ //
2079
+ // With gentle-shell-bridge present the same four options are ALSO served as the
2080
+ // `Herdr` page of Gentle Shell's own `/gentle:customize` menu (see
2081
+ // `registerCustomizePage` below). The page is additive: this command is
2082
+ // registered unconditionally, exactly as before, and the apply path is shared.
2078
2083
  // ---------------------------------------------------------------------------
2079
2084
 
2080
2085
  const CUSTOMIZE_TITLE = "Customize · Herdr Gentle Shell";
@@ -2106,9 +2111,27 @@ const THEME_SYNC_OFF_TEXT = "Theme sync off; Herdr keeps the palette it was last
2106
2111
  const THEME_SYNC_REFUSED_TEXT = "Turn Theme sync off to pick a specific theme.";
2107
2112
  const THEME_LIST_UNAVAILABLE_TEXT =
2108
2113
  "Could not read Pi's theme list (this host exposes no getAllThemes()); nothing was changed.";
2114
+ // The page's OWN apply-time notice, for a catalogue it could read when it built
2115
+ // its rows and cannot read now. It deliberately does not reuse the sentence
2116
+ // above: that one says the host exposes no `getAllThemes()`, which is a
2117
+ // different fact and stays untouched for the command and the panel (S2).
2118
+ const THEME_LIST_UNREADABLE_AT_APPLY_TEXT =
2119
+ "Could not read Pi's theme list at apply time; nothing was changed.";
2109
2120
  const THEME_STORE_UNAVAILABLE_TEXT =
2110
2121
  "Could not reach the theme store (lib/theme-store.js is unavailable); nothing was changed.";
2111
2122
 
2123
+ // S4 (odd/tasks/herdr-customize-page.md): `/herdr-gentle:customize` is registered
2124
+ // unconditionally (S1), so it always exists and every message that sends the user
2125
+ // back to the four options names it — byte for byte the text `865d360` shipped.
2126
+ // No string is surface-dependent: the page added beside the command changes no
2127
+ // wording, and a message never points at a menu that may be absent.
2128
+
2129
+ // The Moshi settings entry waits for the next Pi extension load. A customize ROW
2130
+ // has no reload handle (the bridge hands `action` only inline helpers), so the
2131
+ // page writes the exclusion and asks for a restart instead of promising a reload
2132
+ // it cannot perform. The command and the panel keep reloading immediately.
2133
+ const MOSHI_RESTART_TEXT = "Restart Pi so the new Moshi hook exclusion takes effect.";
2134
+
2112
2135
  // The former panel's geometry and overlay options, unchanged. The helpers
2113
2136
  // module (@earendil-works/pi-tui) is resolved lazily through the injectable
2114
2137
  // seam below so registering the extension never depends on it and tests can
@@ -2149,6 +2172,18 @@ function customizePanelModule() {
2149
2172
  }
2150
2173
  }
2151
2174
 
2175
+ // The bridge row builder (lib/customize-rows.js, odd/tasks/herdr-customize-page.md
2176
+ // T1). Loaded lazily beside the panel module and for the same reason: an
2177
+ // installed copy without the sibling library keeps every other surface working
2178
+ // and answers no page instead of failing this extension.
2179
+ function customizeRowsModule() {
2180
+ try {
2181
+ return nodeRequire(join(customizeLibDir(), "customize-rows.js"));
2182
+ } catch {
2183
+ return null;
2184
+ }
2185
+ }
2186
+
2152
2187
  function themeStoreModule() {
2153
2188
  try {
2154
2189
  return nodeRequire(join(customizeLibDir(), "theme-store.js"));
@@ -2190,6 +2225,17 @@ function readHostThemeNames(ctx) {
2190
2225
  // here: the panel is a plain CommonJS module with no host colour API, and
2191
2226
  // falling back to the active theme would show a palette the user did not pick.
2192
2227
  // An unreadable theme throws, and the panel renders `Preview unavailable`.
2228
+ //
2229
+ // The background token is `selectedBg`, NEVER `accent`: Pi's `Theme.getBgAnsi`
2230
+ // throws `Unknown theme color: accent` because `accent` is a FOREGROUND token
2231
+ // (`theme-tokens.d.ts`: `accent` has `slot: "foreground"`; only `selectedBg`,
2232
+ // `searchMatchBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`,
2233
+ // `toolSuccessBg` and `toolErrorBg` are background tokens). Pi 1.6.0's built-in
2234
+ // catalogue is `system`, `dark` and `light`, and all three answer `selectedBg`,
2235
+ // so their swatches render again; the text side stays on the `text` foreground
2236
+ // token, which the same themes answer. A theme that throws for either, or
2237
+ // answers a non-string, still throws here and both surfaces paint
2238
+ // `Preview unavailable`.
2193
2239
  function themePreviewFactory(ctx) {
2194
2240
  const getTheme = ctx?.ui?.getTheme;
2195
2241
  if (typeof getTheme !== "function") return null;
@@ -2204,13 +2250,19 @@ function themePreviewFactory(ctx) {
2204
2250
  if (typeof theme.name === "string" && theme.name !== name) {
2205
2251
  throw new Error(`Theme ${name} is unavailable.`);
2206
2252
  }
2207
- const accent = typeof theme.getBgAnsi === "function" ? theme.getBgAnsi("accent") : undefined;
2253
+ const background = typeof theme.getBgAnsi === "function" ? theme.getBgAnsi("selectedBg") : undefined;
2208
2254
  const text = typeof theme.getFgAnsi === "function" ? theme.getFgAnsi("text") : undefined;
2209
- if (typeof accent !== "string" || typeof text !== "string") {
2255
+ if (typeof background !== "string" || typeof text !== "string") {
2210
2256
  throw new Error(`Theme ${name} exposes no palette escapes.`);
2211
2257
  }
2212
- // The upstream sample: a background block then the sample text.
2213
- return { title: "source palette", sample: `${accent} \x1b[0m ${text}Aa sample text\x1b[0m` };
2258
+ // The upstream sample: a background block then the sample text. The words are
2259
+ // painted OVER the theme's own background — no reset between the chip and
2260
+ // them — because that is the pairing every theme is designed to keep
2261
+ // readable. A reset there dropped the words onto the user's AMBIENT terminal
2262
+ // background (the verifier measured 1.62:1 for `light` on a #141414 terminal
2263
+ // and 1.22:1 for `dark` on #fafafa). `system` keeps working: its `selectedBg`
2264
+ // is the terminal's default background and its `text` the default foreground.
2265
+ return { title: "source palette", sample: `${background} ${text}Aa sample text\x1b[0m` };
2214
2266
  };
2215
2267
  }
2216
2268
 
@@ -2624,13 +2676,19 @@ async function applyCustomizeSwitch(id, value, ctx, options = {}) {
2624
2676
  ? applyThemeSync(want)
2625
2677
  : applyMoshiNotifications(want);
2626
2678
  const notify = ctx?.ui?.notify;
2627
- if (typeof notify === "function") {
2628
- notify(`${result.text}${result.needsReload ? " Reloading now to apply the change." : ""}`, result.level);
2629
- }
2630
- // The overlay defers the reload (`deferReload`): reloading while the card is
2631
- // still mounted restarts Pi behind an open overlay, so the panel closes first
2632
- // and the caller reloads after `ctx.ui.custom` resolved.
2633
- if (result.needsReload && options.deferReload !== true && typeof ctx?.reload === "function") await ctx.reload();
2679
+ // The reload sentence is a PROMISE about what happens next, so it is written
2680
+ // from what this surface can actually do. `deferReload` hands the reload to the
2681
+ // caller that mounted the overlay (the card closes first, then it reloads), and
2682
+ // `noReload` is the Gentle Shell customize page, where a row action receives no
2683
+ // ctx and therefore no reload handle: there the only honest sentence is a
2684
+ // restart. Every other combination is the command's own immediate reload.
2685
+ const canReload = options.deferReload !== true && options.noReload !== true
2686
+ && typeof ctx?.reload === "function";
2687
+ const reloadNotice = result.needsReload
2688
+ ? (options.noReload === true ? ` ${MOSHI_RESTART_TEXT}` : " Reloading now to apply the change.")
2689
+ : "";
2690
+ if (typeof notify === "function") notify(`${result.text}${reloadNotice}`, result.level);
2691
+ if (result.needsReload && canReload) await ctx.reload();
2634
2692
  return result;
2635
2693
  }
2636
2694
 
@@ -2712,10 +2770,36 @@ function themeSelectionOptions(names) {
2712
2770
  return { options: [...names, unassign], unassign };
2713
2771
  }
2714
2772
 
2715
- // One write for the pinned theme, shared by the inline panel setting and the
2716
- // `ctx.ui.select` fallback: the refusal, the missing store and a failure all
2717
- // write NOTHING, so the stored document only ever changes to a value the user
2718
- // actually picked (S7).
2773
+ // T10 (odd/tasks/herdr-customize-page.md): a surface that holds its own rows can
2774
+ // outlive the catalogue it built them from. Only the Herdr PAGE does: it keeps
2775
+ // one row per theme for as long as Gentle Shell shows the menu, while the
2776
+ // command's picker reads `getAllThemes()` when it prompts and the mounted panel
2777
+ // keeps the 865d360 write. The guard therefore lives on the page's apply path (`applyCustomizePageChoice`), never in the write the command and the
2778
+ // panel share (S2).
2779
+ //
2780
+ // The wording is the notice the theme sync already gives for a stored name this
2781
+ // install does not have (`extensions/herdr-theme-sync.ts`, S4): one sentence for
2782
+ // one fact, spelled once. A catalogue that cannot be read at all gets the page's
2783
+ // own apply-time sentence, because a name nothing verified is never written.
2784
+ function themeNotInstalledText(name) {
2785
+ return `The Pi theme "${name}" is not installed, so Herdr's palette was left unchanged; pick an installed theme in /herdr-gentle:customize.`;
2786
+ }
2787
+
2788
+ // A FRESH read, never the page's row cache: `readHostThemeNames` calls the host
2789
+ // accessor again on every call, so the answer describes the install as it is at
2790
+ // APPLY time.
2791
+ function themeStillInstalled(ctx, name) {
2792
+ const names = readHostThemeNames(ctx);
2793
+ if (names === null) return { ok: false, text: THEME_LIST_UNREADABLE_AT_APPLY_TEXT };
2794
+ return names.includes(name) ? { ok: true, text: null } : { ok: false, text: themeNotInstalledText(name) };
2795
+ }
2796
+
2797
+ // One write for the pinned theme, shared by the inline panel setting, the Herdr
2798
+ // page rows and the `ctx.ui.select` fallback: the refusal, the missing store and
2799
+ // a failure all write NOTHING, so the stored document only ever changes to a
2800
+ // value the user actually picked (S7). No catalogue check lives here: the
2801
+ // command's picker cannot outlive its catalogue, and the page's own guard runs
2802
+ // before this call (T10), so neither surface can inherit a new refusal.
2719
2803
  function writeThemeChoice(ctx, name) {
2720
2804
  const notify = ctx?.ui?.notify;
2721
2805
  const store = themeStoreModule();
@@ -2814,7 +2898,7 @@ async function applyCustomizeChoice(choice, ctx) {
2814
2898
  // uses, and answers with a freshly read model so the panel shows the real state
2815
2899
  // instead of guessing it. `close` is only true when Pi must reload: the caller
2816
2900
  // closes the overlay first and reloads after it resolved.
2817
- async function applyCustomizePanel(choice, ctx) {
2901
+ async function applyCustomizePanel(choice, ctx, options = {}) {
2818
2902
  const model = () => customizePanelModel(ctx);
2819
2903
  if (!isRecord(choice)) return { model: model(), close: false, reload: false };
2820
2904
  const { settingId, optionId } = choice;
@@ -2827,7 +2911,12 @@ async function applyCustomizePanel(choice, ctx) {
2827
2911
  }
2828
2912
  if (!CUSTOMIZE_SWITCH_IDS.includes(settingId)) return { model: model(), close: false, reload: false };
2829
2913
  if (optionId !== "on" && optionId !== "off") return { model: model(), close: false, reload: false };
2830
- const result = await applyCustomizeSwitch(settingId, optionId, ctx, { deferReload: true });
2914
+ const result = await applyCustomizeSwitch(
2915
+ settingId,
2916
+ optionId,
2917
+ ctx,
2918
+ options.noReload === true ? { noReload: true } : { deferReload: true },
2919
+ );
2831
2920
  const reload = Boolean(result && result.needsReload);
2832
2921
  return { model: model(), close: reload, reload };
2833
2922
  }
@@ -2873,7 +2962,7 @@ async function runCustomizeFallback(ctx) {
2873
2962
  : (moshiFlagEnabled(moshiFlagPath()) ? "on" : "off");
2874
2963
  let choice = null;
2875
2964
  try {
2876
- choice = await select(`${picked} (currently ${current})`, [CUSTOMIZE_ON, CUSTOMIZE_OFF]);
2965
+ choice = await select(`${picked} (currently ${current})`, [CUSTOMIZE_OFF, CUSTOMIZE_ON]);
2877
2966
  } catch {
2878
2967
  choice = undefined;
2879
2968
  }
@@ -2964,9 +3053,200 @@ async function executeCustomize(rawArgs, ctx) {
2964
3053
  await runCustomizeFallback(ctx);
2965
3054
  }
2966
3055
 
3056
+ // ---------------------------------------------------------------------------
3057
+ // The Gentle Shell customize PAGE (odd/tasks/herdr-customize-page.md T7;
3058
+ // specs S1, S2, S4).
3059
+ //
3060
+ // `/herdr-gentle:customize` is registered in the FACTORY, unconditionally, exactly
3061
+ // as on `865d360`. This section ADDS a second surface on top of it: when
3062
+ // gentle-shell-bridge answers its handshake, the same four switches also appear as
3063
+ // the `Herdr` page of Gentle Shell's own `/gentle:customize` menu. The page never
3064
+ // replaces the command — two surfaces coexisting is by design, because Pi gives an
3065
+ // extension no way to withdraw a registered command and a bridge with no host menu
3066
+ // must never leave the user with none.
3067
+ //
3068
+ // The bridge is reached as a HANDSHAKE, never a dependency: its object sits at a
3069
+ // `Symbol.for` key on `globalThis`, and the key, the schema and the members this
3070
+ // file calls are inlined here, so nothing resolves `gentle-shell-bridge` as a
3071
+ // module (`examples/bash-card.ts:1214-1244` in that package is the same pattern).
3072
+ //
3073
+ // WHEN the page appears. `session_start` asks the symbol; when it is absent the
3074
+ // page cannot be built yet, so the factory has already subscribed to
3075
+ // `BRIDGE_READY_EVENT` and the announce asks again. That covers Pi's load order,
3076
+ // which does not guarantee that a configured package's module publishes before a
3077
+ // global extension's `session_start`: a late bridge still produces the page. The
3078
+ // announce is a notification, never a registry — the symbol stays the authority,
3079
+ // so a copy that publishes an incompatible slot announces nothing usable and the
3080
+ // gate below answers ABSENT.
3081
+ //
3082
+ // ONE provider, never two. Registration is guarded by the live provider itself, so
3083
+ // a second `session_start`, an announce after a start and a repeated announce all
3084
+ // leave exactly one registration; the bridge's bus is never asked twice. The
3085
+ // provider is session-scoped and the command is not: only the provider is disposed
3086
+ // on session shutdown.
3087
+ // ---------------------------------------------------------------------------
3088
+ const BRIDGE_API_KEY = Symbol.for("gentle-shell-bridge/api/v1");
3089
+ const BRIDGE_API_SCHEMA = "gentle-shell-bridge/api";
3090
+ const BRIDGE_API_VERSION = 1;
3091
+ // The channel the bridge announces itself on. The string MIRRORS `src/api.ts`:
3092
+ // this file cannot import it, so the two are kept in sync by hand.
3093
+ const BRIDGE_READY_EVENT = "gentle-shell-bridge:ready";
3094
+ // The provider's stable id: the bridge replaces a provider registered under the
3095
+ // same id in place, so one page is one page however often it is registered.
3096
+ const CUSTOMIZE_PAGE_PROVIDER_ID = "herdr-gentle:customize";
3097
+
3098
+ // The published object, gated exactly like the bridge's own `isBridgeApi`
3099
+ // (`src/api.ts`): identity strings plus the members this file calls. A foreign
3100
+ // payload, another major version or a partial object is ABSENT — never an error,
3101
+ // never guessed at, never overwritten.
3102
+ function publishedBridge() {
3103
+ const slot = globalThis[BRIDGE_API_KEY];
3104
+ if (!isRecord(slot)) return null;
3105
+ if (slot.schema !== BRIDGE_API_SCHEMA || slot.version !== BRIDGE_API_VERSION) return null;
3106
+ if (typeof slot.registerRows !== "function") return null;
3107
+ if (typeof slot.registerSection !== "function" || typeof slot.createStore !== "function") return null;
3108
+ return slot;
3109
+ }
3110
+
3111
+ // A row's apply path — and it IS the overlay's own path (`applyCustomizePanel`),
3112
+ // not a copy: the same `writeThemeChoice` for the pinned theme, the same
3113
+ // `applyCustomizeSwitch` for the three switched settings, and therefore the same
3114
+ // Moshi prerequisite gate and the same "a refusal writes nothing" promise by
3115
+ // construction. It adds the two facts the overlay does not need: a row action
3116
+ // receives no ctx, so the page has no reload handle and the shared path reports a
3117
+ // restart instead of reloading (see `applyCustomizeSwitch`), and the page's rows
3118
+ // outlive the theme catalogue they were built from (T10).
3119
+ //
3120
+ // The catalogue guard lives HERE, on the page's own call site, and not in the
3121
+ // shared write: the command's picker and the mounted panel keep the 865d360
3122
+ // behavior byte for byte (S2), and no other surface can be affected by
3123
+ // construction. A name removed after the build is refused with the not-installed
3124
+ // notice and writes nothing; a catalogue that cannot be read at apply time gets
3125
+ // the page's own honest sentence and also writes nothing.
3126
+ //
3127
+ // A refusal is NOT re-thrown: the shared path reports it through the host's own
3128
+ // `ui.notify` and returns, which is one report — the same one the command gives.
3129
+ // Throwing on top of that would report it twice (the bridge reports a thrown
3130
+ // action again), so only an unexpected exception travels into the bridge's
3131
+ // channel.
3132
+ async function applyCustomizePageChoice(choice, ctx) {
3133
+ if (isRecord(choice) && choice.settingId === CUSTOMIZE_THEME_SETTING_ID) {
3134
+ const optionId = choice.optionId;
3135
+ // The sync gate answers FIRST, exactly as it does on every other surface.
3136
+ // While sync is on the pinned theme is not available at all, so asking the
3137
+ // catalogue whether the theme still exists would answer a question the row
3138
+ // cannot act on and would bury the one thing the user has to do first.
3139
+ const syncOn = readCustomizeThemeState().sync === true;
3140
+ if (!syncOn && typeof optionId === "string" && optionId.startsWith(CUSTOMIZE_THEME_OPTION_PREFIX)) {
3141
+ const installed = themeStillInstalled(ctx, optionId.slice(CUSTOMIZE_THEME_OPTION_PREFIX.length));
3142
+ if (!installed.ok) {
3143
+ const notify = ctx?.ui?.notify;
3144
+ if (typeof notify === "function") notify(installed.text, "warning");
3145
+ return { model: customizePanelModel(ctx), close: false, reload: false };
3146
+ }
3147
+ }
3148
+ }
3149
+ return applyCustomizePanel(choice, ctx, { noReload: true });
3150
+ }
3151
+
3152
+ // The one provider this extension contributes: the `Herdr` page (a row
3153
+ // CATEGORY, never `registerSection`, which is a sidebar card). `rows()` is called
3154
+ // on every menu build, so the model — and every `current()`, swatch and sync gate
3155
+ // inside it — is read live rather than captured at registration.
3156
+ function customizePageProvider(rowsModule, hostCtx) {
3157
+ return {
3158
+ id: CUSTOMIZE_PAGE_PROVIDER_ID,
3159
+ category: rowsModule.CUSTOMIZE_ROWS_CATEGORY,
3160
+ rows() {
3161
+ const ctx = hostCtx();
3162
+ // No session ctx means no theme catalogue and no notify channel; an empty
3163
+ // page is the honest answer, and `customizeRows` answers no rows for a
3164
+ // model it cannot read anyway.
3165
+ if (!ctx) return [];
3166
+ return rowsModule.customizeRows({
3167
+ model: () => customizePanelModel(ctx),
3168
+ apply: (choice) => applyCustomizePageChoice(choice, ctx),
3169
+ });
3170
+ },
3171
+ };
3172
+ }
3173
+
3174
+ // The Gentle Shell customize page as a REGISTRATION LIFECYCLE, bound by the
3175
+ // factory beside the command (which is registered there too, unconditionally).
3176
+ // Additive by construction: nothing here can unregister or shadow the command.
3177
+ function registerCustomizePage(pi) {
3178
+ let pageContext = null;
3179
+ let disposePage = null;
3180
+
3181
+ function clearPage() {
3182
+ const dispose = disposePage;
3183
+ disposePage = null;
3184
+ if (typeof dispose !== "function") return;
3185
+ try {
3186
+ dispose();
3187
+ } catch {
3188
+ // The bridge owns its own bus: a disposer that fails cannot make this file
3189
+ // host a second page, so the failure is contained here.
3190
+ }
3191
+ }
3192
+
3193
+ // The one registration path `session_start` and the announce both use, so an
3194
+ // announce and a later session cannot both register and a repeated announce
3195
+ // cannot stack a second provider. A live provider IS the guard: re-registering
3196
+ // would only ask the bus to replace an identical entry.
3197
+ function registerPage() {
3198
+ if (disposePage !== null) return;
3199
+ // No session yet: `session_start` asks again once there is a ctx to build the
3200
+ // model from.
3201
+ if (!pageContext) return;
3202
+ const bridge = publishedBridge();
3203
+ // S2: nothing answered the handshake, so today's command stands alone.
3204
+ if (!bridge) return;
3205
+ const rowsModule = customizeRowsModule();
3206
+ // An install without the sibling lib/ has no page to offer; the command and
3207
+ // every other surface keep working.
3208
+ if (!rowsModule) return;
3209
+ let dispose = null;
3210
+ try {
3211
+ dispose = bridge.registerRows(customizePageProvider(rowsModule, () => pageContext));
3212
+ } catch {
3213
+ // A bus that refuses the provider (a host with no customize menu asks for
3214
+ // nothing else): the command is already registered, so no surface is lost.
3215
+ dispose = null;
3216
+ }
3217
+ if (typeof dispose === "function") disposePage = dispose;
3218
+ }
3219
+
3220
+ // The symbol first: when the bridge is already published there is nothing to
3221
+ // wait for and no listener is taken. Otherwise the announce is the only way a
3222
+ // bridge that loads AFTER this extension is ever heard.
3223
+ const events = pi?.events;
3224
+ if (events && typeof events.on === "function" && !publishedBridge()) {
3225
+ try {
3226
+ events.on(BRIDGE_READY_EVENT, registerPage);
3227
+ } catch {
3228
+ // No bus and no ready event: `session_start` still tries the symbol.
3229
+ }
3230
+ }
3231
+
3232
+ pi.on("session_start", (_event, ctx) => {
3233
+ pageContext = isRecord(ctx) ? ctx : null;
3234
+ registerPage();
3235
+ });
3236
+
3237
+ pi.on("session_shutdown", () => {
3238
+ // The bridge's bus outlives the session, so only the provider is dropped:
3239
+ // the command stays as registered, and the next session adds one page again
3240
+ // instead of stacking a second one.
3241
+ clearPage();
3242
+ pageContext = null;
3243
+ });
3244
+ }
3245
+
2967
3246
  export default function (pi) {
2968
3247
  // Registered before the pane gate on purpose: the switches are local state and
2969
- // must stay reachable from a plain Pi session outside a Herdr pane.
3248
+ // must stay reachable from a plain Pi session outside a Herdr pane. S1: this is
3249
+ // unconditional — the page below is additive, never a replacement.
2970
3250
  if (typeof pi?.registerCommand === "function") {
2971
3251
  pi.registerCommand("herdr-gentle:customize", {
2972
3252
  description: "Customize Herdr Gentle Shell: sidebar agent rows, Moshi notifications and the Herdr theme",
@@ -2975,6 +3255,7 @@ export default function (pi) {
2975
3255
  },
2976
3256
  });
2977
3257
  }
3258
+ registerCustomizePage(pi);
2978
3259
  if (!enabled()) return;
2979
3260
 
2980
3261
  let rootSession = false;
@@ -292,6 +292,10 @@ export default function (pi) {
292
292
  seen.missingTheme = true;
293
293
  notify(
294
294
  ctx,
295
+ // S4 (odd/tasks/herdr-customize-page.md): `/herdr-gentle:customize`
296
+ // is registered unconditionally, so it is the one surface this notice
297
+ // can name — the Herdr page of Gentle Shell's customize menu sits
298
+ // beside it, never instead of it.
295
299
  `The Pi theme "${chosen}" is not installed, so Herdr's palette was left unchanged; pick an installed theme in /herdr-gentle:customize.`,
296
300
  );
297
301
  }
@@ -173,9 +173,11 @@ const CUSTOMIZE_OPTION_GAP = " ";
173
173
  // The pointer hint lives in the footer exactly like upstream's `Click · …`.
174
174
  const CUSTOMIZE_CLICK_PREFIX = "Click · ";
175
175
 
176
- // The three settings this package owns, with the upstream order of their two
177
- // options and the static preview each option carries. `id` is the apply target
178
- // the extension knows; it is structural, never the label.
176
+ // The three settings this package owns, with the ONE value order every switch
177
+ // reads — Off on the left, On on the right — and the static preview each option
178
+ // carries (the On sample follows On, whichever side it sits on). `id` is the
179
+ // apply target the extension knows; it is structural, never the label, and no
180
+ // option is ever identified by its position: the ids are always `on` and `off`.
179
181
  const CUSTOMIZE_SIDEBAR_SAMPLE_ON = "● project gentle worker";
180
182
  const CUSTOMIZE_SIDEBAR_SAMPLE_OFF = "native Herdr rows; no managed block";
181
183
  const CUSTOMIZE_MOSHI_SAMPLE_ON = "ask finished";
@@ -188,7 +190,7 @@ const CUSTOMIZE_TOGGLES = Object.freeze({
188
190
  sidebar: {
189
191
  id: "sidebar",
190
192
  setting: "Sidebar agent rows",
191
- order: ["on", "off"],
193
+ order: ["off", "on"],
192
194
  // S5: the sample shows what the managed rows add, from the README's own
193
195
  // description of the heading cell and the role words.
194
196
  preview: (which) => ({
@@ -200,7 +202,7 @@ const CUSTOMIZE_TOGGLES = Object.freeze({
200
202
  moshi: {
201
203
  id: "moshi",
202
204
  setting: "Notifications",
203
- order: ["on", "off"],
205
+ order: ["off", "on"],
204
206
  preview: (which) => ({
205
207
  title: "static notification sample",
206
208
  sample: which === "on" ? CUSTOMIZE_MOSHI_SAMPLE_ON : CUSTOMIZE_MOSHI_SAMPLE_OFF,
@@ -228,7 +230,6 @@ const CUSTOMIZE_THEME_NONE_ID = "none";
228
230
  const CUSTOMIZE_THEME_NONE_LABEL = "None";
229
231
  const CUSTOMIZE_THEME_OPTION_PREFIX = "theme:";
230
232
  const CUSTOMIZE_THEME_UNAVAILABLE_NOTE = "Themes unavailable; use Pi /settings";
231
- const CUSTOMIZE_THEME_DISABLED_NOTE = "Turn Theme sync off to pick a specific theme.";
232
233
  const CUSTOMIZE_THEME_UNKNOWN_NOTE = "state unknown; Enter pins a theme";
233
234
 
234
235
  // The key legend is ONE terminal row: the `key` spelling paints as the key
@@ -449,9 +450,13 @@ function customizeToggleSetting(definition, stored) {
449
450
  }
450
451
 
451
452
  // The one setting that is not a boolean: `None` plus one option per installed
452
- // theme, in Pi's own order. Its options are disabled (still selectable) only
453
- // while the stored sync is on, and an unavailable theme list shows one note
454
- // with no options at all instead of an empty list that looks pickable.
453
+ // theme, in Pi's own order. While the stored sync is on the setting is marked
454
+ // `disabled`, which is how the model says the pinned theme is not available; the
455
+ // PANEL never offers such a setting at all (see `customizeOfferedSettings`), so
456
+ // there is nothing to explain there, while the Gentle Shell page keeps its
457
+ // mounted rows and hides them with `visible()` so the picker returns in place
458
+ // when the sync is turned off. An unavailable theme list shows one note with no
459
+ // options at all instead of an empty list that looks pickable.
455
460
  function customizeThemeSetting(themeState, themeNames, themePreview) {
456
461
  const readable = themeState.ok !== false;
457
462
  const syncOn = readable && themeState.sync === true;
@@ -475,7 +480,6 @@ function customizeThemeSetting(themeState, themeNames, themePreview) {
475
480
  : [];
476
481
  const notes = [];
477
482
  if (!readable) notes.push(CUSTOMIZE_THEME_UNKNOWN_NOTE);
478
- else if (syncOn) notes.push(CUSTOMIZE_THEME_DISABLED_NOTE);
479
483
  if (!listed) notes.push(CUSTOMIZE_THEME_UNAVAILABLE_NOTE);
480
484
  return {
481
485
  id: CUSTOMIZE_THEME_SETTING_ID,
@@ -523,6 +527,19 @@ function customizePanelModel({ sidebar, moshi, theme, themeNames, themePreview }
523
527
  ];
524
528
  }
525
529
 
530
+ // The settings a surface OFFERS: a setting the model marks `disabled` is absent,
531
+ // not dim and not refusing, because the honest answer to "the pinned theme is
532
+ // only available while the sync is off" is to not offer the picker at all — the
533
+ // Gentle Shell page already hides its theme rows that way (`lib/customize-rows.js`
534
+ // `visible()`), and the panel must not offer what the page hides. The model keeps
535
+ // the setting (the page's mounted rows need it to come back in place), so the
536
+ // gate is applied HERE, on every read: the same panel answers a new model after an
537
+ // apply settles, which is how the setting returns without closing and reopening.
538
+ function customizeOfferedSettings(settings) {
539
+ const list = Array.isArray(settings) ? settings : [];
540
+ return list.filter((setting) => !(setting && setting.disabled === true));
541
+ }
542
+
526
543
  /* ---------------------------------------------------------- setting line */
527
544
 
528
545
  // One setting line: the name column, then every option inline. `●` is the
@@ -665,7 +682,7 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model: i
665
682
  };
666
683
  function settings() {
667
684
  const category = state.model[state.cat];
668
- return category && Array.isArray(category.settings) ? category.settings : [];
685
+ return customizeOfferedSettings(category && category.settings);
669
686
  }
670
687
  function settingIndex() {
671
688
  const at = settings().findIndex((entry) => entry.id === state.settingId);
@@ -674,11 +691,17 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model: i
674
691
  function focusedSetting() {
675
692
  return settings()[settingIndex()] || null;
676
693
  }
677
- // A setting is entered on its stored option (upstream `landOn`); an unknown
678
- // state has no stored option, so it enters on the first one.
694
+ // A setting is entered on its stored option (upstream `landOn`). An unknown
695
+ // state has no stored option, and every note that explains an unknown state
696
+ // here promises the same thing — `Enter turns the rows on`, `Enter turns the
697
+ // sync on` — so the fallback is the `on` option BY ID. Position 0 is Off now,
698
+ // and landing there would make the panel's own note a lie.
679
699
  function landOn(setting) {
680
- const at = setting && Array.isArray(setting.options) ? setting.options.findIndex((option) => option.current === true) : -1;
681
- return at < 0 ? 0 : at;
700
+ const options = setting && Array.isArray(setting.options) ? setting.options : [];
701
+ const current = options.findIndex((option) => option.current === true);
702
+ if (current >= 0) return current;
703
+ const on = options.findIndex((option) => option.id === "on");
704
+ return on >= 0 ? on : 0;
682
705
  }
683
706
  function cursorIndex(setting) {
684
707
  if (!setting || !Array.isArray(setting.options)) return 0;
@@ -766,7 +789,7 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model: i
766
789
  const chrome = 1 + (showHeading ? 2 : 0) + (showTopGap ? 1 : 0) + (showBottomGap ? 1 : 0);
767
790
  const contentHeight = Math.max(1, height - 2 - chrome - previewLines);
768
791
  const category = state.model[state.cat] || { id: null, title: "Settings", settings: [] };
769
- const entries = category.settings || [];
792
+ const entries = customizeOfferedSettings(category.settings);
770
793
  const focusedAt = settingIndex();
771
794
  // Right pane rows: one line per setting plus, when the state cannot name a
772
795
  // value, one muted note under it.
@@ -780,9 +803,15 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model: i
780
803
  const listLength = navOnly ? state.model.length : rightLines.length;
781
804
  const start = Math.min(Math.max(0, position - contentHeight + 1), Math.max(0, listLength - contentHeight));
782
805
  const navStart = Math.min(Math.max(0, state.cat - contentHeight + 1), Math.max(0, state.model.length - contentHeight));
806
+ // The label column is sized from the category's FULL setting set, offered or
807
+ // not (D2): a setting the theme gate withholds must not move the values of
808
+ // the settings that remain. The column is a property of the category, not of
809
+ // what happens to be offered in this frame — with the sync off the widest
810
+ // label is `Gentle Shell theme`, and the same width is kept when it is gone.
811
+ const allSettings = Array.isArray(category.settings) ? category.settings : [];
783
812
  const nameWidth = Math.min(
784
813
  20,
785
- entries.reduce((need, setting) => Math.max(need, customizeMeasure(helpers, setting.setting)), 0),
814
+ allSettings.reduce((need, setting) => Math.max(need, customizeMeasure(helpers, setting.setting)), 0),
786
815
  );
787
816
  const paintCell = (text, size, kind) => customizePaint(helpers, theme, kind, text, size);
788
817
  const compose = (segments, size) => customizeCompose(helpers, theme, segments, size);