@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/ui-hooks/index.d.mts

@@ -0,0 +1,1915 @@
+import * as _$react from "react";
+import { ComponentType, JSX, ReactNode } from "react";
+import { PreferenceKey } from "@makaio/framework/services/preferences";
+import { AdapterInfo, ComponentLike, NavigationGroupConfig, OnboardingContext, OnboardingStepDefinition as OnboardingStepDefinition$1, OnboardingStepProps as OnboardingStepProps$1, PageComponentProps, PageDefinition, PageDefinitionQueryOptions, RuntimeReadyWaiter, WidgetDefinition, WidgetLayout, WidgetScope } from "@makaio/framework/ui-kernel";
+import { ExtensionInfo } from "@makaio/framework/kernel";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { AIModel, AgentSelection, ModelFilterMode, ModelVisibility, UiContextSnapshot, UiRuntimeNavigationLevel, UiScope } from "@makaio/framework/contracts";
+import { BindingRecord, ProviderConfigFileRecord } from "@makaio/framework/services/adapter-subsystem";
+import { LogImportMode } from "@makaio/framework/services/log-import/log-import";
+import { EventHandler, EventMessagePayload, ExtractSubjectPayload, SubjectDefinition } from "@makaio/framework/core";
+import { CredentialRef } from "@makaio/framework/contracts/config";
+import { ModelFilterMode as ModelFilterMode$1, ModelVisibility as ModelVisibility$1, ProtocolEndpoints, ProtocolId } from "@makaio/framework/contracts/provider";
+
+//#region ui/hooks/src/bus/bus-provider.d.ts
+/**
+ * React context carrying the active bus instance.
+ *
+ * Components must be rendered inside a `BusProvider` to access this context.
+ */
+declare const BusContext: _$react.Context<IMakaioBus | null>;
+/**
+ * Props for {@link BusProvider}.
+ */
+interface BusProviderProps {
+  /**
+   * Pre-connected bus instance to expose via context.
+   *
+   * Required so framework surfaces make their bus bootstrap explicit instead of
+   * silently falling back to the global singleton.
+   */
+  bus: IMakaioBus;
+  /** React children rendered inside the bus context. */
+  children: ReactNode;
+}
+/**
+ * Provides the connected `IMakaioBus` instance to the React component tree.
+ *
+ * The bus transport must be established before this component mounts.
+ * On the Electron path, pass the `MakaioBus` singleton after calling
+ * `MakaioBus.connect()` in the bootstrap function.
+ * @param props - Provider configuration.
+ * @returns React provider wrapping children with the active bus context.
+ */
+declare function BusProvider({
+  bus,
+  children
+}: BusProviderProps): JSX.Element;
+/**
+ * Hook to access the bus instance from React context.
+ *
+ * Must be called inside a component tree that is wrapped in `BusProvider`.
+ * @returns The active `IMakaioBus` instance.
+ * @throws When called outside a `BusProvider`.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const bus = useBus();
+ *   const handleClick = () => void bus.emit(MySubjects.clicked, {});
+ *   return <button onClick={handleClick}>Click</button>;
+ * }
+ * ```
+ */
+declare function useBus(): IMakaioBus;
+/**
+ * Hook to optionally access the bus instance from React context.
+ *
+ * Unlike {@link useBus}, this hook does not throw when called outside a
+ * `BusProvider`. It returns `null` when no provider is mounted, allowing
+ * components to degrade gracefully rather than crash.
+ *
+ * Use this for components that can meaningfully render without a bus (e.g.
+ * by disabling interactive affordances). Prefer {@link useBus} for components
+ * that have no useful state without a bus.
+ * @returns The active `IMakaioBus` instance, or `null` if no provider is mounted.
+ */
+declare function useOptionalBus(): IMakaioBus | null;
+//#endregion
+//#region ui/hooks/src/bus/use-bus-query.d.ts
+/**
+ * Options for {@link useBusQuery}.
+ * @typeParam Subject - The bus subject definition for the request.
+ */
+interface UseBusQueryOptions<Subject extends SubjectDefinition> {
+  /**
+   * The bus subject definition representing the request to execute.
+   *
+   * Must be a request-type subject (one with `request` and `response` fields).
+   */
+  readonly subject: Subject;
+  /**
+   * The payload to send with the request.
+   *
+   * Must be JSON-serializable so it can be used as a stable effect dependency.
+   */
+  readonly request: Subject['$meta']['payload'] extends {
+    request: infer Request;
+  } ? Request : never;
+  /**
+   * When `true`, the query is not sent and any previously loaded data is retained.
+   *
+   * Toggling from `true` back to `false` triggers an immediate refetch.
+   * @defaultValue false
+   */
+  readonly skip?: boolean;
+  /**
+   * Optional list of event subjects whose emission should trigger a refetch.
+   *
+   * Each subject in the array is subscribed to when the hook mounts. When any
+   * of those events fire the query is re-executed automatically.
+   */
+  readonly refetchOn?: readonly SubjectDefinition[];
+}
+/**
+ * Result returned by {@link useBusQuery}.
+ * @typeParam Response - The response payload type from the bus subject.
+ */
+interface UseBusQueryResult<Response> {
+  /** The most recently resolved response, or `undefined` before the first successful fetch. */
+  readonly data: Response | undefined;
+  /** `true` while a request is in flight. */
+  readonly loading: boolean;
+  /** Set when the most recent request threw or the bus returned an error. */
+  readonly error: Error | undefined;
+  /**
+   * Imperatively trigger a refetch regardless of the current `skip` flag.
+   *
+   * The `skip` guard is bypassed: if you call `refetch()` while `skip` is `true`
+   * the request is still sent.
+   */
+  readonly refetch: () => void;
+}
+/**
+ * Query a bus request subject and expose the result as React state.
+ *
+ * The hook fires an async bus request on mount and re-fires whenever `subject`,
+ * `request`, or `skip` change. Use `refetchOn` to subscribe to bus events that
+ * should invalidate the cached result and trigger a fresh request.
+ * @param options - Query configuration.
+ * @returns Reactive query state including data, loading, error, and a manual refetch callback.
+ * @example
+ * ```tsx
+ * const { data, loading, error } = useBusQuery({
+ *   subject: MyNamespace.subjects.getItem,
+ *   request: { id: itemId },
+ *   refetchOn: [MyNamespace.subjects.itemChanged],
+ * });
+ * ```
+ */
+declare function useBusQuery<Subject extends SubjectDefinition>({
+  subject,
+  request,
+  skip,
+  refetchOn
+}: UseBusQueryOptions<Subject>): UseBusQueryResult<Subject['$meta']['payload'] extends {
+  response: infer Response;
+} ? Response : never>;
+//#endregion
+//#region ui/hooks/src/bus/use-bus-event.d.ts
+type NonChannelEventSubjectDefinition = SubjectDefinition & {
+  readonly $meta: {
+    readonly channel: false;
+    readonly isRequest: false;
+    readonly payload: EventMessagePayload;
+  };
+};
+type HandlerForBusEvent<Subject extends NonChannelEventSubjectDefinition> = EventHandler<ExtractSubjectPayload<Subject>>;
+/**
+ * Subscribe to a bus event subject for the lifetime of the component.
+ *
+ * The subscription is established once on mount (and whenever `bus` or
+ * `subject` change). Passing a new `handler` reference on re-render does
+ * NOT cause an unsubscribe/resubscribe — the latest handler is always called.
+ *
+ * This pattern ensures that closures capturing component state stay fresh
+ * without the overhead of re-registering on every render.
+ * @param subject - The event subject definition to subscribe to.
+ * @param handler - The event handler to invoke when the subject fires.
+ * @example
+ * ```tsx
+ * useBusEvent(SessionNamespace.subjects.messageAdded, (ctx) => {
+ *   setMessages((prev) => [...prev, ctx.payload]);
+ * });
+ * ```
+ */
+declare function useBusEvent<Subject extends NonChannelEventSubjectDefinition>(subject: Subject, handler: HandlerForBusEvent<Subject>): void;
+//#endregion
+//#region ui/hooks/src/widgets/hooks.d.ts
+interface UseWidgetsOptions {
+  builtIns?: readonly WidgetDefinition[];
+  scope?: WidgetScope;
+  includeAny?: boolean;
+}
+interface UseWidgetsResult {
+  builtInWidgets: readonly WidgetDefinition[];
+  loading: boolean;
+  widgets: ReadonlyArray<WidgetDefinition> | undefined;
+}
+/**
+ * Register built-in widgets once and subscribe to runtime widget registrations.
+ * @param options - Built-in registration and scope-filter options.
+ * @returns Registered built-ins plus the current widget list for the requested scope.
+ */
+declare function useWidgets(options?: UseWidgetsOptions): UseWidgetsResult;
+interface UseWidgetRegistryOptions {
+  scope?: WidgetScope;
+  includeAny?: boolean;
+}
+/**
+ * Read registered widgets reactively from the shared widget registry.
+ * @param options - Optional scope filter and include-any behavior.
+ * @returns Widget definitions matching the requested scope.
+ */
+declare function useWidgetRegistry(options?: UseWidgetRegistryOptions): ReadonlyArray<WidgetDefinition>;
+interface UseWidgetConfigOptions<TConfig extends Record<string, unknown>> {
+  paneId: string;
+  widgetId: string;
+  context: WidgetLayoutContext;
+  surface: 'ui' | 'app';
+  defaultConfig: TConfig;
+}
+interface UseWidgetConfigResult<TConfig extends Record<string, unknown>> {
+  config: TConfig;
+  updateConfig: (partial: Partial<TConfig>) => void;
+}
+interface WidgetLayoutContext {
+  readonly scope: UiScope;
+  readonly contextId?: string | null;
+}
+/**
+ * Load and persist widget instance configuration through preferences.
+ * @param options - Widget identity plus default configuration.
+ * @returns Current widget config and a partial-update helper.
+ */
+declare function useWidgetConfig<TConfig extends Record<string, unknown>>(options: UseWidgetConfigOptions<TConfig>): UseWidgetConfigResult<TConfig>;
+//#endregion
+//#region ui/hooks/src/widgets/use-widget-layout.d.ts
+/**
+ * Load a widget layout preference and expose its fetch state.
+ * @param preferenceKey - Preference key that identifies the layout.
+ * @returns The current layout value plus loading, error, and refresh state.
+ */
+declare function useWidgetLayout(preferenceKey: PreferenceKey): {
+  layout: WidgetLayout | null;
+  isLoading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+};
+//#endregion
+//#region ui/hooks/src/widgets/use-widget-layout-actions.d.ts
+/**
+ * Persist or reset widget layouts in preferences.
+ * @returns Layout mutation helpers bound to the current bus instance.
+ */
+declare function useWidgetLayoutActions(): {
+  saveLayout: (key: PreferenceKey, layout: WidgetLayout) => Promise<void>;
+  resetLayout: (key: PreferenceKey) => Promise<void>;
+};
+//#endregion
+//#region ui/hooks/src/widgets/use-tray-layout.d.ts
+/**
+ * Derive a read-only `WidgetLayout` for the tray surface from the live widget registry.
+ * @param lockedWidgetIds - Widget IDs that should be pinned at the top of the tray.
+ * @returns Stable tray layout derived from the current widget registry snapshot.
+ */
+declare function useTrayLayout(lockedWidgetIds?: readonly string[]): WidgetLayout;
+//#endregion
+//#region ui/hooks/src/extensions/shared-browser-loader.d.ts
+type SharedLoaderState = 'loading' | 'ready' | 'empty' | 'error';
+interface SharedShellContribution<TShellProps> {
+  component: ComponentType<TShellProps>;
+}
+interface SharedExtensionBrowserContribution<TShellProps> {
+  shell?: SharedShellContribution<TShellProps>;
+  destroy?: () => void;
+}
+interface SharedFactoryResolution<TContribution> {
+  kind: 'resolved' | 'invalid';
+  factory?: (context: SharedBrowserFactoryContext) => TContribution | null | undefined;
+  reason?: string;
+}
+interface SharedBrowserFactoryContext {
+  bus: IMakaioBus;
+}
+interface ExtensionBrowserLoadResult<TShellProps> {
+  cleanups: Array<() => void>;
+  errorMessage: string | null;
+  shell: ComponentType<TShellProps> | null;
+  state: Exclude<SharedLoaderState, 'loading'>;
+}
+interface ExtensionBrowserLoadOptions<TContribution extends SharedExtensionBrowserContribution<TShellProps>, TShellProps, TFactory> {
+  bus: IMakaioBus;
+  getRegisteredFactory: (extensionName: string) => TFactory | undefined;
+  importModule?: (entrypointPath: string) => Promise<{
+    default?: unknown;
+  }>;
+  isCurrentRun: () => boolean;
+  registerExtensionUI: (bus: IMakaioBus, extensionName: string, contribution: TContribution) => () => void;
+  resolveFactory: (moduleDefault: unknown, registeredFactory: TFactory | undefined) => SharedFactoryResolution<TContribution>;
+  unregisterFactory: (extensionName: string) => void;
+  waitForRuntimeReady: (bus: IMakaioBus) => RuntimeReadyWaiter;
+}
+/**
+ * Load and register browser extension contributions for a renderer surface.
+ *
+ * Centralizes the runtime wait, extension discovery, secure browser import,
+ * contribution registration, and shell selection logic. Callers retain
+ * ownership of local registries and registration adapters via the injected
+ * callbacks so this seam removes orchestration duplication without collapsing
+ * framework and host ownership boundaries.
+ * @param options - Loader dependencies owned by the caller surface.
+ * @returns Final loader state, selected shell, and teardown callbacks.
+ */
+declare function loadExtensionBrowserContributions<TContribution extends SharedExtensionBrowserContribution<TShellProps>, TShellProps, TFactory>(options: ExtensionBrowserLoadOptions<TContribution, TShellProps, TFactory>): Promise<ExtensionBrowserLoadResult<TShellProps>>;
+//#endregion
+//#region node_modules/zustand/esm/vanilla.d.mts
+type SetStateInternal<T> = {
+  _(partial: T | Partial<T> | {
+    _(state: T): T | Partial<T>;
+  }['_'], replace?: false): void;
+  _(state: T | {
+    _(state: T): T;
+  }['_'], replace: true): void;
+}['_'];
+interface StoreApi<T> {
+  setState: SetStateInternal<T>;
+  getState: () => T;
+  getInitialState: () => T;
+  subscribe: (listener: (state: T, prevState: T) => void) => () => void;
+}
+type ExtractState<S> = S extends {
+  getState: () => infer T;
+} ? T : never;
+type Get<T, K, F> = K extends keyof T ? T[K] : F;
+type Mutate<S, Ms> = number extends Ms['length' & keyof Ms] ? S : Ms extends [] ? S : Ms extends [[infer Mi, infer Ma], ...infer Mrs] ? Mutate<StoreMutators<S, Ma>[Mi & StoreMutatorIdentifier], Mrs> : never;
+type StateCreator<T, Mis extends [StoreMutatorIdentifier, unknown][] = [], Mos extends [StoreMutatorIdentifier, unknown][] = [], U = T> = ((setState: Get<Mutate<StoreApi<T>, Mis>, 'setState', never>, getState: Get<Mutate<StoreApi<T>, Mis>, 'getState', never>, store: Mutate<StoreApi<T>, Mis>) => U) & {
+  $$storeMutators?: Mos;
+};
+interface StoreMutators<S, A> {}
+type StoreMutatorIdentifier = keyof StoreMutators<unknown, unknown>;
+//#endregion
+//#region node_modules/zustand/esm/react.d.mts
+type ReadonlyStoreApi<T> = Pick<StoreApi<T>, 'getState' | 'getInitialState' | 'subscribe'>;
+type UseBoundStore<S extends ReadonlyStoreApi<unknown>> = {
+  (): ExtractState<S>;
+  <U>(selector: (state: ExtractState<S>) => U): U;
+} & S;
+//#endregion
+//#region node_modules/zustand/esm/middleware/redux.d.mts
+type Write$3<T, U> = Omit<T, keyof U> & U;
+type StoreRedux<A> = {
+  dispatch: (a: A) => A;
+  dispatchFromDevtools: true;
+};
+type WithRedux<S, A> = Write$3<S, StoreRedux<A>>;
+declare module '../vanilla.mjs' {
+  interface StoreMutators<S, A> {
+    'zustand/redux': WithRedux<S, A>;
+  }
+}
+//#endregion
+//#region node_modules/zustand/esm/middleware/devtools.d.mts
+declare module '../vanilla.mjs' {
+  interface StoreMutators<S, A> {
+    'zustand/devtools': WithDevtools<S>;
+  }
+}
+type Cast<T, U> = T extends U ? T : U;
+type Write$2<T, U> = Omit<T, keyof U> & U;
+type TakeTwo<T> = T extends {
+  length: 0;
+} ? [undefined, undefined] : T extends {
+  length: 1;
+} ? [...args0: Cast<T, unknown[]>, arg1: undefined] : T extends {
+  length: 0 | 1;
+} ? [...args0: Cast<T, unknown[]>, arg1: undefined] : T extends {
+  length: 2;
+} ? T : T extends {
+  length: 1 | 2;
+} ? T : T extends {
+  length: 0 | 1 | 2;
+} ? T : T extends [infer A0, infer A1, ...unknown[]] ? [A0, A1] : T extends [infer A0, (infer A1)?, ...unknown[]] ? [A0, A1?] : T extends [(infer A0)?, (infer A1)?, ...unknown[]] ? [A0?, A1?] : never;
+type WithDevtools<S> = Write$2<S, StoreDevtools<S>>;
+type Action = string | {
+  type: string;
+  [x: string | number | symbol]: unknown;
+};
+type StoreDevtools<S> = S extends {
+  setState: {
+    (...args: infer Sa1): infer Sr1;
+    (...args: infer Sa2): infer Sr2;
+  };
+} ? {
+  setState(...args: [...args: TakeTwo<Sa1>, action?: Action]): Sr1;
+  setState(...args: [...args: TakeTwo<Sa2>, action?: Action]): Sr2;
+  devtools: {
+    cleanup: () => void;
+  };
+} : never;
+//#endregion
+//#region node_modules/zustand/esm/middleware/subscribeWithSelector.d.mts
+type Write$1<T, U> = Omit<T, keyof U> & U;
+type WithSelectorSubscribe<S> = S extends {
+  getState: () => infer T;
+} ? Write$1<S, StoreSubscribeWithSelector<T>> : never;
+declare module '../vanilla.mjs' {
+  interface StoreMutators<S, A> {
+    ['zustand/subscribeWithSelector']: WithSelectorSubscribe<S>;
+  }
+}
+type StoreSubscribeWithSelector<T> = {
+  subscribe: {
+    (listener: (selectedState: T, previousSelectedState: T) => void): () => void;
+    <U>(selector: (state: T) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+      equalityFn?: (a: U, b: U) => boolean;
+      fireImmediately?: boolean;
+    }): () => void;
+  };
+};
+//#endregion
+//#region node_modules/zustand/esm/middleware/persist.d.mts
+type StorageValue<S> = {
+  state: S;
+  version?: number;
+};
+interface PersistStorage<S, R = unknown> {
+  getItem: (name: string) => StorageValue<S> | null | Promise<StorageValue<S> | null>;
+  setItem: (name: string, value: StorageValue<S>) => R;
+  removeItem: (name: string) => R;
+}
+interface PersistOptions<S, PersistedState = S, PersistReturn = unknown> {
+  /** Name of the storage (must be unique) */
+  name: string;
+  /**
+   * Use a custom persist storage.
+   *
+   * Combining `createJSONStorage` helps creating a persist storage
+   * with JSON.parse and JSON.stringify.
+   *
+   * @default createJSONStorage(() => window.localStorage)
+   */
+  storage?: PersistStorage<PersistedState, PersistReturn> | undefined;
+  /**
+   * Filter the persisted value.
+   *
+   * @params state The state's value
+   */
+  partialize?: (state: S) => PersistedState;
+  /**
+   * A function returning another (optional) function.
+   * The main function will be called before the state rehydration.
+   * The returned function will be called after the state rehydration or when an error occurred.
+   */
+  onRehydrateStorage?: (state: S) => ((state?: S, error?: unknown) => void) | void;
+  /**
+   * If the stored state's version mismatch the one specified here, the storage will not be used.
+   * This is useful when adding a breaking change to your store.
+   */
+  version?: number;
+  /**
+   * A function to perform persisted state migration.
+   * This function will be called when persisted state versions mismatch with the one specified here.
+   */
+  migrate?: (persistedState: unknown, version: number) => PersistedState | Promise<PersistedState>;
+  /**
+   * A function to perform custom hydration merges when combining the stored state with the current one.
+   * By default, this function does a shallow merge.
+   */
+  merge?: (persistedState: unknown, currentState: S) => S;
+  /**
+   * An optional boolean that will prevent the persist middleware from triggering hydration on initialization,
+   * This allows you to call `rehydrate()` at a specific point in your apps rendering life-cycle.
+   *
+   * This is useful in SSR application.
+   *
+   * @default false
+   */
+  skipHydration?: boolean;
+}
+type PersistListener<S> = (state: S) => void;
+type StorePersist<S, Ps, Pr> = S extends {
+  getState: () => infer T;
+  setState: {
+    (...args: infer Sa1): infer Sr1;
+    (...args: infer Sa2): infer Sr2;
+  };
+} ? {
+  setState(...args: Sa1): Sr1 | Pr;
+  setState(...args: Sa2): Sr2 | Pr;
+  persist: {
+    setOptions: (options: Partial<PersistOptions<T, Ps, Pr>>) => void;
+    clearStorage: () => void;
+    rehydrate: () => Promise<void> | void;
+    hasHydrated: () => boolean;
+    onHydrate: (fn: PersistListener<T>) => () => void;
+    onFinishHydration: (fn: PersistListener<T>) => () => void;
+    getOptions: () => Partial<PersistOptions<T, Ps, Pr>>;
+  };
+} : never;
+declare module '../vanilla.mjs' {
+  interface StoreMutators<S, A> {
+    'zustand/persist': WithPersist<S, A>;
+  }
+}
+type Write<T, U> = Omit<T, keyof U> & U;
+type WithPersist<S, A> = Write<S, StorePersist<S, A, unknown>>;
+//#endregion
+//#region ui/hooks/src/state/create-persisted-store.d.ts
+/**
+ * Storage engine selection.
+ *
+ * - `'sessionStorage'` – tab-scoped; cleared when the tab is closed.
+ * - `'localStorage'`  – cross-tab; survives browser restart.
+ */
+type StorageType = 'sessionStorage' | 'localStorage';
+/**
+ * SSR-safe no-op storage used when the requested browser storage is unavailable
+ * (e.g., server-side rendering, private-browsing mode, or unit tests).
+ */
+declare const noopStorage: Storage;
+/**
+ * Configuration options for `createPersistedStore`.
+ * @typeParam T - The Zustand state type.
+ */
+interface PersistedStoreConfig<T> {
+  /**
+   * Unique storage key (e.g., `'makaio-agent-selection'`).
+   * Must be globally unique across all stores.
+   */
+  name: string;
+  /**
+   * Which browser storage to use.
+   * Defaults to `'sessionStorage'`.
+   */
+  storage?: StorageType;
+  /**
+   * Schema version for migrations.
+   * Increment when persisted shape changes; supply a `migrate` function in
+   * `extraPersistOptions` when doing so.
+   */
+  version?: number;
+  /**
+   * Subset of state to persist.
+   * When omitted the full state is persisted.
+   * @param state - Full store state.
+   * @returns Partial state to write to storage.
+   */
+  partialize?: PersistOptions<T, Partial<T>>['partialize'];
+  /**
+   * Custom merge function for rehydration.
+   * Useful for schema migrations that need to clean up persisted data.
+   * @param persistedState - Data read from storage (possibly stale shape).
+   * @param currentState - Current in-memory state (initial values).
+   * @returns Merged state.
+   */
+  merge?: (persistedState: unknown, currentState: T) => T;
+  /**
+   * Extra persist options forwarded verbatim to the Zustand `persist`
+   * middleware. Use this for advanced options such as `onRehydrateStorage` or
+   * `migrate`. Values here take precedence over other config fields when there
+   * is a key conflict (except `name` and `storage`, which are always set by
+   * this factory).
+   */
+  extraPersistOptions?: Omit<PersistOptions<T>, 'name' | 'storage'>;
+}
+/**
+ * Factory that creates a Zustand store with Zustand `persist` middleware
+ * pre-configured.
+ *
+ * All framework stores that need persistence should use this factory instead of
+ * calling `create(persist(...))` directly. This keeps the boilerplate in one
+ * place and guarantees SSR-safe storage resolution everywhere.
+ * @param stateCreator - Zustand state creator (same as the first arg to `create`).
+ * @param config - Persistence configuration for this store.
+ * @returns A Zustand store hook identical to what `create()` returns.
+ * @example
+ * ```ts
+ * export const useMyStore = createPersistedStore<MyState>(
+ *   (set) => ({
+ *     count: 0,
+ *     increment: () => set((s) => ({ count: s.count + 1 })),
+ *   }),
+ *   { name: 'makaio-my-store', storage: 'sessionStorage' },
+ * );
+ * ```
+ */
+declare function createPersistedStore<T>(stateCreator: StateCreator<T, [StoreMutatorIdentifier, unknown][], []>, config: PersistedStoreConfig<T>): UseBoundStore<Omit<StoreApi<T>, "setState" | "persist"> & {
+  setState(partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: false | undefined): unknown;
+  setState(state: T | ((state: T) => T), replace: true): unknown;
+  persist: {
+    setOptions: (options: Partial<PersistOptions<T, Partial<T>, unknown>>) => void;
+    clearStorage: () => void;
+    rehydrate: () => Promise<void> | void;
+    hasHydrated: () => boolean;
+    onHydrate: (fn: (state: T) => void) => () => void;
+    onFinishHydration: (fn: (state: T) => void) => () => void;
+    getOptions: () => Partial<PersistOptions<T, Partial<T>, unknown>>;
+  };
+}>;
+//#endregion
+//#region ui/hooks/src/state/window-context-store.d.ts
+interface WindowContextState {
+  /**
+   * The qualified desktop window registration ID for this tab, when the page is
+   * hosted inside a desktop shell (`{packageName}:{windowId}`). Null when
+   * running as a standalone browser tab.
+   *
+   * Set once during bootstrap from host-local runtime config. Never changes for
+   * the lifetime of the tab. Not persisted — always re-derived from the host
+   * config on each page load.
+   */
+  windowId: string | null;
+  /** Current host UI context snapshot for this tab. */
+  uiContext: UiContextSnapshot;
+  /**
+   * ID of the pane that most recently received user focus.
+   * Transient — not persisted. Resets to `null` on page load.
+   */
+  activePaneId: string | null;
+  /**
+   * Set the window registration ID (called once during bootstrap).
+   *
+   * Should only be called by the bootstrap function before React renders.
+   * After the first non-null write, subsequent calls with a different value
+   * are silently ignored — the ID is immutable for the tab's lifetime.
+   * Re-setting the same value (e.g. HMR re-bootstrap) is a no-op.
+   * @param id - The qualified desktop window registration ID, or null for standalone browser.
+   */
+  setWindowId: (id: string | null) => void;
+  /**
+   * Set the active host UI context snapshot.
+   * @param uiContext - UI context snapshot to store for this tab.
+   */
+  setUiContext: (uiContext: UiContextSnapshot) => void;
+  /**
+   * Sets the active pane.
+   *
+   * Called by PaneContainer on focus or pointer-down capture.
+   * @param id - Pane ID, or null to clear.
+   */
+  setActivePaneId: (id: string | null) => void;
+  /** Clear the UI context back to the framework root context. */
+  clearUiContext: () => void;
+}
+/**
+ * Tab-scoped window context store.
+ *
+ * Use this for navigation state and window-specific overrides:
+ * - Which host UI context is active in THIS window
+ * - Model/adapter overrides for THIS window
+ *
+ * Navigation level is read directly from `uiContext.level`.
+ */
+declare const useWindowContext: UseBoundStore<Omit<StoreApi<WindowContextState>, "setState" | "persist"> & {
+  setState(partial: WindowContextState | Partial<WindowContextState> | ((state: WindowContextState) => WindowContextState | Partial<WindowContextState>), replace?: false | undefined): unknown;
+  setState(state: WindowContextState | ((state: WindowContextState) => WindowContextState), replace: true): unknown;
+  persist: {
+    setOptions: (options: Partial<PersistOptions<WindowContextState, Partial<WindowContextState>, unknown>>) => void;
+    clearStorage: () => void;
+    rehydrate: () => Promise<void> | void;
+    hasHydrated: () => boolean;
+    onHydrate: (fn: (state: WindowContextState) => void) => () => void;
+    onFinishHydration: (fn: (state: WindowContextState) => void) => () => void;
+    getOptions: () => Partial<PersistOptions<WindowContextState, Partial<WindowContextState>, unknown>>;
+  };
+}>;
+//#endregion
+//#region ui/hooks/src/state/page-overlay-store.d.ts
+/**
+ * Page Overlay Store - Global page overlay state
+ *
+ * Manages the state of the PageOverlay system for IDE-like navigation to pages
+ * (Settings, Help, Plugin Config) as modal overlays that preserve workspace state.
+ * This is ephemeral UI state that persists to sessionStorage for tab isolation.
+ *
+ * Persisted to sessionStorage:
+ * - Tab survives refresh with overlay state preserved
+ * - Each tab has its own overlay state
+ * - Close tab = fresh start (no stale state)
+ * @packageDocumentation
+ */
+/**
+ * Page overlay state management.
+ */
+interface PageOverlayState {
+  /** Currently displayed page ID (null = closed) */
+  activePageId: string | null;
+  /** Internal route within the page */
+  internalRoute: string | null;
+  /**
+   * Open a page in the overlay.
+   * @param pageId - ID of the page to open (e.g., 'settings', 'help')
+   * @param route - Optional internal route within the page; defaults to null
+   */
+  openPage: (pageId: string, route?: string) => void;
+  /** Close the overlay */
+  close: () => void;
+  /**
+   * Navigate within the current page.
+   * @param route - New internal route
+   */
+  navigate: (route: string) => void;
+}
+/**
+ * Zustand store for PageOverlay state.
+ *
+ * Uses sessionStorage for tab-scoped persistence, ensuring each browser tab
+ * maintains its own overlay state independently.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const activePageId = usePageOverlayStore((s) => s.activePageId);
+ *   const openPage = usePageOverlayStore((s) => s.openPage);
+ *
+ *   return (
+ *     <button onClick={() => openPage('settings')}>
+ *       Open Settings
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const usePageOverlayStore: UseBoundStore<Omit<StoreApi<PageOverlayState>, "setState" | "persist"> & {
+  setState(partial: PageOverlayState | Partial<PageOverlayState> | ((state: PageOverlayState) => PageOverlayState | Partial<PageOverlayState>), replace?: false | undefined): unknown;
+  setState(state: PageOverlayState | ((state: PageOverlayState) => PageOverlayState), replace: true): unknown;
+  persist: {
+    setOptions: (options: Partial<PersistOptions<PageOverlayState, Partial<PageOverlayState>, unknown>>) => void;
+    clearStorage: () => void;
+    rehydrate: () => Promise<void> | void;
+    hasHydrated: () => boolean;
+    onHydrate: (fn: (state: PageOverlayState) => void) => () => void;
+    onFinishHydration: (fn: (state: PageOverlayState) => void) => () => void;
+    getOptions: () => Partial<PersistOptions<PageOverlayState, Partial<PageOverlayState>, unknown>>;
+  };
+}>;
+//#endregion
+//#region ui/hooks/src/navigation/use-navigation-level.d.ts
+/**
+ * Runtime navigation level from the current UI context snapshot.
+ */
+type RuntimeNavigationLevel = UiRuntimeNavigationLevel;
+/**
+ * Reads the current navigation level from window context.
+ * @returns The current navigation level from `uiContext.level`.
+ * @example
+ * ```tsx
+ * const level = useNavigationLevel();
+ * ```
+ */
+declare function useNavigationLevel(): RuntimeNavigationLevel;
+//#endregion
+//#region ui/hooks/src/state/sidebar-store.d.ts
+/**
+ * Per-level collapsed state record.
+ */
+type CollapsedByLevel = Partial<Record<RuntimeNavigationLevel, boolean>>;
+interface SidebarState {
+  /** Collapsed state keyed by navigation level */
+  collapsedByLevel: CollapsedByLevel;
+  /**
+   * Check if sidebar is collapsed at a given navigation level.
+   * @param level - Navigation level to check
+   * @returns True if collapsed (defaults to false)
+   */
+  isCollapsed: (level: RuntimeNavigationLevel) => boolean;
+  /**
+   * Toggle sidebar collapsed state for a navigation level.
+   * @param level - Navigation level to toggle
+   */
+  toggle: (level: RuntimeNavigationLevel) => void;
+  /**
+   * Set sidebar collapsed state for a navigation level.
+   * @param level - Navigation level to set
+   * @param collapsed - Whether the sidebar should be collapsed
+   */
+  setCollapsed: (level: RuntimeNavigationLevel, collapsed: boolean) => void;
+}
+/**
+ * Sidebar state store.
+ *
+ * Provides per-navigation-level collapse persistence via localStorage.
+ * @example
+ * ```tsx
+ * const isCollapsed = useSidebarStore((s) => s.isCollapsed(level));
+ * const toggle = useSidebarStore((s) => s.toggle);
+ *
+ * return (
+ *   <button onClick={() => toggle(level)}>
+ *     {isCollapsed ? 'Expand' : 'Collapse'}
+ *   </button>
+ * );
+ * ```
+ */
+declare const useSidebarStore: UseBoundStore<Omit<StoreApi<SidebarState>, "setState" | "persist"> & {
+  setState(partial: SidebarState | Partial<SidebarState> | ((state: SidebarState) => SidebarState | Partial<SidebarState>), replace?: false | undefined): unknown;
+  setState(state: SidebarState | ((state: SidebarState) => SidebarState), replace: true): unknown;
+  persist: {
+    setOptions: (options: Partial<PersistOptions<SidebarState, Partial<SidebarState>, unknown>>) => void;
+    clearStorage: () => void;
+    rehydrate: () => Promise<void> | void;
+    hasHydrated: () => boolean;
+    onHydrate: (fn: (state: SidebarState) => void) => () => void;
+    onFinishHydration: (fn: (state: SidebarState) => void) => () => void;
+    getOptions: () => Partial<PersistOptions<SidebarState, Partial<SidebarState>, unknown>>;
+  };
+}>;
+//#endregion
+//#region ui/hooks/src/types/widget-layout.d.ts
+/**
+ * Focus Context Widget Layout Types
+ *
+ * Defines the data structures for per-window widget layouts within Focus Contexts.
+ * These types describe how widgets are positioned and sized within a focus context.
+ *
+ * Key distinction from WidgetLayout (from \@makaio/ui-kernel):
+ * - The kernel WidgetLayout uses "placements" for the dashboard/project system
+ * - FocusContextLayout uses "widgets" for Focus Context-specific layouts
+ * @packageDocumentation
+ */
+/**
+ * Widget size enumeration
+ */
+type FocusContextWidgetSize = 'small' | 'medium' | 'large' | 'full-width';
+/**
+ * A placed widget within a Focus Context layout
+ *
+ * Represents a widget instance with its position and size configuration.
+ * The widgetId references a WidgetDeclaration from extensions.
+ */
+interface PlacedFocusWidget {
+  /** Widget definition ID (from plugin's WidgetDeclaration.id) */
+  widgetId: string;
+  /** Current size of the widget */
+  size: FocusContextWidgetSize;
+  /** X coordinate for free-form layouts (optional) */
+  x?: number;
+  /** Y coordinate for free-form layouts (optional) */
+  y?: number;
+  /** Width in grid units (optional) */
+  width?: number;
+  /** Height in grid units (optional) */
+  height?: number;
+}
+/**
+ * Widget layout for a Focus Context
+ *
+ * Defines how widgets are arranged within a specific focus context.
+ * The version field enables future migrations.
+ *
+ * Note: Named FocusContextLayout to avoid conflict with WidgetLayout from \@makaio/ui-kernel.
+ */
+interface FocusContextLayout {
+  /** Layout version for migration support */
+  version: 1;
+  /** Array of placed widgets in this layout */
+  widgets: PlacedFocusWidget[];
+}
+/**
+ * Helper to create an empty widget layout
+ * @returns A new empty layout with no widgets
+ */
+declare function createEmptyFocusContextLayout(): FocusContextLayout;
+/**
+ * Helper to add a widget to a layout.
+ *
+ * Duplicate adds (same `widgetId`) are no-ops — the unchanged layout is
+ * returned. This prevents non-deterministic state when callers inadvertently
+ * re-add a widget that is already present.
+ * @param layout - The layout to modify
+ * @param widget - The placed widget to add
+ * @returns A new layout with the widget added, or the original layout when
+ *   a widget with the same `widgetId` already exists.
+ */
+declare function addWidgetToFocusLayout(layout: FocusContextLayout, widget: PlacedFocusWidget): FocusContextLayout;
+/**
+ * Helper to remove a widget from a layout by widget ID
+ * @param layout - The layout to modify
+ * @param widgetId - The widget ID to remove
+ * @returns A new layout with the widget removed, or the original layout when
+ *   the widget is not present (referential equality on no-op).
+ */
+declare function removeWidgetFromFocusLayout(layout: FocusContextLayout, widgetId: string): FocusContextLayout;
+/**
+ * Helper to update a widget's size in a layout
+ * @param layout - The layout to modify
+ * @param widgetId - The widget ID to update
+ * @param size - The new size
+ * @returns A new layout with the widget updated, or original if widget not found
+ */
+declare function updateFocusContextWidgetSize(layout: FocusContextLayout, widgetId: string, size: FocusContextWidgetSize): FocusContextLayout;
+/**
+ * Helper to update a widget's position in a layout
+ * @param layout - The layout to modify
+ * @param widgetId - The widget ID to update
+ * @param position - The new position (x, y, width, height)
+ * @returns A new layout with the widget updated, or original if widget not found
+ */
+declare function updateFocusContextWidgetPosition(layout: FocusContextLayout, widgetId: string, position: Pick<PlacedFocusWidget, 'x' | 'y' | 'width' | 'height'>): FocusContextLayout;
+//#endregion
+//#region ui/hooks/src/state/focus-store.d.ts
+/**
+ * Focus context ID - the preset context identifiers
+ *
+ * These are the built-in focus contexts available in the web/app interface.
+ * For cross-package API contracts (slash commands, etc.), use FocusContext from \@makaio/contracts.
+ * @deprecated FocusContext is being phased out. This store is kept for behavior parity
+ * but should be removed after the focus-context-deprecation cleanup plan lands.
+ * TODO(focus-context-deprecation): remove when FocusContext is deleted.
+ */
+type FocusContextId = 'onboarding' | 'chat' | 'git' | 'review' | 'planning' | 'settings' | 'dashboard';
+/**
+ * Full Focus Context object with widget layout
+ *
+ * Represents a complete focus context with its widget arrangement.
+ * System-provided contexts have preset IDs, while user-created contexts
+ * can have custom IDs.
+ */
+interface FocusContextObject {
+  /** Unique identifier for this focus context */
+  id: FocusContextId | string;
+  /** Display name for this context */
+  name: string;
+  /** Whether this is a system preset or user-created */
+  isPreset?: boolean;
+  /** Widget arrangement for this context (optional) */
+  layout?: FocusContextLayout;
+  /** Context-aware quick prompt suggestions (optional) */
+  quickPromptSuggestions?: string[];
+}
+/**
+ * Normalized focus context state - always stores the full object
+ * @deprecated FocusContext is being phased out. This store is kept for behavior parity
+ * but should be removed after the focus-context-deprecation cleanup plan lands.
+ * TODO(focus-context-deprecation): remove when FocusContext is deleted.
+ */
+interface FocusState {
+  /** Active focus context with full object (web/app only) */
+  activeFocus: FocusContextObject;
+  /**
+   * Set active focus by ID (looks up from presets).
+   * @param focusId - Preset focus context ID to activate.
+   */
+  setActiveFocus: (focusId: FocusContextId) => void;
+  /**
+   * Set active focus with full context object.
+   * @param context - Full focus context object to activate.
+   */
+  setActiveFocusContext: (context: FocusContextObject) => void;
+  /**
+   * Update widget layout for current focus context.
+   * @param layout - New layout to apply to the active focus context.
+   */
+  setFocusContextLayout: (layout: FocusContextLayout) => void;
+  /** Get widget layout for current focus context */
+  getFocusContextLayout: () => FocusContextLayout | undefined;
+}
+/**
+ * Focus Store with Zustand state management
+ *
+ * Uses sessionStorage for tab-scoped persistence.
+ * @deprecated FocusContext is being phased out. This store is kept for behavior parity
+ * but should be removed after the focus-context-deprecation cleanup plan lands.
+ * TODO(focus-context-deprecation): remove when FocusContext is deleted.
+ */
+declare const useFocusStore: UseBoundStore<Omit<StoreApi<FocusState>, "setState" | "persist"> & {
+  setState(partial: FocusState | Partial<FocusState> | ((state: FocusState) => FocusState | Partial<FocusState>), replace?: false | undefined): unknown;
+  setState(state: FocusState | ((state: FocusState) => FocusState), replace: true): unknown;
+  persist: {
+    setOptions: (options: Partial<PersistOptions<FocusState, Partial<FocusState>, unknown>>) => void;
+    clearStorage: () => void;
+    rehydrate: () => Promise<void> | void;
+    hasHydrated: () => boolean;
+    onHydrate: (fn: (state: FocusState) => void) => () => void;
+    onFinishHydration: (fn: (state: FocusState) => void) => () => void;
+    getOptions: () => Partial<PersistOptions<FocusState, Partial<FocusState>, unknown>>;
+  };
+}>;
+//#endregion
+//#region ui/hooks/src/navigation/register-navigation-handler.d.ts
+/**
+ * Registers the browser-side navigation handler at priority 10.
+ *
+ * This handler validates the URL scheme, then performs `window.open()` with
+ * target names derived from the URL for singleton/reuse semantics. Only
+ * `http:` and `https:` URLs are allowed — `javascript:` and other unsafe
+ * schemes throw to prevent XSS via the bus.
+ *
+ * In Electron, the higher-priority main-process handler (priority 100)
+ * intercepts first; this handler acts as the fallback.
+ * @param bus - The MakaioBus instance to register on
+ * @returns Cleanup function that unregisters the handler
+ */
+declare function registerNavigationHandler(bus: IMakaioBus): () => void;
+//#endregion
+//#region ui/hooks/src/pages/use-pages.d.ts
+/**
+ * Page definition augmented with navigation action and active state.
+ *
+ * Returned by {@link usePages}. Guarantees both `execute` and `isActive`
+ * are always defined, unlike the base `PageDefinition` where `isActive`
+ * is optional.
+ *
+ * `isActive` is a plain boolean evaluated at render time. Consumers must
+ * not cache `ExecutablePage` objects across renders — re-read from the hook
+ * on each render to get the current active state.
+ */
+interface ExecutablePage extends Omit<PageDefinition, 'isActive'> {
+  /** Execute the page's navigation action (open overlay or switch focus). */
+  execute: () => void;
+  /**
+   * Whether this page is currently active.
+   *
+   * Evaluated at render time from the current store state. Always defined.
+   * Re-read the hook on each render to observe changes.
+   */
+  isActive: boolean;
+}
+/**
+ * Convenience hook combining page definitions with navigation actions.
+ *
+ * Returns page definitions with an execute function for each:
+ * - Peek mode pages: execute opens the page overlay
+ * - Switch mode pages: execute changes the focus context (if focusContext is set)
+ *
+ * Used by sidebar, command palette, and other navigation UI to handle
+ * page activation consistently.
+ * @param options - Filter options (mode, level, group, includeHidden)
+ * @returns Pages with execute and isActive callbacks
+ * @example
+ * ```typescript
+ * function Sidebar() {
+ *   const peekPages = usePages({ mode: 'peek' });
+ *   const switchPages = usePages({ mode: 'switch' });
+ *
+ *   return (
+ *     <aside>
+ *       <section>
+ *         <h3>Navigate</h3>
+ *         {switchPages.map(page => (
+ *           <button key={page.id} onClick={page.execute}>
+ *             {page.name}
+ *           </button>
+ *         ))}
+ *       </section>
+ *       <section>
+ *         <h3>Quick Access</h3>
+ *         {peekPages.map(page => (
+ *           <button key={page.id} onClick={page.execute}>
+ *             {page.name}
+ *           </button>
+ *         ))}
+ *       </section>
+ *     </aside>
+ *   );
+ * }
+ * ```
+ */
+declare function usePages(options?: PageDefinitionQueryOptions): ExecutablePage[];
+//#endregion
+//#region ui/hooks/src/navigation/group-pages.d.ts
+/**
+ * Synthetic config created for navigation groups that appear in page data
+ * but have no entry in the provided `groupConfigs` array.
+ *
+ * Unlike {@link NavigationGroupConfig}, the `id` here is an arbitrary string
+ * because the group was not declared in the navigation group registry.
+ */
+interface SyntheticGroupConfig {
+  /** Arbitrary string identifier from the page's `group` field */
+  id: string;
+  /** Label — falls back to the raw group id string */
+  label: string;
+  /** Sort order — unknown groups are appended at the end */
+  order: number;
+}
+/**
+ * A resolved group config is either a declared {@link NavigationGroupConfig}
+ * (known groups) or a {@link SyntheticGroupConfig} (unknown groups whose id
+ * does not appear in the provided configs).
+ */
+type ResolvedGroupConfig = NavigationGroupConfig | SyntheticGroupConfig;
+/**
+ * Grouped pages result.
+ */
+interface GroupedPages {
+  /** Navigation group configuration (declared or synthetic) */
+  config: ResolvedGroupConfig;
+  /** Pages in this group */
+  pages: ExecutablePage[];
+}
+/**
+ * Group pages by NavigationGroup with config-driven ordering.
+ *
+ * Pages are organized by their `group` field. Pages without a group are excluded.
+ * Groups are ordered according to the provided configs. Unknown groups
+ * (groups not in configs) are appended at the end in the order they're encountered.
+ *
+ * Each group in the result includes its config and matching pages.
+ * Groups with no matching pages are still included (with empty pages array).
+ * @param pages - Pages to group
+ * @param groupConfigs - Navigation group configurations for ordering
+ * @returns Array of grouped pages, ordered by config
+ * @example
+ * ```typescript
+ * const pages = usePages();
+ * const grouped = groupPagesByNavigationGroup(pages, defaultNavigationGroups);
+ *
+ * grouped.forEach(({ config, pages }) => {
+ *   console.log(`${config.label}:`, pages.map(p => p.name));
+ * });
+ * // Navigate: ['Dashboard', 'Chat', 'Git']
+ * // Quick Access: ['Settings', 'Projects', 'Sessions']
+ * ```
+ */
+declare function groupPagesByNavigationGroup(pages: ExecutablePage[], groupConfigs: ReadonlyArray<NavigationGroupConfig>): GroupedPages[];
+//#endregion
+//#region ui/hooks/src/pages/use-page-definitions.d.ts
+/**
+ * Reactive hook for querying page definitions.
+ *
+ * Subscribes to registry changes and automatically updates when pages
+ * are registered or unregistered. Returns filtered and sorted results
+ * based on query options.
+ * @param options - Filter by mode, level, group, or visibility
+ * @returns Filtered, sorted page definitions
+ * @example
+ * ```typescript
+ * function Sidebar() {
+ *   // Get all peek mode pages for Quick Access section
+ *   const peekPages = usePageDefinitions({ mode: 'peek' });
+ *
+ *   // Get all switch mode pages for Navigate section
+ *   const switchPages = usePageDefinitions({ mode: 'switch' });
+ *
+ *   return (
+ *     <aside>
+ *       <section>
+ *         <h3>Navigate</h3>
+ *         {switchPages.map(page => <SidebarItem key={page.id} page={page} />)}
+ *       </section>
+ *       <section>
+ *         <h3>Quick Access</h3>
+ *         {peekPages.map(page => <SidebarItem key={page.id} page={page} />)}
+ *       </section>
+ *     </aside>
+ *   );
+ * }
+ * ```
+ */
+declare function usePageDefinitions(options?: PageDefinitionQueryOptions): PageDefinition[];
+//#endregion
+//#region ui/hooks/src/pages/use-window-id-pages.d.ts
+/**
+ * Returns page definitions filtered by the current Electron window registration ID.
+ *
+ * Wraps {@link usePages} with an additional window ID filter derived from
+ * {@link useWindowContext}. Pages that declare a `windowId` constraint are
+ * only included when the constraint matches the current window. Pages without
+ * a `windowId` constraint are always included.
+ *
+ * When no window ID is set (standalone browser), all pages pass through
+ * unfiltered so the sidebar behaves identically to the pre-Electron behaviour.
+ * @param options - Query options forwarded to {@link usePages} (mode, level, group, surface, includeHidden)
+ * @returns Pages with execute and isActive callbacks, filtered for the current window
+ * @example
+ * ```typescript
+ * function Sidebar() {
+ *   const level = useNavigationLevel();
+ *   const surface = window.__MAKAIO_MOBILE__ ? 'mobile' : 'web';
+ *   const pages = useWindowIdPages({ level, surface });
+ *
+ *   // pages only contains entries valid for this Electron window
+ * }
+ * ```
+ */
+declare function useWindowIdPages(options?: PageDefinitionQueryOptions): ExecutablePage[];
+//#endregion
+//#region ui/hooks/src/pages/use-page-component.d.ts
+/**
+ * Resolve a lazy-loaded page component by ID.
+ *
+ * Returns the component wrapped in React.lazy() for Suspense support,
+ * along with the full page definition for metadata access.
+ *
+ * Memoized per pageId to avoid re-creating lazy components on every render.
+ * @param pageId - Page identifier, or `null` when no page is active.
+ *   A `null` value is treated the same as "not found" and returns `undefined`.
+ * @param reloadKey - Optional key that forces React.lazy wrapper recreation
+ *   for retrying failed dynamic imports.
+ * @returns Object with Component and definition, or undefined if not registered
+ *   or if pageId is null
+ * @example
+ * ```typescript
+ * function PageOverlayView() {
+ *   const activePageId = usePageOverlayStore((s) => s.activePageId);
+ *   const resolved = usePageComponent(activePageId);
+ *
+ *   if (!resolved) {
+ *     return null;
+ *   }
+ *
+ *   const { Component, definition } = resolved;
+ *
+ *   return (
+ *     <PageOverlay title={definition.name}>
+ *       <Suspense fallback={<LoadingSpinner />}>
+ *         <Component />
+ *       </Suspense>
+ *     </PageOverlay>
+ *   );
+ * }
+ * ```
+ */
+declare function usePageComponent(pageId: string | null, reloadKey?: number): {
+  Component: ComponentType<PageComponentProps>;
+  definition: PageDefinition;
+} | undefined;
+//#endregion
+//#region ui/hooks/src/provider-config/selectors.d.ts
+/**
+ * UI-facing provider-config summary enriched with provider definition metadata.
+ */
+interface ProviderConfigSummaryView extends ProviderConfigFileRecord {
+  /** Supported wire protocols derived from the backing provider definition. */
+  supportedProtocols: ProtocolId[];
+}
+/**
+ * UI-facing provider-config detail enriched with provider definition metadata.
+ */
+interface ProviderConfigDetailView extends ProviderConfigSummaryView {
+  /** Credential refs resolved through the runtime context seam. */
+  credentialRefs?: Record<string, CredentialRef>;
+}
+/**
+ * List provider-config summaries enriched for UI consumption.
+ * @param bus - Bus used to load subsystem configs and provider definitions.
+ * @param options - Optional list filter.
+ * @returns Enriched provider-config summaries.
+ */
+declare function listProviderConfigSummaryViews(bus: IMakaioBus, options?: {
+  enabled?: boolean;
+}): Promise<ProviderConfigSummaryView[]>;
+/**
+ * Load one provider-config detail view enriched for UI consumption.
+ * @param bus - Bus used to load subsystem config, provider metadata, and runtime context.
+ * @param id - Provider-config identifier.
+ * @returns Enriched detail view or `null` when missing.
+ */
+declare function getProviderConfigDetailView(bus: IMakaioBus, id: string): Promise<ProviderConfigDetailView | null>;
+//#endregion
+//#region ui/hooks/src/onboarding/scan-onboarding-adapters.d.ts
+/**
+ * Client-grouped scan result for onboarding.
+ *
+ * One record is emitted per client. The `adapterNames` array lists all adapter
+ * driver names belonging to that client so callers can enable them in bulk or
+ * individually via {@link SettingsSubjects.adapter.setEnabled}.
+ */
+interface OnboardingClient {
+  /** Stable client identifier (e.g., 'claude-code'). */
+  clientId: string;
+  /** Human-readable display name (e.g., 'Claude Code'). */
+  name: string;
+  /** CLI binary name used for detection. */
+  binary: string;
+  /** Whether the CLI binary was detected on the system. */
+  found: boolean;
+  /** Detected CLI version, if found. */
+  version?: string;
+  /**
+   * Warning message returned by the canonical client scan service.
+   */
+  warningMessage?: string;
+  /**
+   * Adapter driver names belonging to this client
+   * (e.g., `['claude-agent-sdk', 'claude-code-cli']`).
+   */
+  adapterNames: string[];
+}
+/**
+ * Enriched adapter metadata with canonical client scan results.
+ *
+ * One record is emitted per adapter (not per client). A single client binary
+ * may map to multiple adapters (e.g., `claude` → `claude-agent-sdk` and
+ * `claude-code-cli`), so the caller receives one row per adapter with the real
+ * `adapterName` that the settings API understands.
+ */
+interface OnboardingAdapter {
+  /**
+   * Real adapter driver name as registered with the settings API.
+   * Used by AdaptersStep to call {@link SettingsSubjects.adapter.setEnabled}.
+   */
+  adapterName: string;
+  /** Display name for UI */
+  displayName: string;
+  /** CLI binary name */
+  binary: string;
+  /** Whether CLI binary was detected */
+  found: boolean;
+  /** Detected version (if found) */
+  version?: string;
+  /**
+   * Warning message returned by the canonical client scan service.
+   */
+  warningMessage?: string;
+}
+/**
+ * Shared scan context built from bus data.
+ *
+ * Captures the resolved clients, adapter index, and canonical scan results so both
+ * {@link scanOnboardingAdapters} and {@link scanOnboardingClients} can build
+ * their respective output shapes from the same underlying data.
+ */
+interface ScanContext {
+  /** Enabled clients enriched with canonical scan results. */
+  scannedClients: Array<{
+    id: string;
+    name: string;
+    binary: string;
+    found: boolean;
+    version?: string;
+    warningMessage?: string;
+  }>;
+  /** Adapter names indexed by clientId. */
+  adaptersByClientId: Map<string, string[]>;
+}
+/**
+ * Fetches clients and adapters from the bus, reuses `client.scan` for the
+ * canonical scan result, and returns the shared context used by both public
+ * scan functions.
+ *
+ * Returns `null` when there are no scannable clients (callers should return `[]`).
+ * @returns Populated scan context, or null when no scannable clients exist
+ */
+declare function buildScanContext(): Promise<ScanContext | null>;
+/**
+ * Fetches all CLI-backed clients from the client storage bus, reuses the
+ * canonical `client.scan` results, and returns enriched adapter records
+ * including found/version/warningMessage data.
+ *
+ * This is a pure async function — it carries no React state. Scan results are
+ * owned by the flow orchestrator ({@link OnboardingFlowState.scanAdapters}).
+ *
+ * Prefer {@link scanOnboarding} when both adapter and client results are needed
+ * to avoid issuing duplicate bus requests.
+ * @returns Enriched adapter list with canonical client scan results
+ * @example
+ * ```typescript
+ * const adapters = await scanOnboardingAdapters();
+ * ```
+ */
+declare function scanOnboardingAdapters(): Promise<OnboardingAdapter[]>;
+/**
+ * Scans for installed CLI-backed clients and returns client-grouped results.
+ *
+ * Unlike {@link scanOnboardingAdapters} which emits one row per adapter,
+ * this function emits one row per client with an `adapterNames` array
+ * listing all adapter driver names belonging to that client.
+ *
+ * Prefer {@link scanOnboarding} when both adapter and client results are needed
+ * to avoid issuing duplicate bus requests.
+ * @returns Client-grouped scan results
+ */
+declare function scanOnboardingClients(): Promise<OnboardingClient[]>;
+/**
+ * Run both adapter and client scans using a single shared scan context.
+ *
+ * Avoids duplicate bus requests that would occur when calling
+ * {@link scanOnboardingAdapters} and {@link scanOnboardingClients} independently.
+ * @returns Combined scan results for adapters and clients
+ */
+declare function scanOnboarding(): Promise<{
+  adapters: OnboardingAdapter[];
+  clients: OnboardingClient[];
+}>;
+//#endregion
+//#region ui/hooks/src/onboarding/types.d.ts
+/**
+ * Health check result for a single adapter.
+ */
+interface HealthCheckResult {
+  /** Whether the health check passed, is in progress, or failed. */
+  status: 'pending' | 'success' | 'error';
+  /** Human-readable message providing context for the status. */
+  message?: string;
+  /** Time taken to complete the check, in milliseconds. */
+  durationMs?: number;
+}
+/**
+ * Runtime state shared across all onboarding steps.
+ *
+ * Owned by the orchestrator and passed as controlled props to each step.
+ * Treat as immutable inside step components — use {@link OnboardingFlowActions} to mutate.
+ */
+interface OnboardingFlowState {
+  /** Adapter list from the bus, refreshed after enable/load operations. */
+  adapters: ReadonlyArray<AdapterInfo>;
+  /** Adapter names the user has enabled during this flow. */
+  enabledAdapterNames: ReadonlySet<string>;
+  /** Health check results keyed by adapter name. */
+  healthCheckResults: ReadonlyMap<string, HealthCheckResult>;
+  /** Log import mode selections keyed by adapter name. */
+  logImportSelections: ReadonlyMap<string, LogImportMode>;
+  /** Default agent selection set during the preferences step. */
+  defaultAgentSelection: AgentSelection | null;
+  /** Full extension list from the coordinator, fetched on mount by the orchestrator. */
+  extensions: ReadonlyArray<ExtensionInfo>;
+  /** Per-plugin enabled toggle state, keyed by plugin name. */
+  pluginEnabledStates: ReadonlyMap<string, boolean>;
+  /** CLI adapter scan results, populated after {@link OnboardingFlowActions.scan} completes. */
+  scanAdapters: ReadonlyArray<OnboardingAdapter>;
+  /** Whether a CLI adapter scan is currently in progress. */
+  isScanning: boolean;
+  /** Error from the most recent {@link OnboardingFlowActions.scan} call, or null. */
+  scanError: Error | null;
+  /** Client-grouped scan results, populated after {@link OnboardingFlowActions.scan} completes. */
+  scanClients: ReadonlyArray<OnboardingClient>;
+  /** Client IDs selected by the user in step 2. */
+  selectedClientIds: ReadonlySet<string>;
+  /** Provider configs created during onboarding step 3. */
+  providerConfigs: ReadonlyArray<ProviderConfigSummaryView>;
+  /** Adapter-provider bindings created during onboarding step 4. */
+  adapterProviderBindings: ReadonlyArray<BindingRecord>;
+}
+/**
+ * Host/UI-facing provider-config draft accepted by onboarding actions.
+ *
+ * Host UI may collect plaintext credentials interactively before converting
+ * them into stored credential refs through the host-owned create bridge.
+ */
+interface OnboardingProviderConfigDraft {
+  /** Provider definition identifier. */
+  definitionId: string;
+  /** Optional display name. */
+  name?: string;
+  /** Plaintext credentials captured by a host step. */
+  credentials?: Record<string, string>;
+  /** Pre-resolved credential refs for externally managed credentials. */
+  credentialRefs?: Record<string, CredentialRef>;
+  /** Optional endpoint overrides. */
+  endpointOverrides?: ProtocolEndpoints;
+  /** Optional per-model visibility overrides. */
+  modelVisibility?: Record<string, ModelVisibility$1>;
+  /** Optional default visibility mode. */
+  modelFilterMode?: ModelFilterMode$1;
+}
+/**
+ * Host-owned provider-config creator registered into the onboarding hook.
+ *
+ * This keeps plaintext credential capture on the host side while allowing
+ * the framework-owned orchestrator to delegate provider creation through a
+ * narrow inversion-of-control seam.
+ */
+type OnboardingProviderConfigCreator = (bus: IMakaioBus, input: OnboardingProviderConfigDraft) => Promise<string>;
+/**
+ * Explicit registration lifecycle for the onboarding create seam.
+ */
+interface OnboardingProviderConfigRegistration {
+  /**
+   * Register the host-owned create bridge.
+   * @param creator - Host-owned create bridge.
+   * @returns Cleanup that unregisters this creator when still current.
+   */
+  registerCreateProviderConfig: (creator: OnboardingProviderConfigCreator) => () => void;
+  /**
+   * Unregister the current create bridge when it matches the provided creator.
+   * @param creator - Host-owned create bridge.
+   */
+  unregisterCreateProviderConfig: (creator: OnboardingProviderConfigCreator) => void;
+}
+/**
+ * Mutators for onboarding flow state, called by step components.
+ *
+ * All async methods resolve when the operation is complete.
+ * Errors propagate as rejected promises — callers are responsible for handling them.
+ */
+interface OnboardingFlowActions {
+  /**
+   * Enable an adapter by name.
+   * @param adapterName - The adapter driver name to enable.
+   */
+  enableAdapter: (adapterName: string) => Promise<void>;
+  /**
+   * Disable an adapter by name.
+   * @param adapterName - The adapter driver name to disable.
+   */
+  disableAdapter: (adapterName: string) => Promise<void>;
+  /**
+   * Run the health check for an adapter and record the result.
+   * @param adapterName - The adapter driver name to check.
+   * @returns The health check result.
+   */
+  runHealthCheck: (adapterName: string) => Promise<HealthCheckResult>;
+  /**
+   * Set the log import mode for an adapter.
+   * @param adapterName - The adapter driver name.
+   * @param mode - The import mode to apply.
+   */
+  setLogImportMode: (adapterName: string, mode: LogImportMode) => void;
+  /**
+   * Set or clear the default agent selection.
+   * @param selection - The agent selection to persist, or null to clear.
+   */
+  setDefaultAgent: (selection: AgentSelection | null) => void;
+  /**
+   * Re-fetch the adapter list from the bus.
+   */
+  refreshAdapterList: () => Promise<void>;
+  /**
+   * Scan for installed CLI adapters and populate {@link OnboardingFlowState.scanAdapters}.
+   * Sets {@link OnboardingFlowState.isScanning} during the operation.
+   * Rejects with the scan error (also stored in {@link OnboardingFlowState.scanError}).
+   */
+  scan: () => Promise<void>;
+  /**
+   * Optimistically toggle a plugin's enabled state and persist the change.
+   * Fire-and-forget: bus errors are logged but do not surface to the UI.
+   * @param pluginName - The plugin name to toggle.
+   * @param enabled - The new desired enabled state.
+   */
+  togglePlugin: (pluginName: string, enabled: boolean) => void;
+  /**
+   * Select a client in the clients step.
+   * @param clientId - The client identifier to select.
+   */
+  selectClient: (clientId: string) => void;
+  /**
+   * Deselect a client in the clients step.
+   * @param clientId - The client identifier to deselect.
+   */
+  deselectClient: (clientId: string) => void;
+  /**
+   * Create a provider config and add it to the onboarding state.
+   * @param input - The provider config creation input.
+   * @returns The ID of the created provider config.
+   */
+  createProviderConfig: (input: OnboardingProviderConfigDraft) => Promise<string>;
+  /**
+   * Delete a provider config created during onboarding.
+   * @param id - The provider config ID to delete.
+   */
+  deleteProviderConfig: (id: string) => Promise<void>;
+  /**
+   * Bind a provider config to an adapter.
+   * @param adapterName - The adapter name to bind to.
+   * @param providerConfigId - The provider config to bind.
+   */
+  bindProvider: (adapterName: string, providerConfigId: string) => Promise<void>;
+  /**
+   * Unbind a provider config from an adapter.
+   * @param adapterName - The adapter name to unbind from.
+   * @param providerConfigId - The provider config to unbind.
+   */
+  unbindProvider: (adapterName: string, providerConfigId: string) => Promise<void>;
+  /**
+   * Set the default provider for an adapter.
+   * @param adapterName - The adapter name.
+   * @param providerConfigId - The provider config to make default.
+   */
+  setDefaultProvider: (adapterName: string, providerConfigId: string) => Promise<void>;
+  /**
+   * Refresh provider configs from the bus.
+   */
+  refreshProviderConfigs: () => Promise<void>;
+  /**
+   * Refresh adapter-provider bindings from the bus for a specific adapter.
+   * @param adapterName - The adapter name to refresh bindings for.
+   */
+  refreshBindings: (adapterName: string) => Promise<void>;
+}
+/**
+ * Concrete step props for the runtime onboarding flow.
+ *
+ * The kernel owns navigation-only step metadata; the hooks tier composes in
+ * the live flow state and action surface that the orchestrator injects at
+ * render time.
+ */
+type OnboardingStepProps = OnboardingStepProps$1 & {
+  /** Current snapshot of the shared flow state. */flowState: OnboardingFlowState; /** Mutators for flow state. */
+  actions: OnboardingFlowActions;
+};
+/**
+ * Concrete step definition for the runtime onboarding flow.
+ *
+ * This narrows the kernel step contract to the actual prop shape that host
+ * and framework onboarding steps receive at runtime.
+ */
+type OnboardingStepDefinition = Omit<OnboardingStepDefinition$1, 'component'> & {
+  component: ComponentLike<OnboardingStepProps>;
+};
+/**
+ * Options passed to {@link useOnboardingFlow}.
+ */
+interface UseOnboardingFlowOptions {
+  /** Adapter list, client list, and plugin list for condition evaluation. */
+  context: OnboardingContext;
+  /** Called when onboarding flow is completed. */
+  onComplete: () => void;
+  /** Called when onboarding flow is skipped. */
+  onSkip: () => void;
+}
+/**
+ * Return value of {@link useOnboardingFlow}.
+ */
+interface UseOnboardingFlowResult {
+  /** Currently active steps (filtered by conditions, frozen at mount). */
+  activeSteps: ReadonlyArray<OnboardingStepDefinition>;
+  /** Index of the current step. */
+  currentStepIndex: number;
+  /** The current step definition. */
+  currentStep: OnboardingStepDefinition;
+  /** Flow state shared across all steps. */
+  flowState: OnboardingFlowState;
+  /** Actions for step components to call. */
+  actions: OnboardingFlowActions;
+  /** Navigate to the next step. */
+  goNext: () => void;
+  /** Navigate to the previous step. */
+  goBack: () => void;
+  /** Persist accumulated selections and skip the remaining onboarding steps. */
+  skip: () => Promise<void>;
+  /** Persist flow selections and complete the flow (call only from the final step). */
+  complete: () => Promise<void>;
+}
+/**
+ * Framework-owned onboarding hook plus its explicit host registration seam.
+ */
+type UseOnboardingFlowHook = ((options: UseOnboardingFlowOptions) => UseOnboardingFlowResult) & OnboardingProviderConfigRegistration;
+//#endregion
+//#region ui/hooks/src/onboarding/register-core-onboarding-steps.d.ts
+/**
+ * Step components required for core onboarding registration.
+ *
+ * Pass lazy-loaded components from the views package to keep the framework
+ * free of any direct view dependency:
+ * @example
+ * ```tsx
+ * import { lazy } from 'react';
+ *
+ * const cleanup = registerCoreOnboardingSteps({
+ *   WelcomeStep:     lazy(() => import('../OnboardingView/steps/WelcomeStep')),
+ *   ClientsStep:     lazy(() => import('../OnboardingView/steps/ClientsStep')),
+ *   ProvidersStep:   lazy(() => import('../OnboardingView/steps/ProvidersStep')),
+ *   AdaptersStep:    lazy(() => import('../OnboardingView/steps/AdaptersStep')),
+ *   PreferencesStep: lazy(() => import('../OnboardingView/steps/PreferencesStep')),
+ *   PluginsStep:     lazy(() => import('../OnboardingView/steps/PluginsStep')),
+ *   DoneStep:        lazy(() => import('../OnboardingView/steps/DoneStep')),
+ * });
+ * ```
+ */
+interface CoreOnboardingStepComponents {
+  /** Welcome step component (always shown, order 10). */
+  WelcomeStep: ComponentLike<OnboardingStepProps>;
+  /** Clients selection step component (always shown, order 20). */
+  ClientsStep: ComponentLike<OnboardingStepProps>;
+  /** Provider config step component (always shown, order 25). */
+  ProvidersStep: ComponentLike<OnboardingStepProps>;
+  /** Tools (adapters) setup step component (always shown, order 30). */
+  AdaptersStep: ComponentLike<OnboardingStepProps>;
+  /** Preferences step component (always shown after adapters, order 35). */
+  PreferencesStep: ComponentLike<OnboardingStepProps>;
+  /** Plugins step component (shown when extensions are discovered, order 40). */
+  PluginsStep: ComponentLike<OnboardingStepProps>;
+  /** Final confirmation step component (always shown, order 50). */
+  DoneStep: ComponentLike<OnboardingStepProps>;
+}
+/**
+ * Register the seven core onboarding steps.
+ *
+ * Each step is assigned an order value in the range 10–50, leaving 100+ for
+ * plugin-provided steps. Preferences is always included because adapter
+ * enablement is mutable flow state; the Plugins step is conditioned on
+ * extensions being discovered.
+ * @param components - Step components injected from the views package
+ * @returns Cleanup function that unregisters all core steps when called
+ * @example
+ * ```tsx
+ * useEffect(() => {
+ *   const cleanup = registerCoreOnboardingSteps({
+ *     WelcomeStep:     lazy(() => import('../OnboardingView/steps/WelcomeStep')),
+ *     ClientsStep:     lazy(() => import('../OnboardingView/steps/ClientsStep')),
+ *     ProvidersStep:   lazy(() => import('../OnboardingView/steps/ProvidersStep')),
+ *     AdaptersStep:    lazy(() => import('../OnboardingView/steps/AdaptersStep')),
+ *     PreferencesStep: lazy(() => import('../OnboardingView/steps/PreferencesStep')),
+ *     PluginsStep:     lazy(() => import('../OnboardingView/steps/PluginsStep')),
+ *     DoneStep:        lazy(() => import('../OnboardingView/steps/DoneStep')),
+ *   });
+ *   return cleanup;
+ * }, []);
+ * ```
+ */
+declare function registerCoreOnboardingSteps(components: CoreOnboardingStepComponents): () => void;
+//#endregion
+//#region ui/hooks/src/onboarding/skip-flag.d.ts
+/**
+ * Shared onboarding skip-flag helpers.
+ *
+ * Centralizes localStorage access so the first-run gate and onboarding flow
+ * completion use the same persistence contract.
+ * @packageDocumentation
+ */
+/**
+ * Read the persisted onboarding skip flag.
+ * Storage failures are treated as "not skipped".
+ * @returns True when onboarding has been skipped in this browser profile
+ */
+declare function getOnboardingSkipped(): boolean;
+/**
+ * Persist the onboarding skip flag.
+ * Storage failures are intentionally ignored so callers can still continue.
+ */
+declare function setOnboardingSkipped(): void;
+/**
+ * Clear the onboarding skip flag.
+ * Storage failures are intentionally ignored so callers can still continue.
+ */
+declare function clearOnboardingSkipped(): void;
+/**
+ * Check whether onboarding has been completed.
+ * @returns True when the completed flag is set in localStorage
+ */
+declare function getOnboardingCompleted(): boolean;
+/** Mark onboarding as completed persistently. */
+declare function setOnboardingCompleted(): void;
+/** Clear the onboarding completed flag. */
+declare function clearOnboardingCompleted(): void;
+//#endregion
+//#region ui/hooks/src/onboarding/use-onboarding-flow.d.ts
+declare const useOnboardingFlow: UseOnboardingFlowHook;
+//#endregion
+//#region ui/hooks/src/onboarding/plugin-persistence.d.ts
+interface PersistPluginEnabledResult {
+  id: string;
+}
+/**
+ * Persisted extension config entry cached in a ref to preserve config blobs
+ * across enabled-state toggles without driving re-renders.
+ */
+interface PersistedExtensionConfigEntry {
+  /** Stable storage row identifier */
+  id: string;
+  /** Existing extension config payload that must be preserved across enabled toggles */
+  config: Record<string, unknown> | undefined;
+}
+/**
+ * Persist only the enabled state for a plugin config row.
+ *
+ * This uses the storage layer's atomic `setEnabled` RPC instead of
+ * reconstructing a partial `set` payload client-side. Cached config blobs stay
+ * available in-memory for future full writes, but enabled toggles no longer
+ * need to round-trip or risk clearing them.
+ * @param pluginName - Registry name of the plugin
+ * @param enabled - Desired enabled state
+ * @param cache - Ref map of persisted config entries
+ * @param bus - Bus instance used to dispatch the set request
+ * @returns Persisted row identifier for the extension config record
+ */
+declare function persistPluginEnabled(pluginName: string, enabled: boolean, cache: Map<string, PersistedExtensionConfigEntry>, bus: IMakaioBus): Promise<PersistPluginEnabledResult>;
+//#endregion
+//#region ui/hooks/src/state/app-context-store.d.ts
+interface AppContextState {
+  /** Default agent selection for new windows (null = use system default) */
+  defaultSelection: AgentSelection | null;
+  /** Set the default selection for new windows */
+  setDefaultSelection: (selection: AgentSelection | null) => void;
+}
+/**
+ * Cross-tab application context store.
+ *
+ * Use this for user-level defaults that should:
+ * - Persist across browser sessions
+ * - Apply to newly opened windows/tabs
+ * - Be overridable per-window via useSelectionStore
+ * @example
+ * ```tsx
+ * const { defaultSelection, setDefaultSelection } = useAppContext();
+ *
+ * // Update default for new windows
+ * setDefaultSelection({ kind: 'adapter', adapterName: 'claude-code', model: 'opus' });
+ * ```
+ */
+declare const useAppContext: UseBoundStore<Omit<StoreApi<AppContextState>, "setState" | "persist"> & {
+  setState(partial: AppContextState | Partial<AppContextState> | ((state: AppContextState) => AppContextState | Partial<AppContextState>), replace?: false | undefined): unknown;
+  setState(state: AppContextState | ((state: AppContextState) => AppContextState), replace: true): unknown;
+  persist: {
+    setOptions: (options: Partial<PersistOptions<AppContextState, Partial<AppContextState>, unknown>>) => void;
+    clearStorage: () => void;
+    rehydrate: () => Promise<void> | void;
+    hasHydrated: () => boolean;
+    onHydrate: (fn: (state: AppContextState) => void) => () => void;
+    onFinishHydration: (fn: (state: AppContextState) => void) => () => void;
+    getOptions: () => Partial<PersistOptions<AppContextState, Partial<AppContextState>, unknown>>;
+  };
+}>;
+//#endregion
+//#region ui/hooks/src/state/provider-store.d.ts
+/**
+ * An adapter that is bound to a provider config.
+ *
+ * Used by the model picker to emit model×adapter combinations. The
+ * `displayLabel` resolves to the adapter's human-readable display name.
+ */
+interface BoundAdapter {
+  /** Stable adapter driver name (e.g., `'claude-code'`, `'openai-node'`). */
+  adapterName: string;
+  /**
+   * Human-readable label for display in picker UI.
+   * Sourced from the canonical adapter config's `displayName`, falling back to
+   * the stable adapter `name` when the display label is absent.
+   */
+  displayLabel: string;
+}
+/**
+ * Runtime information about a configured provider instance.
+ *
+ * Each entry corresponds to one canonical provider-config record and carries
+ * the model catalog sourced from the linked provider definition.
+ */
+interface ProviderInfo {
+  /**
+   * Provider config UUID — stable identifier for this configuration instance.
+   * Corresponds to `providerConfigId` in {@link AgentSelection}.
+   */
+  providerConfigId: string;
+  /** FK to providers.id — links this config to the provider definition. */
+  definitionId: string;
+  /** Display name for UI, as configured by the user. */
+  name: string;
+  /** Available models sourced from the provider definition catalog. */
+  availableModels: AIModel[];
+  /** Whether this is the default config for its provider definition. */
+  isDefault: boolean;
+  /** Whether this config is enabled. */
+  enabled: boolean;
+  /** Controls default visibility for models without explicit overrides. */
+  modelFilterMode: ModelFilterMode;
+  /** True when at least one credential key exists in storage. */
+  hasCredentials: boolean;
+  /** Sparse per-model visibility overrides. */
+  modelVisibility?: Record<string, ModelVisibility>;
+  /**
+   * Adapters currently bound to this provider config.
+   *
+   * Used by the model picker to enumerate model×adapter combinations for
+   * selection. Empty when no adapters are bound.
+   */
+  boundAdapters: BoundAdapter[];
+}
+interface ProviderState {
+  /** All available providers across all definitions */
+  providers: ProviderInfo[];
+  /** Loading state */
+  isLoading: boolean;
+  /** Error state */
+  error: Error | null;
+  /** Fetch in progress (for deduplication) */
+  _fetchPromise: Promise<void> | null;
+  /**
+   * Whether providers have been fetched at least once.
+   * Used to gate the stale-cache guard so `invalidate()` can force a refresh.
+   */
+  _hasFetched: boolean;
+  /**
+   * Monotonically increasing counter incremented on every `invalidate()` call.
+   * In-flight fetches compare their captured generation against the current
+   * value on completion — if they differ, the results are discarded so a
+   * subsequent `fetchProviders()` can start a fresh fetch.
+   */
+  _fetchGeneration: number;
+  /**
+   * Fetch providers from all enabled provider configs. Idempotent — concurrent
+   * calls share the same promise. No-ops when already fetched unless
+   * `invalidate()` has been called first.
+   */
+  fetchProviders: () => Promise<void>;
+  /**
+   * Mark the provider list as stale so the next `fetchProviders()` call
+   * triggers a real refetch. Call this after creating, updating, or deleting
+   * a provider config.
+   */
+  invalidate: () => void;
+  /** Set providers */
+  setProviders: (providers: ProviderInfo[]) => void;
+  /** Set error state */
+  setError: (error: Error | null) => void;
+}
+declare const useProviderStore: UseBoundStore<StoreApi<ProviderState>>;
+//#endregion
+//#region ui/hooks/src/utils/persisted-agent-selection.d.ts
+type PersistableAdapterSelection = Extract<AgentSelection, {
+  kind: 'adapter';
+}> & {
+  providerConfigId: string;
+  model: string;
+};
+type PersistableProjectSelection = Exclude<AgentSelection, {
+  kind: 'adapter';
+}> | PersistableAdapterSelection;
+/**
+ * Parse persisted browser selection state into the current AgentSelection union.
+ *
+ * The wire schema intentionally stays open for host-tier extension. Browser
+ * persistence is stricter: only current application kinds are accepted, with
+ * one-way migration for legacy `'model'` and `'virtualModel'` payloads.
+ * @param value - Raw persisted value from storage/preferences
+ * @returns Current AgentSelection, or null when the payload is stale/invalid
+ */
+declare function parsePersistedAgentSelection(value: unknown): AgentSelection | null;
+/**
+ * Project defaults must be concrete and lossless when persisted.
+ * @param selection - Candidate selection from UI state
+ * @returns True when the selection can be stored as an explicit project default
+ */
+declare function isPersistableProjectSelection(selection: AgentSelection): selection is PersistableProjectSelection;
+//#endregion
+export { type AppContextState, type BoundAdapter, BusContext, BusProvider, type BusProviderProps, type CoreOnboardingStepComponents, type ExecutablePage, type ExtensionBrowserLoadOptions, type ExtensionBrowserLoadResult, type FocusContextId, type FocusContextLayout, type FocusContextObject, type FocusContextWidgetSize, type FocusState, type GroupedPages, type HealthCheckResult, type OnboardingAdapter, type OnboardingClient, type OnboardingFlowActions, type OnboardingFlowState, type OnboardingStepDefinition, type OnboardingStepProps, type PageOverlayState, type PersistableAdapterSelection, type PersistableProjectSelection, type PersistedExtensionConfigEntry, type PersistedStoreConfig, type PlacedFocusWidget, type ProviderConfigDetailView, type ProviderConfigSummaryView, type ProviderInfo, type RuntimeNavigationLevel, type ScanContext, type SharedLoaderState, type SidebarState, type StorageType, type UseBusQueryOptions, type UseBusQueryResult, type UseOnboardingFlowOptions, type UseOnboardingFlowResult, type UseWidgetConfigOptions, type UseWidgetConfigResult, type UseWidgetRegistryOptions, type UseWidgetsOptions, type UseWidgetsResult, type WindowContextState, addWidgetToFocusLayout, buildScanContext, clearOnboardingCompleted, clearOnboardingSkipped, createEmptyFocusContextLayout, createPersistedStore, getOnboardingCompleted, getOnboardingSkipped, getProviderConfigDetailView, groupPagesByNavigationGroup, isPersistableProjectSelection, listProviderConfigSummaryViews, loadExtensionBrowserContributions, noopStorage, parsePersistedAgentSelection, persistPluginEnabled, registerCoreOnboardingSteps, registerNavigationHandler, removeWidgetFromFocusLayout, scanOnboarding, scanOnboardingAdapters, scanOnboardingClients, setOnboardingCompleted, setOnboardingSkipped, updateFocusContextWidgetPosition, updateFocusContextWidgetSize, useAppContext, useBus, useBusEvent, useBusQuery, useFocusStore, useNavigationLevel, useOnboardingFlow, useOptionalBus, usePageComponent, usePageDefinitions, usePageOverlayStore, usePages, useProviderStore, useSidebarStore, useTrayLayout, useWidgetConfig, useWidgetLayout, useWidgetLayoutActions, useWidgetRegistry, useWidgets, useWindowContext, useWindowIdPages };