herdr-gentle-shell 1.8.0 → 1.9.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.
@@ -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";
@@ -2092,10 +2097,13 @@ const CUSTOMIZE_OFF = "Off";
2092
2097
  // unpinnable, because selecting it would read as "clear the pin".
2093
2098
  const CUSTOMIZE_THEME_UNASSIGN = "Off (no theme assigned)";
2094
2099
 
2095
- // The row id `lib/customize-panel.js` gives the theme value row. It is not an
2096
- // On/Off pair: the row opens the host's theme list, so the apply path keys the
2097
- // list on this id instead of on a value it could toggle.
2098
- const CUSTOMIZE_THEME_SELECT_ROW_ID = "select";
2100
+ // The theme setting's STRUCTURAL option ids from `lib/customize-panel.js`. They
2101
+ // are never labels: `none` is the "no theme assigned" choice and `theme:<name>`
2102
+ // a real theme, so an installed theme literally called `None` or `Off` keeps its
2103
+ // own option and stays pinnable.
2104
+ const CUSTOMIZE_THEME_SETTING_ID = "theme";
2105
+ const CUSTOMIZE_THEME_NONE_OPTION_ID = "none";
2106
+ const CUSTOMIZE_THEME_OPTION_PREFIX = "theme:";
2099
2107
  const THEME_SYNC_ON_TEXT = "Theme sync on; Herdr's palette follows the theme active in Pi.";
2100
2108
  const THEME_SYNC_OFF_TEXT = "Theme sync off; Herdr keeps the palette it was last given.";
2101
2109
  // The refusal keeps S4's promise: the pinned theme is only available while the
@@ -2103,9 +2111,27 @@ const THEME_SYNC_OFF_TEXT = "Theme sync off; Herdr keeps the palette it was last
2103
2111
  const THEME_SYNC_REFUSED_TEXT = "Turn Theme sync off to pick a specific theme.";
2104
2112
  const THEME_LIST_UNAVAILABLE_TEXT =
2105
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.";
2106
2120
  const THEME_STORE_UNAVAILABLE_TEXT =
2107
2121
  "Could not reach the theme store (lib/theme-store.js is unavailable); nothing was changed.";
2108
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
+
2109
2135
  // The former panel's geometry and overlay options, unchanged. The helpers
2110
2136
  // module (@earendil-works/pi-tui) is resolved lazily through the injectable
2111
2137
  // seam below so registering the extension never depends on it and tests can
@@ -2146,6 +2172,18 @@ function customizePanelModule() {
2146
2172
  }
2147
2173
  }
