@pellux/goodvibes-tui 0.20.3 → 0.21.0

package/src/input/onboarding/onboarding-wizard-types.ts

@@ -1,10 +1,7 @@
-import { isIP } from 'node:net';
 import type { ModelPickerTarget } from '../model-picker.ts';
 import {
-  deriveOnboardingStepState,
   type OnboardingAcknowledgementReason,
   type OnboardingAcknowledgementTarget,
-  type OnboardingApplyOperation,
   type OnboardingApplyRequest,
   type OnboardingMode,
   type OnboardingSnapshotState,
@@ -193,3 +190,148 @@ export interface OnboardingWizardRuntimeHydration {
 }
 
 export type MutableModelSelectionMap = Map<ModelPickerTarget, OnboardingWizardModelSelection>;
+
+// ---------------------------------------------------------------------------
+// External surface types (moved here to break the surfaces ↔ extra-specs cycle)
+// ---------------------------------------------------------------------------
+
+export interface ExternalSurfaceSetupFieldSpec {
+  readonly id: string;
+  readonly configKey: ConfigKey;
+  readonly kind: 'text' | 'masked' | 'radio';
+  readonly valueType?: 'string' | 'number';
+  readonly label: string;
+  readonly hint: string;
+  readonly placeholder: string;
+  readonly options?: readonly OnboardingWizardRadioOption[];
+  readonly defaultNumber?: number;
+  readonly min?: number;
+  readonly max?: number;
+  readonly defaultValue: (snapshot: OnboardingSnapshotState | null) => string;
+}
+
+export interface ExternalSurfaceSpec {
+  readonly id: string;
+  readonly enabledFieldId: string;
+  readonly enabledConfigKey: ConfigKey;
+  readonly label: string;
+  readonly hint: string;
+  /**
+   * Existing SDK config key. In onboarding this maps to the per-surface
+   * auto-start choice, not to whether setup fields are shown.
+   */
+  readonly defaultEnabled: (snapshot: OnboardingSnapshotState | null) => boolean;
+  readonly fields: readonly ExternalSurfaceSetupFieldSpec[];
+}
+
+// ---------------------------------------------------------------------------
+// Controller interface (moved here to break the wizard ↔ satellites cycle)
+// ---------------------------------------------------------------------------
+
+/**
+ * Public interface of OnboardingWizardController. Satellite modules
+ * (apply, steps, rules, state, cloudflare, cloudflare-step) receive the
+ * controller through this interface so they do not need to import from
+ * onboarding-wizard.ts and the circular dependency is broken.
+ */
+export interface OnboardingWizardControllerLike {
+  // State fields
+  active: boolean;
+  mode: OnboardingWizardMode;
+  stepIndex: number;
+  hydrationPending: boolean;
+  hydrationError: string | null;
+  pendingModelPickerTarget: ModelPickerTarget | null;
+  pendingAction: OnboardingWizardAction | null;
+  editingFieldId: string | null;
+  editBuffer: string;
+  applyFeedback: OnboardingWizardApplyFeedback | null;
+
+  readonly scrollOffsets: number[];
+  readonly selectedFieldIndices: number[];
+  readonly dirtyStepIds: Set<OnboardingWizardStepId>;
+  readonly toggleState: Map<string, boolean>;
+  readonly touchedActionFields: Set<string>;
+  readonly radioState: Map<string, string>;
+  readonly textState: Map<string, string>;
+  readonly modelSelectionState: MutableModelSelectionMap;
+
+  readonly baselineToggleState: Map<string, boolean>;
+  readonly baselineRadioState: Map<string, string>;
+  readonly baselineTextState: Map<string, string>;
+  readonly baselineModelSelectionState: MutableModelSelectionMap;
+
+  runtimeSnapshot: OnboardingSnapshotState | null;
+  runtimeDerived: OnboardingStepDerivationState;
+
+  // Computed
+  readonly steps: readonly OnboardingWizardStepDefinition[];
+  readonly currentStep: OnboardingWizardStepDefinition;
+  readonly dirty: boolean;
+  readonly dirtyStepCount: number;
+
+  // Field value accessors
+  getFieldValue(field: OnboardingWizardFieldDefinition): boolean | string | OnboardingWizardModelSelection;
+  getFieldById(fieldId: string): OnboardingWizardFieldDefinition | null;
+  getStringFieldValue(fieldId: string, fallback: string): string;
+  getBooleanFieldValue(fieldId: string, fallback: boolean): boolean;
+  parseIntegerFieldValue(fieldId: string, fallback: number): number | null;
+  getPortFieldValue(fieldId: string, fallback: number): number;
+  getNumberFieldValue(fieldId: string, fallback: number, min?: number, max?: number): number;
+
+  // Capability / rules accessors
+  isCapabilitySelected(capabilityId: OnboardingStep1CapabilityId): boolean;
+  hasServerCapabilitiesSelected(): boolean;
+  shouldEnableBrowserSurface(): boolean;
+  hasSelectedInboundExternalSurface(): boolean;
+  isRequiredExternalSetupField(fieldId: string): boolean;
+  getSelectedSecretMedium(): 'secure' | 'plaintext';
+  shouldEnableHttpListener(): boolean;
+  shouldExposeHttpListenerNetworkFields(): boolean;
+  shouldExposeControlPlaneNetwork(): boolean;
+  requiresAuthBootstrap(): boolean;
+  hasAdminAuthUser(): boolean;
+  hasLocalAuthUser(): boolean;
+  hasBootstrapCredentialPresent(): boolean;
+  getDefaultAdminUsername(): string;
+  getSharedIpDefault(enabled: { readonly controlPlane: boolean; readonly httpListener: boolean; readonly web: boolean }): boolean;
+  getSharedIpHostDefault(enabled: { readonly controlPlane: boolean; readonly httpListener: boolean; readonly web: boolean }): string;
+
+  // Capability mutations
+  toggleCapability(capabilityId: OnboardingStep1CapabilityId): void;
+  selectAllServerCapabilities(): void;
+  selectLocalTuiOnly(): void;
+  selectAllExternalSurfaces(): void;
+  clearExternalSurfaces(): void;
+  setCapabilityValue(capabilityId: OnboardingStep1CapabilityId, selected: boolean): void;
+  getCurrentCapabilities(): readonly OnboardingStep1CapabilityItem[];
+  getCapabilitySelectionState(): readonly OnboardingStep1CapabilityItem[];
+
+  // State operations
+  recalculateDirtyState(): void;
+  reconcileStateWithCurrentDefinitions(): void;
+  reconcileStepCursor(stepIndex: number): void;
+  resetValuesFromCurrentDefinitions(): void;
+  ensureSelectionVisible(visibleFields: number): void;
+  isFieldDirty(fieldId: string): boolean;
+  isFieldDirtyByDefinition(field: OnboardingWizardFieldDefinition): boolean;
+  isFieldSatisfied(field: OnboardingWizardFieldDefinition): boolean;
+  isStepDirty(stepIndex: number): boolean;
+  hasExistingAccessState(): boolean;
+  getBlockingFieldLabels(): readonly string[];
+  getFieldValidationError(step: OnboardingWizardStepDefinition, field: OnboardingWizardFieldDefinition): string | null;
+  getToggleFieldCount(stepIndex: number): number;
+  getCompletedToggleCount(stepIndex: number): number;
+  getStepFieldCount(stepIndex: number): number;
+  getCompletedFieldCount(stepIndex: number): number;
+
+  // Additional operations used by steps/apply
+  buildApplyRequest(): OnboardingApplyRequest;
+  isEditingTextField(): boolean;
+  getTextFieldValue(fieldId: string, fallback?: string): string;
+  getFieldValueLabel(field: OnboardingWizardFieldDefinition): string;
+  getSelectedFieldIndex(): number;
+  getSelectedField(): OnboardingWizardFieldDefinition | null;
+  getFieldWindow(visibleFields: number): OnboardingWizardFieldWindow;
+}
+

package/src/input/onboarding/onboarding-wizard.ts

@@ -34,12 +34,12 @@ import {
   toggleCapability as toggleCapabilityForController,
 } from './onboarding-wizard-rules.ts';
 import { ensureSelectionVisible as ensureSelectionVisibleForController, getBlockingFieldLabels as getBlockingFieldLabelsForController, getCapabilitySelectionState as getCapabilitySelectionStateForController, getCompletedFieldCount as getCompletedFieldCountForController, getCompletedToggleCount as getCompletedToggleCountForController, getCurrentCapabilities as getCurrentCapabilitiesForController, getFieldById as getFieldByIdForController, getFieldValidationError as getFieldValidationErrorForController, getStepFieldCount as getStepFieldCountForController, getToggleFieldCount as getToggleFieldCountForController, hasExistingAccessState as hasExistingAccessStateForController, isFieldDirty as isFieldDirtyForController, isFieldDirtyByDefinition as isFieldDirtyByDefinitionForController, isFieldSatisfied as isFieldSatisfiedForController, isStepDirty as isStepDirtyForController, recalculateDirtyState as recalculateDirtyStateForController, reconcileStateWithCurrentDefinitions as reconcileStateWithCurrentDefinitionsForController, reconcileStepCursor as reconcileStepCursorForController, resetValuesFromCurrentDefinitions as resetValuesFromCurrentDefinitionsForController } from './onboarding-wizard-state.ts';
-import type { MutableModelSelectionMap, OnboardingWizardAction, OnboardingWizardApplyFeedback, OnboardingWizardFieldDefinition, OnboardingWizardFieldWindow, OnboardingWizardMode, OnboardingWizardModelSelection, OnboardingWizardRuntimeHydration, OnboardingWizardSnapshot, OnboardingWizardStepDefinition, OnboardingWizardStepId } from './onboarding-wizard-types.ts';
+import type { OnboardingWizardControllerLike, MutableModelSelectionMap, OnboardingWizardAction, OnboardingWizardApplyFeedback, OnboardingWizardFieldDefinition, OnboardingWizardFieldWindow, OnboardingWizardMode, OnboardingWizardModelSelection, OnboardingWizardRuntimeHydration, OnboardingWizardSnapshot, OnboardingWizardStepDefinition, OnboardingWizardStepId } from './onboarding-wizard-types.ts';
 
-export type { OnboardingWizardAcknowledgementFieldDefinition, OnboardingWizardAction, OnboardingWizardActionFieldDefinition, OnboardingWizardApplyFeedback, OnboardingWizardApplyFeedbackSeverity, OnboardingWizardChecklistFieldDefinition, OnboardingWizardExternalSurfaceStepId, OnboardingWizardFieldDefinition, OnboardingWizardFieldKind, OnboardingWizardFieldWindow, OnboardingWizardMaskedFieldDefinition, OnboardingWizardMode, OnboardingWizardModelPickerFieldDefinition, OnboardingWizardModelSelection, OnboardingWizardRadioFieldDefinition, OnboardingWizardRadioOption, OnboardingWizardRuntimeHydration, OnboardingWizardSnapshot, OnboardingWizardStatusFieldDefinition, OnboardingWizardStepDefinition, OnboardingWizardStepId, OnboardingWizardTextFieldDefinition } from './onboarding-wizard-types.ts';
+export type { OnboardingWizardControllerLike, OnboardingWizardAcknowledgementFieldDefinition, OnboardingWizardAction, OnboardingWizardActionFieldDefinition, OnboardingWizardApplyFeedback, OnboardingWizardApplyFeedbackSeverity, OnboardingWizardChecklistFieldDefinition, OnboardingWizardExternalSurfaceStepId, OnboardingWizardFieldDefinition, OnboardingWizardFieldKind, OnboardingWizardFieldWindow, OnboardingWizardMaskedFieldDefinition, OnboardingWizardMode, OnboardingWizardModelPickerFieldDefinition, OnboardingWizardModelSelection, OnboardingWizardRadioFieldDefinition, OnboardingWizardRadioOption, OnboardingWizardRuntimeHydration, OnboardingWizardSnapshot, OnboardingWizardStatusFieldDefinition, OnboardingWizardStepDefinition, OnboardingWizardStepId, OnboardingWizardTextFieldDefinition } from './onboarding-wizard-types.ts';
 export { getOnboardingWizardBodyRows, getOnboardingWizardVisibleFieldCount } from './onboarding-wizard-helpers.ts';
 
-export class OnboardingWizardController {
+export class OnboardingWizardController implements OnboardingWizardControllerLike {
   public active = false;
   public mode: OnboardingWizardMode = 'new';
   public stepIndex = 0;

package/src/input/settings-modal-data.ts

@@ -0,0 +1,304 @@
+/**
+ * settings-modal-data — pure data-assembly helpers for SettingsModal.
+ *
+ * All functions are stateless: they take dependencies as arguments and return
+ * derived data without mutating state. The class in settings-modal.ts delegates
+ * to these during open() and tab-switch operations.
+ */
+
+import { CONFIG_SCHEMA, type ConfigKey } from '@pellux/goodvibes-sdk/platform/config';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { getResolvedSettingLookup } from '@/runtime/index.ts';
+import type { FeatureFlagManager } from '@/runtime/index.ts';
+import type { McpRegistry } from '@pellux/goodvibes-sdk/platform/mcp';
+import { buildSubscriptionEntries } from './settings-modal-subscriptions.ts';
+import type { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ServiceInspectionQuery } from '../runtime/ui-service-queries.ts';
+import {
+  SETTINGS_CATEGORIES,
+  type FlagEntry,
+  type McpEntry,
+  type SettingEntry,
+  type SettingsCategory,
+  type SubscriptionEntry,
+} from './settings-modal-types.ts';
+
+// ---------------------------------------------------------------------------
+// deepEqual — structural equality for isDefault comparisons
+// ---------------------------------------------------------------------------
+
+/**
+ * Structural equality check for setting default comparisons.
+ * Handles scalars, arrays, and plain objects. Does NOT support
+ * circular references or non-plain prototypes — config defaults
+ * are always JSON-safe primitives, arrays, or plain objects.
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (a === undefined || b === undefined) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== 'object') return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const aKeys = Object.keys(ao);
+  const bKeys = Object.keys(bo);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(bo, key)) return false;
+    if (!deepEqual(ao[key], bo[key])) return false;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// buildSettingGroups — loads CONFIG_SCHEMA into per-category SettingEntry maps
+// ---------------------------------------------------------------------------
+
+export function buildSettingGroups(
+  configManager: ConfigManager,
+): Map<SettingsCategory, SettingEntry[]> {
+  const groups = new Map<SettingsCategory, SettingEntry[]>();
+  for (const cat of SETTINGS_CATEGORIES) {
+    if (cat === 'flags') continue;
+    groups.set(cat, []);
+  }
+
+  for (const setting of CONFIG_SCHEMA) {
+    const rawCat = setting.key.split('.')[0] as string;
+    const cat = rawCat as SettingsCategory;
+    const currentValue = configManager.get(setting.key as ConfigKey);
+    const resolved = getResolvedSettingLookup(configManager, setting.key as ConfigKey)?.entry;
+    const entry: SettingEntry = {
+      setting,
+      currentValue,
+      isDefault: deepEqual(currentValue, setting.default),
+      effectiveSource: resolved?.effectiveSource,
+      locked: resolved?.locked,
+      conflict: resolved?.conflict,
+      sourceLabel: resolved?.sourceLabel,
+      lockReason: resolved?.lockReason,
+    };
+    if (groups.has(cat)) groups.get(cat)!.push(entry);
+    if ((rawCat === 'controlPlane' || rawCat === 'httpListener' || rawCat === 'web') && groups.has('network')) {
+      groups.get('network')!.push(entry);
+    }
+  }
+
+  const uiEntries = groups.get('ui');
+  if (uiEntries) {
+    const uiPriority: Record<string, number> = {
+      'ui.systemMessages': 0,
+      'ui.operationalMessages': 1,
+      'ui.wrfcMessages': 2,
+      'ui.voiceEnabled': 3,
+    };
+    uiEntries.sort((a, b) => (uiPriority[a.setting.key] ?? 99) - (uiPriority[b.setting.key] ?? 99));
+  }
+
+  // Cross-list ui.voiceEnabled into the 'tts' category so that /config tts
+  // shows the always-speak toggle alongside the other TTS settings.
+  const ttsEntries = groups.get('tts');
+  if (ttsEntries && uiEntries) {
+    const voiceEnabledEntry = uiEntries.find((e) => e.setting.key === 'ui.voiceEnabled');
+    if (voiceEnabledEntry && !ttsEntries.some((e) => e.setting.key === 'ui.voiceEnabled')) {
+      ttsEntries.unshift(voiceEnabledEntry);
+    }
+  }
+
+  return groups;
+}
+
+// ---------------------------------------------------------------------------
+// buildFlagEntries — snapshot of current feature flag states
+// ---------------------------------------------------------------------------
+
+export function buildFlagEntries(featureFlagManager: FeatureFlagManager | null): FlagEntry[] {
+  if (!featureFlagManager) return [];
+  return Array.from(featureFlagManager.getAll().values()).map(({ flag, state }) => ({
+    flag,
+    state,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// buildMcpEntries — snapshot of current MCP server security entries
+// ---------------------------------------------------------------------------
+
+export function buildMcpEntries(mcpRegistry: McpRegistry | null): McpEntry[] {
+  if (!mcpRegistry) return [];
+  return mcpRegistry.listServerSecurity().map((entry) => ({
+    name: entry.name,
+    connected: entry.connected,
+    role: entry.role,
+    trustMode: entry.trustMode,
+    allowedPaths: [...entry.allowedPaths],
+    allowedHosts: [...entry.allowedHosts],
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// buildSubscriptionEntries — re-export for use by SettingsModal
+// ---------------------------------------------------------------------------
+
+export { buildSubscriptionEntries };
+
+// ---------------------------------------------------------------------------
+// buildNetworkFilteredItems — applies host-mode visibility rules for 'network' tab
+// ---------------------------------------------------------------------------
+
+export function buildNetworkFilteredItems(
+  items: SettingEntry[],
+  configManager: ConfigManager | null,
+): SettingEntry[] {
+  return items.filter(entry => {
+    if (entry.setting.key === 'controlPlane.host') {
+      return configManager?.get('controlPlane.hostMode') === 'custom';
+    }
+    if (entry.setting.key === 'httpListener.host') {
+      return configManager?.get('httpListener.hostMode') === 'custom';
+    }
+    if (entry.setting.key === 'web.host') {
+      return configManager?.get('web.hostMode') === 'custom';
+    }
+    return true;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// refreshEntryValues — re-reads currentValue/isDefault for all loaded entries
+// ---------------------------------------------------------------------------
+
+export function refreshEntryValues(
+  groups: Map<SettingsCategory, SettingEntry[]>,
+  configManager: ConfigManager,
+): void {
+  for (const entries of groups.values()) {
+    for (const entry of entries) {
+      entry.currentValue = configManager.get(entry.setting.key as ConfigKey);
+      entry.isDefault = deepEqual(entry.currentValue, entry.setting.default);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// updateEntryForKey — updates a single setting entry after a value change
+// ---------------------------------------------------------------------------
+
+export function updateEntryForKey(
+  groups: Map<SettingsCategory, SettingEntry[]>,
+  key: ConfigKey,
+  configManager: ConfigManager,
+): void {
+  for (const entries of groups.values()) {
+    const entry = entries.find((candidate) => candidate.setting.key === key);
+    if (entry) {
+      entry.currentValue = configManager.get(key);
+      entry.isDefault = deepEqual(entry.currentValue, entry.setting.default);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// fuzzyScoreSettingEntry — score an entry against a query for ranked search
+// ---------------------------------------------------------------------------
+
+/**
+ * Score a single SettingEntry against a search query.
+ *
+ * Score tiers (higher = better match):
+ *   - 3000–3999: exact key substring match (3000 + position bonus 0–999)
+ *   - 2000–2999: exact label substring match (2000 + position bonus 0–999)
+ *   - 1000–1999: exact description substring match (1000 + position bonus 0–999)
+ *   - 1–99:      subsequence match across key+label+description
+ *
+ * Returns null when the query does not match at all.
+ *
+ * @param query - The search string (already lowercased).
+ * @param entry - The setting entry to test.
+ * @param getLabel - Pure function mapping an entry to its display label.
+ */
+export function fuzzyScoreSettingEntry(
+  query: string,
+  entry: SettingEntry,
+  getLabel: (e: SettingEntry) => string,
+): number | null {
+  if (query.length === 0) return 0;
+  const lq = query.toLowerCase();
+  const key = entry.setting.key.toLowerCase();
+  const label = getLabel(entry).toLowerCase();
+  const description = (entry.setting.description ?? '').toLowerCase();
+
+  // Tier 1: key substring — base 3000, position bonus up to 999
+  // A key match at position 0 scores 3999; at position 999 scores 3000.
+  const keyIdx = key.indexOf(lq);
+  if (keyIdx !== -1) return 3000 + Math.max(0, 999 - keyIdx);
+
+  // Tier 2: label substring — base 2000, position bonus up to 999
+  const labelIdx = label.indexOf(lq);
+  if (labelIdx !== -1) return 2000 + Math.max(0, 999 - labelIdx);
+
+  // Tier 3: description substring — base 1000, position bonus up to 999
+  const descIdx = description.indexOf(lq);
+  if (descIdx !== -1) return 1000 + Math.max(0, 999 - descIdx);
+
+  // Tier 4: subsequence across concatenated key + label + description — 1..99
+  const haystack = `${key} ${label} ${description}`;
+  let qi = 0;
+  let score = 0;
+  for (let ci = 0; ci < haystack.length && qi < lq.length; ci++) {
+    if (haystack[ci] === lq[qi]) {
+      qi++;
+      score++;
+    }
+  }
+  if (qi === lq.length) return Math.min(99, score);
+  return null;
+}
+
+/**
+ * Search all setting entries across all groups, returning results ranked by
+ * relevance score (highest first). Excludes the flags, mcp, and subscriptions
+ * special categories (which have their own entry types).
+ *
+ * @param query - User input string. Empty string returns []. 
+ * @param groups - The settings group map from buildSettingGroups.
+ * @param getLabel - Pure function mapping an entry to its display label.
+ */
+export function searchSettingEntries(
+  query: string,
+  groups: Map<SettingsCategory, SettingEntry[]>,
+  getLabel: (e: SettingEntry) => string,
+): SettingEntry[] {
+  if (query.trim().length === 0) return [];
+  const lq = query.trim().toLowerCase();
+  const seen = new Set<string>();
+  const scored: Array<{ entry: SettingEntry; score: number }> = [];
+  for (const entries of groups.values()) {
+    for (const entry of entries) {
+      // Deduplicate: network tab cross-lists keys already in controlPlane/httpListener/web
+      if (seen.has(entry.setting.key)) continue;
+      seen.add(entry.setting.key);
+      const score = fuzzyScoreSettingEntry(lq, entry, getLabel);
+      if (score !== null) scored.push({ entry, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map(r => r.entry);
+}
+
+// ---------------------------------------------------------------------------
+// Re-export SubscriptionEntry for convenience
+// ---------------------------------------------------------------------------
+
+export type { SubscriptionEntry } from './settings-modal-types.ts';
+export type { SubscriptionManager };
+export type { ServiceInspectionQuery };

package/src/input/settings-modal-mutations.ts

@@ -0,0 +1,154 @@
+/**
+ * settings-modal-mutations — pure mutation helpers for SettingsModal.
+ *
+ * These functions encapsulate the side-effectful write operations:
+ * applying config values, persisting feature flag state, and applying flag
+ * runtime toggles. Each function takes its dependencies as explicit arguments
+ * rather than accessing class-level state.
+ */
+
+import type { ConfigKey, PersistedFlagState } from '@pellux/goodvibes-sdk/platform/config';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { FeatureFlagManager } from '@/runtime/index.ts';
+import type { FeatureFlag, FlagState } from '@/runtime/index.ts';
+import type { FlagEntry, SettingEntry } from './settings-modal-types.ts';
+import { deepEqual } from './settings-modal-data.ts';
+
+// ---------------------------------------------------------------------------
+// ApplyValueResult — returned by applySettingValue so the caller can react
+// ---------------------------------------------------------------------------
+
+export interface ApplyValueResult {
+  /** Restart domain that was triggered, if any. */
+  readonly restartDomain: 'control-plane' | 'http-listener' | 'web' | null;
+  /** Message from onSettingApplied handler, if any. */
+  readonly effectMessage: string | null;
+  /** Whether the value actually changed (false = no-op). */
+  readonly changed: boolean;
+}
+
+export type SettingAppliedCallback = (change: {
+  readonly key: ConfigKey;
+  readonly previousValue: unknown;
+  readonly value: unknown;
+}) => { readonly message?: string } | void;
+
+// ---------------------------------------------------------------------------
+// applySettingValue
+// ---------------------------------------------------------------------------
+
+export function applySettingValue({
+  key,
+  value,
+  configManager,
+  groups,
+  onSettingApplied,
+  refreshGroups,
+}: {
+  key: ConfigKey;
+  value: unknown;
+  configManager: ConfigManager;
+  groups: Map<string, SettingEntry[]>;
+  onSettingApplied: SettingAppliedCallback | null;
+  /** Called after applying the value so the caller can re-read currentValues. */
+  refreshGroups: () => void;
+}): ApplyValueResult {
+  const previousValue = configManager.get(key);
+  const isRestartKey = ['host', 'port', 'hostMode', 'enabled'].includes(key.split('.')[1] ?? '');
+
+  try {
+    configManager.setDynamic(key, value);
+  } catch (e) {
+    logger.error('SettingsModal: failed to set config value', { key, error: summarizeError(e) });
+    return {
+      restartDomain: null,
+      effectMessage: `Save failed: ${summarizeError(e)}`,
+      changed: false,
+    };
+  }
+
+  // Update the entry in the groups map
+  for (const entries of groups.values()) {
+    const entry = entries.find((candidate) => candidate.setting.key === key);
+    if (entry) {
+      entry.currentValue = configManager.get(key);
+      entry.isDefault = deepEqual(entry.currentValue, entry.setting.default);
+    }
+  }
+
+  // Determine restart domain
+  let restartDomain: 'control-plane' | 'http-listener' | 'web' | null = null;
+  if (previousValue !== value && isRestartKey) {
+    const rawCat = key.split('.')[0] as string;
+    if (rawCat === 'controlPlane') restartDomain = 'control-plane';
+    else if (rawCat === 'httpListener') restartDomain = 'http-listener';
+    else if (rawCat === 'web') restartDomain = 'web';
+  }
+
+  // Fire change callback
+  let effectMessage: string | null = null;
+  if (previousValue !== value && onSettingApplied) {
+    const result = onSettingApplied({ key, previousValue, value });
+    effectMessage = result?.message ?? null;
+    refreshGroups();
+  }
+
+  return { restartDomain, effectMessage, changed: previousValue !== value };
+}
+
+// ---------------------------------------------------------------------------
+// persistFlagState — write a flag override to config
+// ---------------------------------------------------------------------------
+
+export function persistFlagState(
+  configManager: ConfigManager,
+  flagId: string,
+  newState: FlagState,
+  defaultState: FlagState,
+): void {
+  if (newState === 'killed') return; // never persist killed state
+
+  try {
+    const current = (configManager.getCategory('featureFlags') as Record<string, PersistedFlagState>) ?? {};
+    if (newState === defaultState) {
+      delete current[flagId];
+    } else {
+      current[flagId] = newState;
+    }
+    configManager.mergeCategory('featureFlags', current);
+  } catch (e) {
+    logger.error('SettingsModal: failed to persist flag state', { flagId, error: summarizeError(e) });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// applyFlagState — toggle a feature flag (runtime + persist)
+// ---------------------------------------------------------------------------
+
+export function applyFlagState(
+  flagEntry: FlagEntry,
+  newState: FlagState,
+  featureFlagManager: FeatureFlagManager,
+  configManager: ConfigManager,
+): void {
+  const flag: FeatureFlag = flagEntry.flag;
+
+  if (!flag.runtimeToggleable) {
+    persistFlagState(configManager, flag.id, newState, flag.defaultState as FlagState);
+    flagEntry.state = newState;
+    return;
+  }
+
+  try {
+    if (newState === 'enabled') {
+      featureFlagManager.enable(flag.id);
+    } else {
+      featureFlagManager.disable(flag.id);
+    }
+    persistFlagState(configManager, flag.id, newState, flag.defaultState as FlagState);
+    flagEntry.state = newState;
+  } catch (e) {
+    logger.error('SettingsModal: failed to toggle feature flag', { flag: flag.id, error: summarizeError(e) });
+  }
+}