Squash Odysseus development history

static/js/settings/dom.js

@@ -0,0 +1,7 @@
+// Shared DOM helpers for the Settings modules.
+// Keep this module intentionally small so panel modules do not grow their own
+// element-lookup conventions as Settings is split out of settings.js.
+
+export function byId(id) {
+  return document.getElementById(id);
+}

static/js/settings/lifecycle.js

@@ -0,0 +1,176 @@
+// Settings modal lifecycle primitives.
+//
+// Panel-specific behavior belongs elsewhere. This module owns only the window
+// shell: dragging/docking reset, close semantics, visibility animation, and the
+// delegated link that leaves Settings for the Persona editor.
+
+import { makeWindowDraggable } from '../windowDrag.js';
+import { clearDockSide } from '../modalSnap.js';
+
+const _dragBound = new WeakSet();
+const _closeBound = new WeakSet();
+let _promptLinkBound = false;
+
+export function bindSettingsDrag(modalEl) {
+  if (!modalEl || _dragBound.has(modalEl)) return;
+
+  const header = modalEl.querySelector('.modal-header');
+  const content = modalEl.querySelector('.settings-modal-content');
+  if (!header || !content) return;
+
+  _dragBound.add(modalEl);
+  makeWindowDraggable(modalEl, {
+    content,
+    header,
+    skipSelector: 'button, input, select, .theme-opacity-wrap',
+    enableDock: true,
+  });
+}
+
+export function resetSettingsWindowPlacement(modalEl) {
+  const content = modalEl?.querySelector('.settings-modal-content');
+  if (!content) return;
+
+  const hadLeft = modalEl.classList.contains('modal-left-docked');
+  const hadRight = modalEl.classList.contains('modal-right-docked');
+  modalEl.classList.remove('modal-left-docked', 'modal-right-docked');
+  if (hadLeft) clearDockSide('left', modalEl);
+  if (hadRight) clearDockSide('right', modalEl);
+
+  if (content._leftDockNavObs) {
+    try { content._leftDockNavObs.navObs && content._leftDockNavObs.navObs.disconnect(); } catch (_) {}
+    try { window.removeEventListener('resize', content._leftDockNavObs.reanchor); } catch (_) {}
+    delete content._leftDockNavObs;
+  }
+
+  delete content._preDockSnapshot;
+  delete content._dockSide;
+  delete content._dockSuspended;
+  delete content.dataset._tilePreSnap;
+  delete content.dataset._tileZone;
+
+  [
+    'position', 'left', 'top', 'right', 'bottom', 'margin', 'transform',
+    'width', 'height', 'max-width', 'max-height', 'border-radius', 'transition',
+  ].forEach(property => content.style.removeProperty(property));
+}
+
+export function bindOpenPromptModalLink({ getModal, closeSettings } = {}) {
+  if (_promptLinkBound) return;
+  _promptLinkBound = true;
+
+  document.addEventListener('click', async event => {
+    const link = event.target?.closest?.('[data-open-prompt-modal]');
+    if (!link) return;
+    event.preventDefault();
+
+    const settingsModal = typeof getModal === 'function' ? getModal() : null;
+    if (
+      settingsModal
+      && !settingsModal.classList.contains('hidden')
+      && typeof closeSettings === 'function'
+    ) {
+      closeSettings();
+    }
+
+    try {
+      const module = await import('../presets.js?v=20260908personaname1');
+      const openPrompt = module.openCustomPresetModal
+        || (module.default && module.default.openCustomPresetModal);
+      if (typeof openPrompt === 'function') openPrompt();
+    } catch (_) {
+      const modal = document.getElementById('custom-preset-modal');
+      if (modal) modal.classList.remove('hidden');
+    }
+
+    const personaTab = document.querySelector(
+      '#custom-preset-modal .preset-tab[data-chartab="character"]'
+    );
+    if (personaTab) personaTab.click();
+  });
+}
+
+export function bindSettingsClose(modalEl, options = {}) {
+  if (!modalEl || _closeBound.has(modalEl)) return;
+  _closeBound.add(modalEl);
+
+  const closeSettings = options.closeSettings;
+  const isTouchInsideModal = options.isTouchInsideModal;
+
+  const closeButton = modalEl.querySelector('.close-btn');
+  closeButton?.addEventListener('click', () => {
+    if (typeof closeSettings === 'function') closeSettings();
+  });
+
+  modalEl.addEventListener('mousedown', event => {
+    if (typeof isTouchInsideModal === 'function' && isTouchInsideModal()) return;
+    if (event.target === modalEl && typeof closeSettings === 'function') {
+      closeSettings();
+    }
+  });
+
+  document.addEventListener('keydown', event => {
+    if (event.key !== 'Escape' || modalEl.classList.contains('hidden')) return;
+
+    // Esc should dismiss transient popovers before the Settings window.
+    const popoverOpen = modalEl.querySelector(
+      '#adm-epLocalMoreMenu, #adm-epApiMoreMenu, #adm-provider-menu, #search-provider-menu, [data-popover-open="1"]'
+    );
+    if (
+      popoverOpen
+      && popoverOpen.style.display !== 'none'
+      && !popoverOpen.classList.contains('hidden')
+    ) {
+      return;
+    }
+
+    // Integration/account editors are nested flows. Close the editor first so
+    // an accidental Esc does not discard the entire Settings context.
+    const innerForm = modalEl.querySelector('#unified-intg-form, #set-email-accounts-form');
+    if (
+      innerForm
+      && innerForm.style.display !== 'none'
+      && innerForm.children.length > 0
+    ) {
+      event.preventDefault();
+      event.stopPropagation();
+      innerForm.style.display = 'none';
+      innerForm.innerHTML = '';
+      return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    if (typeof closeSettings === 'function') closeSettings();
+  });
+}
+
+export function showSettingsModal(modalEl) {
+  if (!modalEl) return;
+  if (modalEl.classList.contains('hidden')) {
+    resetSettingsWindowPlacement(modalEl);
+  }
+  modalEl.classList.remove('hidden');
+}
+
+export function hideSettingsModal(modalEl) {
+  if (!modalEl) return;
+
+  const content = modalEl.querySelector('.modal-content, .settings-modal-content');
+  if (content && !content.classList.contains('modal-closing')) {
+    content.classList.add('modal-closing');
+    content.addEventListener('animationend', () => {
+      modalEl.classList.add('hidden');
+      content.classList.remove('modal-closing');
+    }, { once: true });
+    setTimeout(() => {
+      if (!modalEl.classList.contains('hidden')) {
+        modalEl.classList.add('hidden');
+        content.classList.remove('modal-closing');
+      }
+    }, 250);
+    return;
+  }
+
+  modalEl.classList.add('hidden');
+}

static/js/settings/navigation.js

@@ -0,0 +1,57 @@
+// Settings navigation primitives.
+//
+// This module owns panel activation and sidebar click routing only. Individual
+// panels continue to own their data loading and side effects.
+
+import { DEFAULT_SETTINGS_PANEL_ID, isAdminManagedSettingsTab } from './registry.js';
+
+const _boundModals = new WeakSet();
+
+export function activateSettingsPanel(modalEl, tab) {
+  if (!modalEl || !tab) return null;
+
+  modalEl.querySelectorAll('[data-settings-tab]').forEach(button => {
+    button.classList.toggle('active', button.dataset.settingsTab === tab);
+  });
+  modalEl.querySelectorAll('[data-settings-panel]').forEach(panel => {
+    panel.classList.toggle('hidden', panel.dataset.settingsPanel !== tab);
+  });
+  return tab;
+}
+
+export function getActiveSettingsTab(modalEl, fallback = DEFAULT_SETTINGS_PANEL_ID) {
+  if (!modalEl) return fallback;
+  const active = modalEl.querySelector('[data-settings-tab].active');
+  return active?.dataset?.settingsTab || fallback;
+}
+
+export function bindSettingsNavigation(modalEl, options = {}) {
+  if (!modalEl || _boundModals.has(modalEl)) return;
+  _boundModals.add(modalEl);
+
+  const openAdminTab = options.openAdminTab;
+  const onPanelActivated = options.onPanelActivated;
+
+  modalEl.querySelectorAll('[data-settings-tab]').forEach(button => {
+    button.addEventListener('click', () => {
+      const tab = button.dataset.settingsTab;
+      if (!tab) return;
+
+      // Preserve the existing lazy-admin path: when the admin module accepts
+      // the tab, it owns activation/rendering and the Settings shell does not
+      // perform a second local switch.
+      if (
+        isAdminManagedSettingsTab(tab)
+        && typeof openAdminTab === 'function'
+        && openAdminTab(tab, button) === true
+      ) {
+        return;
+      }
+
+      activateSettingsPanel(modalEl, tab);
+      if (typeof onPanelActivated === 'function') {
+        onPanelActivated(tab, button);
+      }
+    });
+  });
+}

static/js/settings/registry.js

@@ -0,0 +1,237 @@
+// Canonical metadata for the existing Settings information architecture.
+//
+// This module describes Settings; it does not render the sidebar, load panel
+// data, or own panel behavior. Keeping those concerns separate lets the
+// current markup remain stable while navigation/search code shares one source
+// of truth for panel identity and ownership.
+
+function defineGroup(definition) {
+  return Object.freeze({ ...definition });
+}
+
+function definePanel(definition) {
+  return Object.freeze({
+    controller: 'settings',
+    adminOnly: false,
+    ...definition,
+    keywords: Object.freeze([...(definition.keywords || [])]),
+  });
+}
+
+export const SETTINGS_GROUPS = Object.freeze([
+  defineGroup({
+    id: 'models',
+    label: 'Models & AI',
+  }),
+  defineGroup({
+    id: 'communications',
+    label: 'Communications',
+  }),
+  defineGroup({
+    id: 'experience',
+    label: 'Experience',
+  }),
+  defineGroup({
+    id: 'account',
+    label: 'Account',
+  }),
+  defineGroup({
+    id: 'administration',
+    label: 'Administration',
+    adminOnly: true,
+  }),
+]);
+
+// Order intentionally mirrors the existing Settings sidebar.
+export const SETTINGS_PANELS = Object.freeze([
+  definePanel({
+    id: 'services',
+    label: 'Add Models',
+    group: 'models',
+    controller: 'admin',
+    keywords: ['models', 'provider', 'endpoint'],
+  }),
+  definePanel({
+    id: 'added-models',
+    label: 'Added Models',
+    group: 'models',
+    controller: 'admin',
+    keywords: ['models', 'configured', 'provider', 'endpoint'],
+  }),
+  definePanel({
+    id: 'ai',
+    label: 'AI Defaults',
+    group: 'models',
+    keywords: ['ai', 'defaults', 'model', 'vision', 'image', 'tts', 'stt'],
+  }),
+  definePanel({
+    id: 'search',
+    label: 'Search',
+    group: 'models',
+    keywords: ['search', 'research', 'provider'],
+  }),
+
+  definePanel({
+    id: 'integrations',
+    label: 'Integrations',
+    group: 'communications',
+    controller: 'admin',
+    keywords: ['integrations', 'connections', 'services'],
+  }),
+  definePanel({
+    id: 'email',
+    label: 'Email',
+    group: 'communications',
+    keywords: ['email', 'imap', 'smtp', 'oauth'],
+  }),
+  definePanel({
+    id: 'reminders',
+    label: 'Reminders',
+    group: 'communications',
+    keywords: ['reminders', 'notifications', 'alerts'],
+  }),
+
+  definePanel({
+    id: 'appearance',
+    label: 'Appearance',
+    group: 'experience',
+    keywords: ['appearance', 'theme', 'font', 'density', 'peek'],
+  }),
+  definePanel({
+    id: 'shortcuts',
+    label: 'Shortcuts',
+    group: 'experience',
+    keywords: ['shortcuts', 'keyboard', 'hotkeys'],
+  }),
+
+  definePanel({
+    id: 'account',
+    label: 'Account',
+    group: 'account',
+    keywords: ['account', 'password', 'logout'],
+  }),
+
+  definePanel({
+    id: 'tools',
+    label: 'Agent Tools',
+    group: 'administration',
+    controller: 'admin',
+    adminOnly: true,
+    keywords: ['agent', 'tools'],
+  }),
+  definePanel({
+    id: 'users',
+    label: 'Users',
+    group: 'administration',
+    controller: 'admin',
+    adminOnly: true,
+    keywords: ['users', 'accounts', 'admin'],
+  }),
+  definePanel({
+    id: 'system',
+    label: 'System',
+    group: 'administration',
+    controller: 'admin',
+    adminOnly: true,
+    keywords: ['system', 'admin', 'server'],
+  }),
+]);
+
+export const DEFAULT_SETTINGS_PANEL_ID = 'services';
+
+const _panelsById = new Map(
+  SETTINGS_PANELS.map(panel => [panel.id, panel]),
+);
+
+export function getSettingsPanel(id) {
+  return _panelsById.get(String(id || '')) || null;
+}
+
+export function getSettingsPanelsForGroup(groupId) {
+  return SETTINGS_PANELS.filter(panel => panel.group === groupId);
+}
+
+export function isAdminManagedSettingsTab(id) {
+  return getSettingsPanel(id)?.controller === 'admin';
+}
+
+export function isAdminOnlySettingsTab(id) {
+  return getSettingsPanel(id)?.adminOnly === true;
+}
+
+export function getSettingsPanelSearchText(panelOrId) {
+  const panel = typeof panelOrId === 'string'
+    ? getSettingsPanel(panelOrId)
+    : panelOrId;
+
+  if (!panel) return '';
+
+  return [
+    panel.label,
+    ...(panel.keywords || []),
+  ].join(' ').toLowerCase();
+}
+
+function normalizeSettingsSearch(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, ' ');
+}
+
+export function searchSettingsPanels(query, options = {}) {
+  const normalized = normalizeSettingsSearch(query);
+  if (!normalized) return [];
+
+  const terms = normalized.split(' ');
+  const isAdmin = options.isAdmin === true;
+
+  return SETTINGS_PANELS.filter(panel => {
+    if (panel.adminOnly && !isAdmin) return false;
+
+    const haystack = getSettingsPanelSearchText(panel);
+    return terms.every(term => haystack.includes(term));
+  });
+}
+
+export function getSettingsRegistryIssues(modalEl) {
+  if (!modalEl) return ['Settings modal is unavailable'];
+
+  const tabIds = Array.from(
+    modalEl.querySelectorAll('[data-settings-tab]'),
+    element => element.dataset.settingsTab,
+  ).filter(Boolean);
+
+  const panelIds = Array.from(
+    modalEl.querySelectorAll('[data-settings-panel]'),
+    element => element.dataset.settingsPanel,
+  ).filter(Boolean);
+
+  const registryIds = SETTINGS_PANELS.map(panel => panel.id);
+  const issues = [];
+
+  const duplicates = ids => ids.filter(
+    (id, index) => ids.indexOf(id) !== index,
+  );
+
+  for (const id of new Set(duplicates(tabIds))) {
+    issues.push(`Duplicate Settings tab: ${id}`);
+  }
+  for (const id of new Set(duplicates(panelIds))) {
+    issues.push(`Duplicate Settings panel: ${id}`);
+  }
+
+  for (const id of registryIds) {
+    if (!tabIds.includes(id)) issues.push(`Registry tab missing from DOM: ${id}`);
+    if (!panelIds.includes(id)) issues.push(`Registry panel missing from DOM: ${id}`);
+  }
+
+  for (const id of tabIds) {
+    if (!registryIds.includes(id)) issues.push(`DOM tab missing from registry: ${id}`);
+  }
+  for (const id of panelIds) {
+    if (!registryIds.includes(id)) issues.push(`DOM panel missing from registry: ${id}`);
+  }
+
+  return issues;
+}

