# API reference

> The public API surface of OpenNook, by module.

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

[https://swiftpackageindex.com/twinkling-reality/opennook/documentation](https://swiftpackageindex.com/twinkling-reality/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 (with `NookConfiguration.defaultStyle`, the
  framework's own shape), 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`.
- **Live configuration** - `AppCoordinator.reloadActiveConfiguration()` rebuilds
  the active module's configuration and applies it to the running chrome, and
  `AppCoordinator.replaceChromeBehavior(_:)` changes the host's chrome behavior at
  runtime (`ModuleHost.chromeBehavior` reads it back). See
  [Playground](/guides/playground/). 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`).
- **Companion surfaces** - `NookCompanion` and
  `NookConfiguration.addCompanion(...)`, with the shared `companionStyle`,
  `companionSize`, and `companionPresence`; `NookCompanionSource`
  (`NookConfiguration.companionSource`) for companions that come and go while the app
  runs; the glyph button style `NookGlyphButtonStyle` (`.nookGlyph`); and the chrome
  controls `NookChromeActions` (`\.nookChromeActions`), `NookKeepOpenButton`, and
  `NookSettingsButton`, with the `topBar.showsKeepOpenButton` /
  `showsSettingsButton` flags. See
  [Companion surfaces](/guides/companion-surfaces/). Source:
  `Sources/NookKit/App/NookCompanion.swift`,
  `Sources/NookKit/App/NookCompanionSource.swift`,
  `Sources/NookKit/App/NookGlyphButtonStyle.swift`,
  `Sources/NookKit/App/NookChromeActions.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`.
- **Notch clearance** - `NookNotchClearance` (`topBar.notchClearance`),
  `NookNotchRow`, and the `nookNotchAccessories(leading:trailing:)` modifier: keeping
  content clear of the hardware notch, and putting views beside it. See
  [Layout and content insets](/guides/layout-and-insets/#clearing-the-notch). Source:
  `Sources/NookKit/App/Views/Layout/NookNotchClearance.swift`,
  `Sources/NookKit/App/Views/Layout/NookNotchRow.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.
  `Nook.style` and `Nook.hoverBehavior` are settable, so a running chrome can be
  restyled in place.
- `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/).
- `NookNotchCutout`, `\.nookNotchCutout` - where the hardware notch falls in the host
  content frame. See
  [Layout and content insets](/guides/layout-and-insets/#clearing-the-notch).
- `NookCompanionSurface`, `NookCompanionAnchor`, `NookCompanionVisibility`,
  `NookCompanionShape`, `NookCompanionBackdrop` - companion surfaces at the engine
  level (`Nook.companions`), with the `nookCompanionVisibility(_:)` /
  `nookCompanionHidden(_:)` modifiers, `\.nookCompanionIsPresented`, and
  `\.nookCompanionIsHovered`. See [Companion surfaces](/guides/companion-surfaces/).
- `NookCompanionStyle`, `AnyNookCompanionStyle`, `NookStandardCompanionStyle`,
  `NookCompanionStyleConfiguration`, `NookCompanionFadeMask`, `NookOutlineShadow` -
  how a companion surface is drawn; `NookCompanionSize` (`\.nookCompanionSize`) -
  the size a companion shares with its controls; `NookCompanionPresence` - how it
  comes and goes. See [Companion surfaces](/guides/companion-surfaces/#look).
- `NookBackdropView`, `\.nookChromeBackdrop` - the chrome's backdrop, painted in any
  shape by content and styles.
- `NookRimGlowStyle`, `NookRimGlowPreferenceKey`, `nookRimGlow(_:)` - the glowing
  rim; `NookScrollEdgeFade`, `nookScrollEdgeFade(...)`, `\.nookScrollEdgeFade` - the
  scroll edge fade. See [Rim glow and edge fade](/guides/panel-effects/).

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/`.