# API reference

> The public API surface of OpenNook, by module.

OpenNook publishes its symbol-level DocC reference through
[Swift Package Index](https://swiftpackageindex.com/glendonC/opennook),
regenerated on each tagged release, at:

[https://swiftpackageindex.com/glendonC/opennook/documentation](https://swiftpackageindex.com/glendonC/opennook/documentation)

The map below is the maintained index of the public surface, grouped by module,
with the guide that teaches each piece and the source file that defines it. The
source is always the source of truth.

Build that DocC reference yourself with `./Scripts/generate-docs.sh` - it
produces the same combined site Swift Package Index hosts.

## NookApp

The one-line entry point. `import NookApp` re-exports `NookKit` and
`NookSurface`, so a host needs only this single import.

- `NookApp.main` - the boot overloads: a view builder, a `NookConfiguration`, a
  `NookHostConfiguration`, and a main-actor builder closure for setup that
  constructs main-actor-isolated types. See [Your first nook](/start/first-nook/).
  Source: `Sources/NookApp/NookApp.swift`.

## NookKit

The app chrome layered over `NookSurface`.

- **Registration** - `NookConfiguration`, `NookTopBarConfiguration`. The
  host-app seam: home/compact content, theme, lifecycle hooks, chrome flags, the
  shape/animation/width knobs, and `setSettings(_:)`. See
  [Your first nook](/start/first-nook/) and
  [Settings chrome](/guides/settings-chrome/). Source:
  `Sources/NookKit/App/NookConfiguration.swift`.
- **Theme** - `NookResolvedTheme`. The flat palette every chrome view reads,
  including `accent` and `fontDesign`. See [Theming](/guides/theming/). Source:
  `Sources/NookKit/App/NookResolvedTheme.swift`.
- **Appearance preferences** - `NookAppearancePreferences`, `NookChromePalette`,
  `NookSurfaceStyle`. The persisted, user-facing surface and chrome state. See
  [Theming](/guides/theming/#user-facing-appearance-preferences). Source:
  `Sources/NookKit/App/NookAppearancePreferences.swift`.
- **Lifecycle** - `AppCoordinator`. The vocabulary the hotkey and menu-bar
  fallback call into (`showNook`, `hideNook`, `toggleNook`,
  `toggleKeepNookOpen`), plus `switchModule`/`cycleModule` and the
  `NookSurfacePresenting` conformance. See [Your first nook](/start/first-nook/).
  Source: `Sources/NookKit/App/AppCoordinator.swift`.
- **State** - `AppState`, `NookViewMode`, `HotkeyRegistrationFailure`. The
  observable chrome state; `replaceAppearancePreferences(_:)` is the persisted
  write path. Source: `Sources/NookKit/App/AppState.swift`.
- **Services** - `AppServices`, `ServiceKey`. The per-module dependency
  container resolved from `\.appServices`. See
  [Multiple modules](/guides/multiple-modules/#service-isolation-servicekey-and-appservices).
  Source: `Sources/NookKit/App/AppServices.swift`.
- **Multi-module hosting** - `NookHostConfiguration`, `NookModule`,
  `ClosureModule`, `NookModuleDescriptor`, `NookModuleContext`,
  `NookModuleRegistry`, `NookHostBranding`. See
  [Multiple modules](/guides/multiple-modules/). Source:
  `Sources/NookKit/App/Modules/`.
- **Input and display** - `NookHotkey` (`Sources/NookKit/System/NookHotkey.swift`),
  `NookDisplayPreference` (`Sources/NookKit/App/NookDisplayPreference.swift`).
- **Layout metrics** - `NookLayout`, the public chrome dimension constants
  (expanded width, edge padding, compact-slot size, breadcrumb width), and
  `NookChromeMetrics`, the host-tunable metrics bag (`edgePadding`, compact slot
  size, breadcrumb width, top-bar height). See
  [Layout and content insets](/guides/layout-and-insets/). Source:
  `Sources/NookKit/App/Views/Layout/NookLayout.swift`,
  `Sources/NookKit/App/NookChromeMetrics.swift`.

## NookSurface

The low-level notch window, re-exported through `NookApp`. Most hosts drive
these through `NookKit` rather than directly; the host-facing knobs are:

- `NookStyle` - corner radii, `expandedContentInsets`, and the built-in animation curves.
- `NookTransitionConfiguration` - per-instance animation overrides.
- `NookPresentation` - notch-fused vs free-floating chrome.
- `NookContentInsets` - curve-derived safe-area insets for edge-pinned host content.
  See [Layout and content insets](/guides/layout-and-insets/).

Both `NookStyle` and `NookTransitionConfiguration` are surfaced on
`NookConfiguration`; see
[Theming](/guides/theming/#chrome-shape-animation-and-width) and
[Layout and content insets](/guides/layout-and-insets/). The remaining
surface types (`Nook`, `NookState`, `NookBackdrop`, `NookHoverBehavior`,
`NookFeedback`) live under `Sources/NookSurface/`.

## NookComponents

Opt-in add-ons. Add the `NookComponents` product to your target only when you
want one; it is not pulled in by `NookApp`.

- **Shelf** - `ShelfStore`, `ShelfItem`, `NookShelfView`, `ShelfRuntime`. See
  [File shelf](/guides/file-shelf/). Source: `Sources/NookComponents/Shelf/`.
- **Activities** - `NookActivity`, `NookActivityPriority`, `NookActivityQueue`,
  `NookActivityHost`, `NookActivityCard`. See
  [Activity queue](/guides/activity-queue/). Source:
  `Sources/NookComponents/Activities/`.
- **Volume** - `SystemVolumeObserver`, `VolumeReading`, `CoreAudioVolumeReader`,
  `NookVolumeIndicator`. See [Volume glyph](/guides/volume-glyph/). Source:
  `Sources/NookComponents/Volume/`.