static/js/settings/search.js

@@ -0,0 +1,172 @@
+import {
+  SETTINGS_GROUPS,
+  getSettingsPanel,
+  searchSettingsPanels,
+} from './registry.js';
+
+const _boundModals = new WeakSet();
+
+function groupLabelFor(panel) {
+  const group = SETTINGS_GROUPS.find(candidate => candidate.id === panel.group);
+  return group?.label || '';
+}
+
+function clearResults(resultsEl) {
+  if (!resultsEl) return;
+  resultsEl.replaceChildren();
+  resultsEl.classList.add('hidden');
+}
+
+function getResultButtons(resultsEl) {
+  if (!resultsEl) return [];
+  return Array.from(resultsEl.querySelectorAll('[data-settings-search-result]'));
+}
+
+function setActiveResult(resultsEl, index) {
+  const buttons = getResultButtons(resultsEl);
+  if (!buttons.length) return -1;
+
+  let next = index;
+  if (next < 0) next = buttons.length - 1;
+  if (next >= buttons.length) next = 0;
+
+  buttons.forEach((button, buttonIndex) => {
+    const active = buttonIndex === next;
+    button.classList.toggle('active', active);
+    button.setAttribute('aria-selected', active ? 'true' : 'false');
+  });
+
+  if (typeof buttons[next].scrollIntoView === 'function') {
+    buttons[next].scrollIntoView({ block: 'nearest' });
+  }
+
+  return next;
+}
+
+export function bindSettingsSearch(modalEl, options = {}) {
+  if (!modalEl || _boundModals.has(modalEl)) return;
+
+  const input = modalEl.querySelector('#settings-nav-search');
+  const resultsEl = modalEl.querySelector('#settings-nav-search-results');
+
+  if (!input || !resultsEl) return;
+  _boundModals.add(modalEl);
+
+  const isAdmin = typeof options.isAdmin === 'function'
+    ? options.isAdmin
+    : () => false;
+
+  const openPanel = typeof options.openPanel === 'function'
+    ? options.openPanel
+    : () => {};
+
+  let activeIndex = -1;
+
+  function reset() {
+    input.value = '';
+    activeIndex = -1;
+    clearResults(resultsEl);
+  }
+
+  function activateResult(button) {
+    const panelId = button?.dataset?.settingsSearchResult;
+    if (!panelId || !getSettingsPanel(panelId)) return;
+
+    openPanel(panelId);
+    reset();
+  }
+
+  function render() {
+    const query = input.value.trim();
+    activeIndex = -1;
+    resultsEl.replaceChildren();
+
+    if (!query) {
+      resultsEl.classList.add('hidden');
+      return;
+    }
+
+    const matches = searchSettingsPanels(query, {
+      isAdmin: isAdmin(),
+    });
+
+    if (!matches.length) {
+      const empty = document.createElement('div');
+      empty.className = 'settings-search-empty';
+      empty.textContent = 'No settings found';
+      resultsEl.appendChild(empty);
+      resultsEl.classList.remove('hidden');
+      return;
+    }
+
+    for (const panel of matches) {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'settings-search-result';
+      button.setAttribute('data-settings-search-result', panel.id);
+      button.setAttribute('role', 'option');
+      button.setAttribute('aria-selected', 'false');
+
+      const label = document.createElement('span');
+      label.className = 'settings-search-result-label';
+      label.textContent = panel.label;
+
+      const group = document.createElement('span');
+      group.className = 'settings-search-result-group';
+      group.textContent = groupLabelFor(panel);
+
+      button.append(label, group);
+      button.addEventListener('click', () => activateResult(button));
+      resultsEl.appendChild(button);
+    }
+
+    resultsEl.classList.remove('hidden');
+  }
+
+  input.addEventListener('input', render);
+
+  input.addEventListener('focus', () => {
+    if (input.value.trim()) render();
+  });
+
+  input.addEventListener('keydown', event => {
+    const buttons = getResultButtons(resultsEl);
+
+    if (event.key === 'Escape') {
+      if (!input.value && resultsEl.classList.contains('hidden')) return;
+      event.preventDefault();
+      event.stopPropagation();
+      reset();
+      return;
+    }
+
+    if (!buttons.length) return;
+
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      activeIndex = setActiveResult(resultsEl, activeIndex + 1);
+      return;
+    }
+
+    if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      activeIndex = setActiveResult(resultsEl, activeIndex - 1);
+      return;
+    }
+
+    if (event.key === 'Enter') {
+      const target = buttons[activeIndex >= 0 ? activeIndex : 0];
+      if (!target) return;
+      event.preventDefault();
+      activateResult(target);
+    }
+  });
+
+  modalEl.addEventListener('mousedown', event => {
+    if (event.target === input || resultsEl.contains(event.target)) return;
+    clearResults(resultsEl);
+    activeIndex = -1;
+  });
+
+  return { reset, render };
+}

