API reference

OpenNook publishes its symbol-level DocC reference through Swift Package Index, regenerated on each tagged release, at:

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. 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 and Settings chrome. Source: Sources/NookKit/App/NookConfiguration.swift.
• Theme - NookResolvedTheme. The flat palette every chrome view reads, including accent and fontDesign. See Theming. Source: Sources/NookKit/App/NookResolvedTheme.swift.
• Appearance preferences - NookAppearancePreferences, NookChromePalette, NookSurfaceStyle. The persisted, user-facing surface and chrome state. See Theming. 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. 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. 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. Source: Sources/NookKit/App/AppServices.swift.
• Multi-module hosting - NookHostConfiguration, NookModule, ClosureModule, NookModuleDescriptor, NookModuleContext, NookModuleRegistry, NookHostBranding. See 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. 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. 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. 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.
• NookNotchCutout, \.nookNotchCutout - where the hardware notch falls in the host content frame. See Layout and content insets.
• NookCompanionSurface, NookCompanionAnchor, NookCompanionVisibility, NookCompanionShape, NookCompanionBackdrop - companion surfaces at the engine level (Nook.companions), with the nookCompanionVisibility(_:) / nookCompanionHidden(_:) modifiers, \.nookCompanionIsPresented, and \.nookCompanionIsHovered. See 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.
• 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.

Both NookStyle and NookTransitionConfiguration are surfaced on NookConfiguration; see Theming and Layout and content 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. Source: Sources/NookComponents/Shelf/.
• Activities - NookActivity, NookActivityPriority, NookActivityQueue, NookActivityHost, NookActivityCard. See Activity queue. Source: Sources/NookComponents/Activities/.
• Volume - SystemVolumeObserver, VolumeReading, CoreAudioVolumeReader, NookVolumeIndicator. See Volume glyph. Source: Sources/NookComponents/Volume/.