// Shared JSDoc typedefs for the Sidebar panel system (H4 modularization).
//
// `Sidebar.js` is a thin orchestrator: it builds ONE `PanelContext` and passes it
// to every `buildXPanel(ctx)` / `wireXPanel(ctx)`. Panels read and write shared
// state through this context — NOT through module-level closure globals — and
// publish their cross-panel refresh functions into `ctx.refresh` so other panels
// can invoke them (e.g. the relief panel refreshing the model panel).
//
// No TypeScript: these typedefs exist only to give the editor and AI agents an
// explicit contract.

/**
 * Cross-panel refresh registry. Each panel assigns its own refresh closures here
 * during wiring; other panels invoke them defensively (`ctx.refresh.modelPanel?.()`).
 * Several are also mirrored onto `window.*` because `visualizer/DimensionInspector.js`
 * reaches the sidebar through that seam.
 *
 * @typedef {Object} PanelRefreshRegistry
 * @property {(selectFileAfterLoad?: string) => Promise<void>} [reliefFiles] - Reload the indexed-PDF selector + per-model cache (ReliefPanel). Mirrors nothing but calls modelPanel/inspector.
 * @property {() => void} [modelPanel] - Repopulate the multi-model selector + active badge (ModelPanel).
 * @property {() => void} [modelCacheStatus] - Recompute the per-document model cache hint (ModelPanel).
 * @property {() => void} [docList] - Re-render the active relief-document list (ReliefPanel). Mirrored to `window.sidebarRefreshDocs`.
 * @property {() => void} [dimList] - Re-render the Mode-C inspected-dimension list (ReliefPanel). Mirrored to `window.sidebarRefreshDims`.
 * @property {() => void} [comparisonModeUI] - Toggle the A/B/C comparison sub-controls (ReliefPanel).
 * @property {() => void} [subModeUI] - Apply THREADS/RELIEF sub-mode visibility (ReliefPanel).
 * @property {() => Promise<void>} [saeStatus] - Refresh the SAE space toggle + metrics (SaeMetricsPanel).
 */

/**
 * The single contract every panel receives. Built once by `createSidebar()`.
 *
 * @typedef {Object} PanelContext
 * @property {typeof import('../core/State.js').STATE} STATE - Reactive global state (setters in State.js).
 * @property {typeof import('../core/State.js').CONFIG} CONFIG - Reactive global config.
 * @property {(query: string, append: boolean) => void} onScan - Add a token/sentence to the 3D space.
 * @property {(criteria: {tokenIndex: string|number, operator: string, value: number, limit: number}) => void} onHunterQuery - Run the Signal Hunter scan.
 * @property {(a: string, b: string, c: string, topK: number) => void} onCalculate - Run vector arithmetic (A − B + C).
 * @property {(lines: string[]) => void} onBatchLoad - Batch-load tokens from a text file.
 * @property {() => void} onClearAll - Remove all active threads.
 * @property {() => void} applyComparison - Single entry point that renders the active comparison mode (A/B 3D, C inspector).
 * @property {(opts: ModalOptions) => void} showCustomModal - Shared modal overlay util.
 * @property {(dimIndex: number) => void} showNamingModal - AI dimension-naming modal (Phase 2).
 * @property {PanelRefreshRegistry} refresh - Cross-panel refresh registry.
 */

/**
 * Options accepted by {@link showCustomModal}.
 *
 * @typedef {Object} ModalOptions
 * @property {string} title - Modal header text.
 * @property {string} contentHTML - Body markup (trusted, local).
 * @property {(overlay: HTMLElement) => void} [onConfirm] - Confirm-button handler; receives the overlay element.
 * @property {() => void} [onCancel] - Cancel/close handler.
 * @property {string} [confirmText] - Confirm button label (default "Confirm").
 * @property {string} [cancelText] - Cancel button label (default "Cancel").
 * @property {boolean} [isAlert] - Alert mode: single button + close-X, no cancel.
 */

export {};