static/js/settings/sidebar.js

@@ -0,0 +1,238 @@
+const STORAGE_WIDTH = 'odysseus-settings-sidebar-width';
+const STORAGE_COLLAPSED = 'odysseus-settings-sidebar-collapsed';
+
+export const SETTINGS_SIDEBAR_DEFAULT_WIDTH = 220;
+export const SETTINGS_SIDEBAR_MIN_WIDTH = 150;
+export const SETTINGS_SIDEBAR_MAX_WIDTH = 340;
+export const SETTINGS_SIDEBAR_COLLAPSE_THRESHOLD = 110;
+
+const _bound = new WeakSet();
+
+function clampWidth(value) {
+  const width = Number(value);
+  if (!Number.isFinite(width)) return SETTINGS_SIDEBAR_DEFAULT_WIDTH;
+  return Math.max(
+    SETTINGS_SIDEBAR_MIN_WIDTH,
+    Math.min(SETTINGS_SIDEBAR_MAX_WIDTH, width),
+  );
+}
+
+function readStoredWidth() {
+  try {
+    const stored = localStorage.getItem(STORAGE_WIDTH);
+    if (stored == null || String(stored).trim() === '') {
+      return SETTINGS_SIDEBAR_DEFAULT_WIDTH;
+    }
+    return clampWidth(stored);
+  } catch {
+    return SETTINGS_SIDEBAR_DEFAULT_WIDTH;
+  }
+}
+
+function readStoredCollapsed() {
+  try {
+    return localStorage.getItem(STORAGE_COLLAPSED) === '1';
+  } catch {
+    return false;
+  }
+}
+
+function storeWidth(width) {
+  try {
+    localStorage.setItem(STORAGE_WIDTH, String(Math.round(width)));
+  } catch {}
+}
+
+function storeCollapsed(collapsed) {
+  try {
+    localStorage.setItem(STORAGE_COLLAPSED, collapsed ? '1' : '0');
+  } catch {}
+}
+
+function syncResizeHandleAria(modalEl, width = null) {
+  const handle = modalEl?.querySelector('#settings-sidebar-resize-handle');
+  if (!handle) return;
+
+  const sidebar = modalEl.querySelector('.settings-sidebar');
+  const collapsed = sidebar?.classList.contains('settings-sidebar-collapsed');
+
+  const current = collapsed
+    ? SETTINGS_SIDEBAR_MIN_WIDTH
+    : clampWidth(
+        width ?? sidebar?.getBoundingClientRect?.().width
+          ?? SETTINGS_SIDEBAR_DEFAULT_WIDTH
+      );
+
+  handle.setAttribute('aria-valuemin', String(SETTINGS_SIDEBAR_MIN_WIDTH));
+  handle.setAttribute('aria-valuemax', String(SETTINGS_SIDEBAR_MAX_WIDTH));
+  handle.setAttribute('aria-valuenow', String(Math.round(current)));
+}
+
+function isDesktopSidebarMode(modalEl) {
+  const content = modalEl?.querySelector('.settings-modal-content');
+  if (!content) return false;
+
+  // Mirrors the existing container breakpoint where the sidebar becomes a
+  // horizontal rail. Resizing/collapse applies only to the vertical desktop
+  // navigation layout.
+  return content.getBoundingClientRect().width > 620;
+}
+
+export function setSettingsSidebarCollapsed(modalEl, collapsed, options = {}) {
+  const sidebar = modalEl?.querySelector('.settings-sidebar');
+  if (!sidebar) return false;
+
+  const next = collapsed === true;
+  sidebar.classList.toggle('settings-sidebar-collapsed', next);
+
+  const toggle = sidebar.querySelector('#settings-sidebar-toggle');
+  if (toggle) {
+    toggle.setAttribute('aria-expanded', next ? 'false' : 'true');
+    toggle.setAttribute(
+      'aria-label',
+      next ? 'Expand settings navigation' : 'Collapse settings navigation',
+    );
+    toggle.title = next
+      ? 'Expand settings navigation'
+      : 'Collapse settings navigation';
+  }
+
+  if (!next) {
+    const width = clampWidth(options.width ?? readStoredWidth());
+    sidebar.style.setProperty('--settings-sidebar-width', `${width}px`);
+    syncResizeHandleAria(modalEl, width);
+  } else {
+    syncResizeHandleAria(modalEl);
+  }
+
+  if (options.persist !== false) storeCollapsed(next);
+  return next;
+}
+
+export function setSettingsSidebarWidth(modalEl, width, options = {}) {
+  const sidebar = modalEl?.querySelector('.settings-sidebar');
+  if (!sidebar) return null;
+
+  const next = clampWidth(width);
+  sidebar.style.setProperty('--settings-sidebar-width', `${next}px`);
+  syncResizeHandleAria(modalEl, next);
+
+  if (options.persist !== false) storeWidth(next);
+  return next;
+}
+
+export function bindSettingsSidebar(modalEl) {
+  if (!modalEl || _bound.has(modalEl)) return;
+  _bound.add(modalEl);
+
+  const sidebar = modalEl.querySelector('.settings-sidebar');
+  const handle = modalEl.querySelector('#settings-sidebar-resize-handle');
+  const toggle = modalEl.querySelector('#settings-sidebar-toggle');
+
+  if (!sidebar || !handle || !toggle) return;
+
+  setSettingsSidebarWidth(modalEl, readStoredWidth(), { persist: false });
+  setSettingsSidebarCollapsed(
+    modalEl,
+    readStoredCollapsed(),
+    { persist: false },
+  );
+
+  toggle.addEventListener('click', event => {
+    event.preventDefault();
+    event.stopPropagation();
+
+    if (!isDesktopSidebarMode(modalEl)) return;
+
+    const collapsed = sidebar.classList.contains('settings-sidebar-collapsed');
+    setSettingsSidebarCollapsed(modalEl, !collapsed);
+  });
+
+  let startX = 0;
+  let startWidth = 0;
+
+  function stopResize() {
+    if (!sidebar.classList.contains('settings-sidebar-resizing')) return;
+
+    sidebar.classList.remove('settings-sidebar-resizing');
+    document.body.classList.remove('settings-sidebar-resize-active');
+
+    window.removeEventListener('pointermove', onPointerMove);
+    window.removeEventListener('pointerup', stopResize);
+
+    const width = sidebar.getBoundingClientRect().width;
+    if (width < SETTINGS_SIDEBAR_COLLAPSE_THRESHOLD) {
+      setSettingsSidebarCollapsed(modalEl, true);
+      return;
+    }
+
+    setSettingsSidebarCollapsed(modalEl, false, { persist: false });
+    setSettingsSidebarWidth(modalEl, width);
+    storeCollapsed(false);
+  }
+
+  function onPointerMove(event) {
+    const rawWidth = startWidth + (event.clientX - startX);
+
+    if (rawWidth < SETTINGS_SIDEBAR_COLLAPSE_THRESHOLD) {
+      sidebar.style.setProperty(
+        '--settings-sidebar-width',
+        `${Math.max(34, rawWidth)}px`,
+      );
+      return;
+    }
+
+    setSettingsSidebarCollapsed(modalEl, false, { persist: false });
+    setSettingsSidebarWidth(modalEl, rawWidth, { persist: false });
+  }
+
+  handle.addEventListener('pointerdown', event => {
+    if (!isDesktopSidebarMode(modalEl)) return;
+
+    event.preventDefault();
+    startX = event.clientX;
+    startWidth = sidebar.getBoundingClientRect().width;
+
+    sidebar.classList.remove('settings-sidebar-collapsed');
+    sidebar.classList.add('settings-sidebar-resizing');
+    document.body.classList.add('settings-sidebar-resize-active');
+
+    window.addEventListener('pointermove', onPointerMove);
+    window.addEventListener('pointerup', stopResize);
+  });
+
+  handle.addEventListener('keydown', event => {
+    if (!isDesktopSidebarMode(modalEl)) return;
+
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      toggle.click();
+      return;
+    }
+
+    if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return;
+
+    event.preventDefault();
+
+    if (sidebar.classList.contains('settings-sidebar-collapsed')) {
+      setSettingsSidebarCollapsed(modalEl, false);
+    }
+
+    const current = sidebar.getBoundingClientRect().width;
+    const delta = event.key === 'ArrowLeft' ? -16 : 16;
+
+    // Once keyboard resizing reaches the declared minimum, another ArrowLeft
+    // collapses the rail. Without this explicit boundary transition the width
+    // setter clamps 134px back to 150px forever, making keyboard collapse via
+    // ArrowLeft unreachable.
+    if (
+      event.key === 'ArrowLeft'
+      && current <= SETTINGS_SIDEBAR_MIN_WIDTH
+    ) {
+      setSettingsSidebarCollapsed(modalEl, true);
+      return;
+    }
+
+    setSettingsSidebarWidth(modalEl, current + delta);
+  });
+}