2148
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
+
2149
2187
  function themeStoreModule() {
2150
2188
  try {
2151
2189
  return nodeRequire(join(customizeLibDir(), "theme-store.js"));
@@ -2169,13 +2207,57 @@ function readCustomizeThemeState() {
2169
2207
  }
2170
2208
  }
2171
2209
 
2172
- function customizePanelModel() {
2210
+ // S2: the panel lists Pi's own themes, so the extension reads them from the
2211
+ // host instead of shipping a copy. `null` means "this host exposes no list" and
2212
+ // the panel says so with one note instead of showing an empty picker.
2213
+ function readHostThemeNames(ctx) {
2214
+ const listThemes = ctx?.ui?.getAllThemes;
2215
+ if (typeof listThemes !== "function") return null;
2216
+ try {
2217
+ return themeNames(listThemes.call(ctx.ui));
2218
+ } catch {
2219
+ return null;
2220
+ }
2221
+ }
2222
+
2223
+ // S6: a theme's preview is a swatch in THAT theme's colours, taken from the
2224
+ // theme object the host hands back. The raw SGR is deliberate and lives only
2225
+ // here: the panel is a plain CommonJS module with no host colour API, and
2226
+ // falling back to the active theme would show a palette the user did not pick.
2227
+ // An unreadable theme throws, and the panel renders `Preview unavailable`.
2228
+ function themePreviewFactory(ctx) {
2229
+ const getTheme = ctx?.ui?.getTheme;
2230
+ if (typeof getTheme !== "function") return null;
2231
+ return (name) => {
2232
+ let theme;
2233
+ try {
2234
+ theme = getTheme.call(ctx.ui, name);
2235
+ } catch {
2236
+ theme = null;
2237
+ }
2238
+ if (!theme) throw new Error(`Theme ${name} is unavailable.`);
2239
+ if (typeof theme.name === "string" && theme.name !== name) {
2240
+ throw new Error(`Theme ${name} is unavailable.`);
2241
+ }
2242
+ const accent = typeof theme.getBgAnsi === "function" ? theme.getBgAnsi("accent") : undefined;
2243
+ const text = typeof theme.getFgAnsi === "function" ? theme.getFgAnsi("text") : undefined;
2244
+ if (typeof accent !== "string" || typeof text !== "string") {
2245
+ throw new Error(`Theme ${name} exposes no palette escapes.`);
2246
+ }
2247
+ // The upstream sample: a background block then the sample text.
2248
+ return { title: "source palette", sample: `${accent} \x1b[0m ${text}Aa sample text\x1b[0m` };
2249
+ };
2250
+ }
2251
+
2252
+ function customizePanelModel(ctx) {
2173
2253
  const panel = customizePanelModule();
2174
2254
  if (!panel) return null;
2175
2255
  return panel.customizePanelModel({
2176
2256
  sidebar: sidebarRowsState().state,
2177
2257
  moshi: moshiFlagEnabled(moshiFlagPath()) ? "on" : "off",
2178
2258
  theme: readCustomizeThemeState(),
2259
+ themeNames: readHostThemeNames(ctx),
2260
+ themePreview: themePreviewFactory(ctx),
2179
2261
  });
2180
2262
  }
2181
2263
 
@@ -2569,7 +2651,7 @@ function applyMoshiNotifications(want) {
2569
2651
  // only when the Moshi settings entry actually changed. The theme switch never
2570
2652
  // reloads: the palette it writes belongs to Herdr, so a Pi reload would only
2571
2653
  // restart the extension for nothing.
2572
- async function applyCustomizeSwitch(id, value, ctx) {
2654
+ async function applyCustomizeSwitch(id, value, ctx, options = {}) {
2573
2655
  const want = value === "on";
2574
2656
  const result = id === "sidebar"
2575
2657
  ? await applySidebarRows(want)
@@ -2577,10 +2659,20 @@ async function applyCustomizeSwitch(id, value, ctx) {
2577
2659
  ? applyThemeSync(want)
2578
2660
  : applyMoshiNotifications(want);
2579
2661
  const notify = ctx?.ui?.notify;
2580
- if (typeof notify === "function") {
2581
- notify(`${result.text}${result.needsReload ? " Reloading now to apply the change." : ""}`, result.level);
2582
- }
2583
- if (result.needsReload && typeof ctx?.reload === "function") await ctx.reload();
2662
+ // The reload sentence is a PROMISE about what happens next, so it is written
2663
+ // from what this surface can actually do. `deferReload` hands the reload to the
2664
+ // caller that mounted the overlay (the card closes first, then it reloads), and
2665
+ // `noReload` is the Gentle Shell customize page, where a row action receives no
2666
+ // ctx and therefore no reload handle: there the only honest sentence is a
2667
+ // restart. Every other combination is the command's own immediate reload.
2668
+ const canReload = options.deferReload !== true && options.noReload !== true
2669
+ && typeof ctx?.reload === "function";
2670
+ const reloadNotice = result.needsReload
2671
+ ? (options.noReload === true ? ` ${MOSHI_RESTART_TEXT}` : " Reloading now to apply the change.")
2672
+ : "";
2673
+ if (typeof notify === "function") notify(`${result.text}${reloadNotice}`, result.level);
2674
+ if (result.needsReload && canReload) await ctx.reload();
2675
+ return result;
2584
2676
  }
2585
2677
 
2586
2678
  // The one-line spelling of the theme state, shared by `status` and the menu
@@ -2632,7 +2724,9 @@ function applyThemeSync(want) {
2632
2724
 
2633
2725
  // `ctx.ui.getAllThemes()` documents `{ name, path }` records; a plain string list
2634
2726
  // is accepted too. A malformed entry is skipped instead of failing the whole
2635
- // list, and the result is deduplicated and sorted so the prompt is stable.
2727
+ // list. S2 keeps Pi's OWN order (the list the user sees in /settings), drops the
2728
+ // names that are paths rather than themes (`/` in the name, as upstream does) and
2729
+ // deduplicates, so one theme is never offered twice.
2636
2730
  function themeNames(themes) {
2637
2731
  if (!Array.isArray(themes)) return null;
2638
2732
  const names = [];
@@ -2640,9 +2734,10 @@ function themeNames(themes) {
2640
2734
  const name = typeof entry === "string" ? entry : isRecord(entry) ? entry.name : null;
2641
2735
  if (typeof name !== "string") continue;
2642
2736
  const clean = name.trim();
2643
- if (clean.length > 0) names.push(clean);
2737
+ if (clean.length === 0 || clean.includes("/")) continue;
2738
+ names.push(clean);
2644
2739
  }
2645
- return [...new Set(names)].sort();
2740
+ return [...new Set(names)];
2646
2741
  }
2647
2742
 
2648
2743
  // The picker's entries plus the ONE entry that means "unassign". A theme really
@@ -2658,9 +2753,67 @@ function themeSelectionOptions(names) {
2658
2753
  return { options: [...names, unassign], unassign };
2659
2754
  }
2660
2755
 
2661
- // S4: pin one of Pi's themes while the sync is off. The refusal, the missing
2662
- // theme list and an empty answer all write NOTHING, so the stored document only
2663
- // ever changes to a value the user actually picked.
2756
+ // T10 (odd/tasks/herdr-customize-page.md): a surface that holds its own rows can
2757
+ // outlive the catalogue it built them from. Only the Herdr PAGE does: it keeps
2758
+ // one row per theme for as long as Gentle Shell shows the menu, while the
2759
+ // command's picker reads `getAllThemes()` when it prompts and the mounted panel
2760
+ // keeps the 865d360 write. The guard therefore lives on the page's apply path (`applyCustomizePageChoice`), never in the write the command and the
2761
+ // panel share (S2).
2762
+ //
2763
+ // The wording is the notice the theme sync already gives for a stored name this
2764
+ // install does not have (`extensions/herdr-theme-sync.ts`, S4): one sentence for
2765
+ // one fact, spelled once. A catalogue that cannot be read at all gets the page's
2766
+ // own apply-time sentence, because a name nothing verified is never written.
2767
+ function themeNotInstalledText(name) {
2768
+ return `The Pi theme "${name}" is not installed, so Herdr's palette was left unchanged; pick an installed theme in /herdr-gentle:customize.`;
2769
+ }
2770
+
2771
+ // A FRESH read, never the page's row cache: `readHostThemeNames` calls the host
2772
+ // accessor again on every call, so the answer describes the install as it is at
2773
+ // APPLY time.
2774
+ function themeStillInstalled(ctx, name) {
2775
+ const names = readHostThemeNames(ctx);
2776
+ if (names === null) return { ok: false, text: THEME_LIST_UNREADABLE_AT_APPLY_TEXT };
2777
+ return names.includes(name) ? { ok: true, text: null } : { ok: false, text: themeNotInstalledText(name) };
2778
+ }
2779
+
2780
+ // One write for the pinned theme, shared by the inline panel setting, the Herdr
2781
+ // page rows and the `ctx.ui.select` fallback: the refusal, the missing store and
2782
+ // a failure all write NOTHING, so the stored document only ever changes to a
2783
+ // value the user actually picked (S7). No catalogue check lives here: the
2784
+ // command's picker cannot outlive its catalogue, and the page's own guard runs
2785
+ // before this call (T10), so neither surface can inherit a new refusal.
2786
+ function writeThemeChoice(ctx, name) {
2787
+ const notify = ctx?.ui?.notify;
2788
+ const store = themeStoreModule();
2789
+ if (!store || typeof store.writeThemeState !== "function") {
2790
+ if (typeof notify === "function") notify(THEME_STORE_UNAVAILABLE_TEXT, "warning");
2791
+ return false;
2792
+ }
2793
+ if (readCustomizeThemeState().sync === true) {
2794
+ if (typeof notify === "function") notify(THEME_SYNC_REFUSED_TEXT, "warning");
2795
+ return false;
2796
+ }
2797
+ try {
2798
+ store.writeThemeState(process.env, { sync: false, theme: name });
2799
+ } catch (error) {
2800
+ if (typeof notify === "function") notify(themeStoreWriteError(error), "error");
2801
+ return false;
2802
+ }
2803
+ if (typeof notify === "function") {
2804
+ notify(
2805
+ name === null
2806
+ ? "Gentle Shell theme set to Off; Herdr keeps the palette it was last given."
2807
+ : `Gentle Shell theme set to ${name}.`,
2808
+ "info",
2809
+ );
2810
+ }
2811
+ return true;
2812
+ }
2813
+
2814
+ // S4: pin one of Pi's themes while the sync is off, through the host's own
2815
+ // picker. The refusal, the missing theme list and an empty answer all write
2816
+ // NOTHING, so the stored document only ever changes to a value the user picked.
2664
2817
  async function applyThemeSelection(ctx) {
2665
2818
  const notify = ctx?.ui?.notify;
2666
2819
  const store = themeStoreModule();
@@ -2702,47 +2855,55 @@ async function applyThemeSelection(ctx) {
2702
2855
  }
2703
2856
  // Esc/cancel and an empty answer write nothing at all.
2704
2857
  if (typeof picked !== "string" || picked.length === 0) return;
2705
- const next = picked === picker.unassign ? null : picked;
2706
- try {
2707
- store.writeThemeState(process.env, { sync: false, theme: next });
2708
- } catch (error) {
2709
- if (typeof notify === "function") notify(themeStoreWriteError(error), "error");
2710
- return;
2711
- }
2712
- if (typeof notify === "function") {
2713
- notify(
2714
- next === null
2715
- ? "Gentle Shell theme set to Off; Herdr keeps the palette it was last given."
2716
- : `Gentle Shell theme set to ${next}.`,
2717
- "info",
2718
- );
2719
- }
2858
+ writeThemeChoice(ctx, picked === picker.unassign ? null : picked);
2720
2859
  }
2721
2860
 
2722
- // The single apply path shared by the overlay and the menu fallback. The choice
2723
- // the panel resolves names the switch it drives (`switchId`) and the value to
2724
- // apply; that switch id is the only thing read here, so a row can never apply a
2725
- // switch its category does not own. An inconclusive sidebar verdict is never a
2726
- // refusal: choosing On still attempts the repair and reports the apply step's
2727
- // own error, exactly like the baseline menu did. The theme value is the one row
2728
- // that is not a toggle: it carries the `select` row id, and the refusal for a
2729
- // stored sync lives in `applyThemeSelection` so both entry points share it.
2730
- const CUSTOMIZE_SWITCH_IDS = ["sidebar", "moshi", "theme-sync", "theme"];
2861
+ // The apply path of the menu fallback. The choice names the switch it drives
2862
+ // (`switchId`) and the value to apply; that switch id is the only thing read
2863
+ // here, so a row can never apply a switch its category does not own. An
2864
+ // inconclusive sidebar verdict is never a refusal: choosing On still attempts
2865
+ // the repair and reports the apply step's own error, exactly like the baseline
2866
+ // menu did. The fallback has no inline theme list, so its theme setting keeps
2867
+ // opening the host's picker through `applyThemeSelection`.
2868
+ const CUSTOMIZE_SWITCH_IDS = ["sidebar", "moshi", "theme-sync"];
2731
2869
 
2732
2870
  async function applyCustomizeChoice(choice, ctx) {
2733
2871
  if (!isRecord(choice)) return;
2734
2872
  const switchId = choice.switchId;
2735
2873
  const valueId = choice.valueId;
2736
2874
  if (!CUSTOMIZE_SWITCH_IDS.includes(switchId)) return;
2737
- if (switchId === "theme") {
2738
- if (valueId !== CUSTOMIZE_THEME_SELECT_ROW_ID) return;
2739
- await applyThemeSelection(ctx);
2740
- return;
2741
- }
2742
2875
  if (valueId !== "on" && valueId !== "off") return;
2743
2876
  await applyCustomizeSwitch(switchId, valueId, ctx);
2744
2877
  }
2745
2878
 
2879
+ // The overlay's apply path: it receives the structural ids of the setting and
2880
+ // the option the user confirmed, writes through the same functions the menu
2881
+ // uses, and answers with a freshly read model so the panel shows the real state
2882
+ // instead of guessing it. `close` is only true when Pi must reload: the caller
2883
+ // closes the overlay first and reloads after it resolved.
2884
+ async function applyCustomizePanel(choice, ctx, options = {}) {
2885
+ const model = () => customizePanelModel(ctx);
2886
+ if (!isRecord(choice)) return { model: model(), close: false, reload: false };
2887
+ const { settingId, optionId } = choice;
2888
+ if (settingId === CUSTOMIZE_THEME_SETTING_ID) {
2889
+ if (optionId === CUSTOMIZE_THEME_NONE_OPTION_ID) writeThemeChoice(ctx, null);
2890
+ else if (typeof optionId === "string" && optionId.startsWith(CUSTOMIZE_THEME_OPTION_PREFIX)) {
2891
+ writeThemeChoice(ctx, optionId.slice(CUSTOMIZE_THEME_OPTION_PREFIX.length));
2892
+ }
2893
+ return { model: model(), close: false, reload: false };
2894
+ }
2895
+ if (!CUSTOMIZE_SWITCH_IDS.includes(settingId)) return { model: model(), close: false, reload: false };
2896
+ if (optionId !== "on" && optionId !== "off") return { model: model(), close: false, reload: false };
2897
+ const result = await applyCustomizeSwitch(
2898
+ settingId,
2899
+ optionId,
2900
+ ctx,
2901
+ options.noReload === true ? { noReload: true } : { deferReload: true },
2902
+ );
2903
+ const reload = Boolean(result && result.needsReload);
2904
+ return { model: model(), close: reload, reload };
2905
+ }
2906
+
2746
2907
  // The former plain menu, kept as the fallback when the TUI helpers or
2747
2908
  // `ctx.ui.custom` are unavailable. It reads the same model and applies
2748
2909
  // through the same path as the overlay, and it offers the theme rows too, so
@@ -2826,11 +2987,11 @@ async function executeCustomize(rawArgs, ctx) {
2826
2987
  }
2827
2988
  if (helpers && ctx?.ui && typeof ctx.ui.custom === "function") {
2828
2989
  const panel = customizePanelModule();
2829
- const model = customizePanelModel();
2830
- let choice = null;
2990
+ const model = customizePanelModel(ctx);
2991
+ let reloadPending = false;
2831
2992
  if (panel && model) {
2832
2993
  try {
2833
- choice = await ctx.ui.custom(
2994
+ await ctx.ui.custom(
2834
2995
  // Theme and terminal rows travel through the real factory arguments:
2835
2996
  // the card paints with the host theme and clips to the live height.
2836
2997
  (hostTui, theme, _keybindings, done) => panel.createCustomizePanel({
@@ -2848,6 +3009,15 @@ async function executeCustomize(rawArgs, ctx) {
2848
3009
  }
2849
3010
  },
2850
3011
  model,
3012
+ // Enter applies in place behind the panel's busy guard: the panel
3013
+ // swaps in the model this reads back and stays open, except when a
3014
+ // reload is needed — then it closes so `ctx.reload()` runs here,
3015
+ // never behind a mounted card.
3016
+ apply: async (request) => {
3017
+ const outcome = await applyCustomizePanel(request, ctx);
3018
+ if (outcome.reload) reloadPending = true;
3019
+ return { model: outcome.model, close: outcome.close };
3020
+ },
2851
3021
  done,
2852
3022
  }),
2853
3023
  CUSTOMIZE_OVERLAY_OPTIONS,
@@ -2857,22 +3027,209 @@ async function executeCustomize(rawArgs, ctx) {
2857
3027
  await runCustomizeFallback(ctx);
2858
3028
  return;
2859
3029
  }
2860
- } else {
2861
- await runCustomizeFallback(ctx);
3030
+ if (reloadPending && typeof ctx.reload === "function") await ctx.reload();
2862
3031
  return;
2863
3032
  }
2864
- // Esc (null) does nothing at all: no notification, no write, no reload.
2865
- // Anything else runs the single apply path once the overlay is disposed.
2866
- if (!choice || typeof choice !== "object") return;
2867
- await applyCustomizeChoice(choice, ctx);
3033
+ await runCustomizeFallback(ctx);
2868
3034
  return;
2869
3035
  }
2870
3036
  await runCustomizeFallback(ctx);
2871
3037
  }
2872
3038
 
3039
+ // ---------------------------------------------------------------------------
3040
+ // The Gentle Shell customize PAGE (odd/tasks/herdr-customize-page.md T7;
3041
+ // specs S1, S2, S4).
3042
+ //
3043
+ // `/herdr-gentle:customize` is registered in the FACTORY, unconditionally, exactly
3044
+ // as on `865d360`. This section ADDS a second surface on top of it: when
3045
+ // gentle-shell-bridge answers its handshake, the same four switches also appear as
3046
+ // the `Herdr` page of Gentle Shell's own `/gentle:customize` menu. The page never
3047
+ // replaces the command — two surfaces coexisting is by design, because Pi gives an
3048
+ // extension no way to withdraw a registered command and a bridge with no host menu
3049
+ // must never leave the user with none.
3050
+ //
3051
+ // The bridge is reached as a HANDSHAKE, never a dependency: its object sits at a
3052
+ // `Symbol.for` key on `globalThis`, and the key, the schema and the members this
3053
+ // file calls are inlined here, so nothing resolves `gentle-shell-bridge` as a
3054
+ // module (`examples/bash-card.ts:1214-1244` in that package is the same pattern).
3055
+ //
3056
+ // WHEN the page appears. `session_start` asks the symbol; when it is absent the
3057
+ // page cannot be built yet, so the factory has already subscribed to
3058
+ // `BRIDGE_READY_EVENT` and the announce asks again. That covers Pi's load order,
3059
+ // which does not guarantee that a configured package's module publishes before a
3060
+ // global extension's `session_start`: a late bridge still produces the page. The
3061
+ // announce is a notification, never a registry — the symbol stays the authority,
3062
+ // so a copy that publishes an incompatible slot announces nothing usable and the
3063
+ // gate below answers ABSENT.
3064
+ //
3065
+ // ONE provider, never two. Registration is guarded by the live provider itself, so
3066
+ // a second `session_start`, an announce after a start and a repeated announce all
3067
+ // leave exactly one registration; the bridge's bus is never asked twice. The
3068
+ // provider is session-scoped and the command is not: only the provider is disposed
3069
+ // on session shutdown.
3070
+ // ---------------------------------------------------------------------------
3071
+ const BRIDGE_API_KEY = Symbol.for("gentle-shell-bridge/api/v1");
3072
+ const BRIDGE_API_SCHEMA = "gentle-shell-bridge/api";
3073
+ const BRIDGE_API_VERSION = 1;
3074
+ // The channel the bridge announces itself on. The string MIRRORS `src/api.ts`:
3075
+ // this file cannot import it, so the two are kept in sync by hand.
3076
+ const BRIDGE_READY_EVENT = "gentle-shell-bridge:ready";
3077
+ // The provider's stable id: the bridge replaces a provider registered under the
3078
+ // same id in place, so one page is one page however often it is registered.
3079
+ const CUSTOMIZE_PAGE_PROVIDER_ID = "herdr-gentle:customize";
3080
+
3081
+ // The published object, gated exactly like the bridge's own `isBridgeApi`
3082
+ // (`src/api.ts`): identity strings plus the members this file calls. A foreign
3083
+ // payload, another major version or a partial object is ABSENT — never an error,
3084
+ // never guessed at, never overwritten.
3085
+ function publishedBridge() {
3086
+ const slot = globalThis[BRIDGE_API_KEY];
3087
+ if (!isRecord(slot)) return null;
3088
+ if (slot.schema !== BRIDGE_API_SCHEMA || slot.version !== BRIDGE_API_VERSION) return null;
3089
+ if (typeof slot.registerRows !== "function") return null;
3090
+ if (typeof slot.registerSection !== "function" || typeof slot.createStore !== "function") return null;
3091
+ return slot;
3092
+ }
3093
+
3094
+ // A row's apply path — and it IS the overlay's own path (`applyCustomizePanel`),
3095
+ // not a copy: the same `writeThemeChoice` for the pinned theme, the same
3096
+ // `applyCustomizeSwitch` for the three switched settings, and therefore the same
3097
+ // Moshi prerequisite gate and the same "a refusal writes nothing" promise by
3098
+ // construction. It adds the two facts the overlay does not need: a row action
3099
+ // receives no ctx, so the page has no reload handle and the shared path reports a
3100
+ // restart instead of reloading (see `applyCustomizeSwitch`), and the page's rows
3101
+ // outlive the theme catalogue they were built from (T10).
3102
+ //
3103
+ // The catalogue guard lives HERE, on the page's own call site, and not in the
3104
+ // shared write: the command's picker and the mounted panel keep the 865d360
3105
+ // behavior byte for byte (S2), and no other surface can be affected by
3106
+ // construction. A name removed after the build is refused with the not-installed
3107
+ // notice and writes nothing; a catalogue that cannot be read at apply time gets
3108
+ // the page's own honest sentence and also writes nothing.
3109
+ //
3110
+ // A refusal is NOT re-thrown: the shared path reports it through the host's own
3111
+ // `ui.notify` and returns, which is one report — the same one the command gives.
3112
+ // Throwing on top of that would report it twice (the bridge reports a thrown
3113
+ // action again), so only an unexpected exception travels into the bridge's
3114
+ // channel.
3115
+ async function applyCustomizePageChoice(choice, ctx) {
3116
+ if (isRecord(choice) && choice.settingId === CUSTOMIZE_THEME_SETTING_ID) {
3117
+ const optionId = choice.optionId;
3118
+ // The sync gate answers FIRST, exactly as it does on every other surface.
3119
+ // While sync is on the pinned theme is not available at all, so asking the
3120
+ // catalogue whether the theme still exists would answer a question the row
3121
+ // cannot act on and would bury the one thing the user has to do first.
3122
+ const syncOn = readCustomizeThemeState().sync === true;
3123
+ if (!syncOn && typeof optionId === "string" && optionId.startsWith(CUSTOMIZE_THEME_OPTION_PREFIX)) {
3124
+ const installed = themeStillInstalled(ctx, optionId.slice(CUSTOMIZE_THEME_OPTION_PREFIX.length));
3125
+ if (!installed.ok) {
3126
+ const notify = ctx?.ui?.notify;
3127
+ if (typeof notify === "function") notify(installed.text, "warning");
3128
+ return { model: customizePanelModel(ctx), close: false, reload: false };
3129
+ }
3130
+ }
3131
+ }
3132
+ return applyCustomizePanel(choice, ctx, { noReload: true });
3133
+ }
3134
+
3135
+ // The one provider this extension contributes: the `Herdr` page (a row
3136
+ // CATEGORY, never `registerSection`, which is a sidebar card). `rows()` is called
3137
+ // on every menu build, so the model — and every `current()`, swatch and sync gate
3138
+ // inside it — is read live rather than captured at registration.
3139
+ function customizePageProvider(rowsModule, hostCtx) {
3140
+ return {
3141
+ id: CUSTOMIZE_PAGE_PROVIDER_ID,
3142
+ category: rowsModule.CUSTOMIZE_ROWS_CATEGORY,
3143
+ rows() {
3144
+ const ctx = hostCtx();
3145
+ // No session ctx means no theme catalogue and no notify channel; an empty
3146
+ // page is the honest answer, and `customizeRows` answers no rows for a
3147
+ // model it cannot read anyway.
3148
+ if (!ctx) return [];
3149
+ return rowsModule.customizeRows({
3150
+ model: () => customizePanelModel(ctx),
3151
+ apply: (choice) => applyCustomizePageChoice(choice, ctx),
3152
+ });
3153
+ },
3154
+ };
3155
+ }
3156
+
3157
+ // The Gentle Shell customize page as a REGISTRATION LIFECYCLE, bound by the
3158
+ // factory beside the command (which is registered there too, unconditionally).
3159
+ // Additive by construction: nothing here can unregister or shadow the command.
3160
+ function registerCustomizePage(pi) {
3161
+ let pageContext = null;
3162
+ let disposePage = null;
3163
+
3164
+ function clearPage() {
3165
+ const dispose = disposePage;
3166
+ disposePage = null;
3167
+ if (typeof dispose !== "function") return;
3168
+ try {
3169
+ dispose();
3170
+ } catch {
3171
+ // The bridge owns its own bus: a disposer that fails cannot make this file
3172
+ // host a second page, so the failure is contained here.
3173
+ }
3174
+ }
3175
+
3176
+ // The one registration path `session_start` and the announce both use, so an
3177
+ // announce and a later session cannot both register and a repeated announce
3178
+ // cannot stack a second provider. A live provider IS the guard: re-registering
3179
+ // would only ask the bus to replace an identical entry.
3180
+ function registerPage() {
3181
+ if (disposePage !== null) return;
3182
+ // No session yet: `session_start` asks again once there is a ctx to build the
3183
+ // model from.
3184
+ if (!pageContext) return;
3185
+ const bridge = publishedBridge();
3186
+ // S2: nothing answered the handshake, so today's command stands alone.
3187
+ if (!bridge) return;
3188
+ const rowsModule = customizeRowsModule();
3189
+ // An install without the sibling lib/ has no page to offer; the command and
3190
+ // every other surface keep working.
3191
+ if (!rowsModule) return;
3192
+ let dispose = null;
3193
+ try {
3194
+ dispose = bridge.registerRows(customizePageProvider(rowsModule, () => pageContext));
3195
+ } catch {
3196
+ // A bus that refuses the provider (a host with no customize menu asks for
3197
+ // nothing else): the command is already registered, so no surface is lost.
3198
+ dispose = null;
3199
+ }
3200
+ if (typeof dispose === "function") disposePage = dispose;
3201
+ }
3202
+
3203
+ // The symbol first: when the bridge is already published there is nothing to
3204
+ // wait for and no listener is taken. Otherwise the announce is the only way a
3205
+ // bridge that loads AFTER this extension is ever heard.
3206
+ const events = pi?.events;
3207
+ if (events && typeof events.on === "function" && !publishedBridge()) {
3208
+ try {
3209
+ events.on(BRIDGE_READY_EVENT, registerPage);
3210
+ } catch {
3211
+ // No bus and no ready event: `session_start` still tries the symbol.
3212
+ }
3213
+ }
3214
+
3215
+ pi.on("session_start", (_event, ctx) => {
3216
+ pageContext = isRecord(ctx) ? ctx : null;
3217
+ registerPage();
3218
+ });
3219
+
3220
+ pi.on("session_shutdown", () => {
3221
+ // The bridge's bus outlives the session, so only the provider is dropped:
3222
+ // the command stays as registered, and the next session adds one page again
3223
+ // instead of stacking a second one.
3224
+ clearPage();
3225
+ pageContext = null;
3226
+ });
3227
+ }
3228
+
2873
3229
  export default function (pi) {
2874
3230
  // Registered before the pane gate on purpose: the switches are local state and
2875
- // must stay reachable from a plain Pi session outside a Herdr pane.
3231
+ // must stay reachable from a plain Pi session outside a Herdr pane. S1: this is
3232
+ // unconditional — the page below is additive, never a replacement.
2876
3233
  if (typeof pi?.registerCommand === "function") {
2877
3234
  pi.registerCommand("herdr-gentle:customize", {
2878
3235
  description: "Customize Herdr Gentle Shell: sidebar agent rows, Moshi notifications and the Herdr theme",
@@ -2881,6 +3238,7 @@ export default function (pi) {
2881
3238
  },
2882
3239
  });
2883
3240
  }
3241
+ registerCustomizePage(pi);
2884
3242
  if (!enabled()) return;
2885
3243
 
2886
3244
  let rootSession = false;