> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyvexsoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell Utility Hooks

> Navigation, toasts, config, and logging hooks.

These four hooks provide access to shell services from within plugin UI components. They are all thin wrappers around `usePluginContext()` fields, exported as focused hooks for readability.

## Import

```ts theme={null}
import {
  useShellNavigation,
  useShellToast,
  useShellConfig,
  usePluginLogger,
} from "@skyvexsoftware/stratos-sdk";
```

***

## `useShellNavigation`

Access the shell's navigation helpers. All navigation is handled by the shell's router — plugins do not manage their own history.

### Signature

```ts theme={null}
function useShellNavigation(): PluginNavigationHelper
```

See [`PluginNavigationHelper`](/sdk/type-reference#pluginnavigationhelper) for the full shape.

### Methods

| Method                             | Description                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------ |
| `navigateTo(path)`                 | Navigate to a route within the current plugin (e.g. `"history"`, `"settings"`) |
| `navigateToPlugin(pluginId, path)` | Navigate to a route in another plugin                                          |
| `navigateToShell(path)`            | Navigate to a shell-level route (e.g. `"settings"`, `"debug"`)                 |
| `getCurrentPath()`                 | Return the current route path string                                           |

### Usage

```tsx theme={null}
import { useShellNavigation } from "@skyvexsoftware/stratos-sdk";

export function Nav() {
  const nav = useShellNavigation();

  return (
    <nav>
      <button onClick={() => nav.navigateTo("history")}>History</button>
      <button onClick={() => nav.navigateToPlugin("pirep-filing", "new")}>
        File PIREP
      </button>
      <button onClick={() => nav.navigateToShell("settings")}>
        App Settings
      </button>
    </nav>
  );
}
```

***

## `useShellToast`

Trigger toast notifications using the shell's toast system. All toasts appear in the shell's notification area — plugins do not render their own toast containers.

### Signature

```ts theme={null}
function useShellToast(): PluginToastAPI
```

See [`PluginToastAPI`](/sdk/type-reference#plugintoastapi) for the full shape.

### Usage

```tsx theme={null}
import { useShellToast } from "@skyvexsoftware/stratos-sdk";

export function SaveButton() {
  const toast = useShellToast();

  const handleSave = async () => {
    try {
      await saveData();
      toast.success("Settings saved");
    } catch {
      toast.error("Failed to save settings");
    }
  };

  return <button onClick={handleSave}>Save</button>;
}
```

***

## `useShellConfig`

Read plugin-namespaced config values synchronously. The config store is namespaced to the current plugin — two plugins using the same key will not conflict.

### Signature

```ts theme={null}
function useShellConfig(): PluginConfigStore
```

See [`PluginConfigStore`](/sdk/type-reference#pluginconfigstore) for the full shape.

Note: The UI-side config store provides synchronous reads (values are preloaded into context). This differs from the background `PluginContext.config`, which has async `get`, `set`, `delete`, and `getAll` methods.

### Usage

```tsx theme={null}
import { useShellConfig } from "@skyvexsoftware/stratos-sdk";

export function MyComponent() {
  const config = useShellConfig();

  // With default value — always returns a string
  const theme = config.get<string>("theme", "dark");

  // Without default — may be undefined
  const apiKey = config.get<string>("apiKey");

  return (
    <div>
      <p>Theme: {theme}</p>
      {!apiKey && <p>API key not configured</p>}
    </div>
  );
}
```

***

## `usePluginLogger`

Access a scoped logger that routes log output to the shell's logging infrastructure. Log entries are prefixed with the plugin ID and written to the daily log file alongside all other Stratos logs.

### Signature

```ts theme={null}
function usePluginLogger(): PluginLogger
```

See [`PluginLogger`](/sdk/type-reference#pluginlogger) for the full shape.

### Parameters

Both `category` and `message` are required. The `category` should be the component or service name — it appears in the log entry alongside the plugin ID prefix.

| Parameter  | Description                                          |
| ---------- | ---------------------------------------------------- |
| `category` | Component or service name (e.g. `"FlightMapPage"`)   |
| `message`  | Human-readable log message                           |
| `...args`  | Optional additional values appended to the log entry |

### Usage

```tsx theme={null}
import { usePluginLogger } from "@skyvexsoftware/stratos-sdk";

export function FlightMapPage() {
  const logger = usePluginLogger();

  useEffect(() => {
    logger.info("FlightMapPage", "Map initialised");
  }, []);

  const handleError = (err: unknown) => {
    logger.error("FlightMapPage", "Failed to load route data", err);
  };

  return <Map onError={handleError} />;
}
```

### Never use `console.*` directly

Plugin components must use `usePluginLogger` rather than `console.log`, `console.error`, etc. The logger writes to the structured log file, applies secret sanitization, and includes the plugin ID prefix for easy filtering.

```tsx theme={null}
// Correct
const logger = usePluginLogger();
logger.info("MyComponent", "User clicked button");

// Wrong — do not use console directly in plugin components
console.log("User clicked button");
```