Playground

Examples/PlaygroundNook is a live customization playground. A controls window beside the running nook changes its appearance, theme, size and shape, type and motion, top bar, companion surfaces, rim glow, scroll edge fade, and hover behavior - and, on the Tokens page, any single theme token - and the real nook - not a mock - updates as you go. When it looks right, copy the result as Swift that sets only what you changed, save it as a JSON preset to share or open later, or copy the theme alone as a theme file.

swift run PlaygroundNook

The window

The playground opens a regular, resizable window next to the nook. The nook starts as the stock chrome, so everything you see change is something you changed.

The sidebar lists the pages. A dot marks a page with changes, and right-clicking a page resets it.
At the top right, Keep Open holds the nook open while you work in the window, Expand opens or collapses the nook, and Code shows or hides the code.
The code on the right is the Swift snippet or the JSON preset for what you have now, updated as you change it, with a button to copy it.

Each page groups its settings into cards, with one control column so every control lines up. Settings most people leave alone - content insets, metrics, extra theme colors, the chrome’s labels - are folded into a row until you open it; a dot on the row means something inside has changed. Hover a label or an info icon to see what it does. A changed value shows a reset arrow beside its label, a changed card shows Reset, and applying a preset or resetting a page can be undone from the confirmation at the bottom of the window. The window follows the Mac’s light or dark appearance.

The controls are in a window rather than in the nook itself: the nook changes shape as you edit it, collapses when the pointer leaves, and has no room for text fields and color pickers. While the window is open the playground is a regular app with a Dock icon and a menu bar, so Command-Tab reaches it and text fields get the usual editing shortcuts. Closing the window returns it to a menu-bar-only app; the Controls button in the nook brings the window back.

Two launch options help when you try presets:

swift run PlaygroundNook --preset my-preset.json   # open a preset at launch
swift run PlaygroundNook --sample glass            # media, glass, glance, call, or defaults
swift run PlaygroundNook --expand                  # open the nook at launch
swift run PlaygroundNook --keep-open               # hold the nook expanded
swift run PlaygroundNook --hide-controls           # skip the controls window

What you can change

Page	Changes	Lands on
Appearance	layout, palette, material, backdrop strength, accent, haptics; under Opening, what hovering the pill does and its waits	`AppState.appearancePreferences`
Theme	font design and width; corner, scale, and motion knobs; accent, label, fill, stroke, hover, status, and inactive icon colors; the backdrop of each material (framework, solid, frosted, Liquid Glass with its variant, linear, radial, elliptical, and angular gradients, mesh) and the theme’s glass shading; under Theme File, the name, pins, sound volume, and what the person may change	`NookConfiguration.chromeTheme`
Panel	expanded width, corner radii, content insets, a few metrics	`expandedWidth`, `style`, `metrics`
Type and Motion	four typography roles, the Settings and banner springs	`typography`, `motion`
Top Bar	top bar and Settings switches, width, leading title and icon, notch clearance, labels and the Settings group titles, the lock, gear, separator, and back symbols	`topBar`, `topBar.symbols`, `labels`
Companions	the size, look, and entrance every companion shares; add, duplicate, remove, and reorder companions; the selected one’s items, placement, style, and details	`companionSize`, `companionStyle`, `companionPresence`, `addCompanion(...)`
Effects	rim style, scroll edge fade edges and length, the chrome’s shadow	`rimGlow`, `scrollEdgeFade`, the theme’s `shadow.chrome`
Behavior	hover keeps visible, hover haptics, glass shading	`chromeBehavior.hoverBehavior`, `chromeBehavior.glassShading`
Activities	starts, alerts, and ends three sample live activities, to see the pill shared and the peek; the song’s cover is a shared element; not part of a preset	the module’s `NookLiveActivities`, `nookSharedElement(_:style:)`
Widgets	shows sample widgets on a grid in the nook’s home, with the columns, sizes, and card style you pick; not part of a preset	`NookWidget`, `NookWidgetGrid`
Tokens	any theme token by id: colors, numbers, fonts, animations, content transitions, sounds, shadows	`NookConfiguration.chromeTheme` tokens

Some controls exist only to show a setting off. Preview on the Top Bar page posts a status banner, and on the Type and Motion page switches between home and Settings. The Effects page lights the rim and fills the nook with a list and a row of chips that scroll. Header beside notch on the Top Bar page moves the nook’s own header into the band beside the notch with nookNotchAccessories(leading:trailing:); with the top bar off, it shows what clearing the notch does. The theme colors start as Live - the palette the chrome resolves from the user’s preferences - until you pick a color.

The Theme File card on the Theme page holds what a theme says beyond its look. Its pins replace the person’s palette, material, or backdrop strength while the theme is on, so a pinned value wins over the Appearance page, as it would in any host.

The Tokens page

Every value a chrome theme can set has a stable dotted id, such as banner.cornerRadius or motion.content.enter. The Tokens page, under Advanced, lists them all, grouped by the first part of the id, and the list comes from the framework itself (NookTokenDescriptor.all), so a token the framework adds shows up with no change to the playground.

Search filters by id; Changed only shows the tokens you have overridden.
Each row shows what the token resolves to now - with the theme’s knobs applied and any reference followed - and a dot and a reset arrow when it is overridden.
Opening a row shows an editor for its kind: a color as one color, a pair for dark and light chrome, the accent at an opacity, or another color token; a number as a value or another number token times a factor; a font’s role, size, weight, design, width, family, and digits; a spring, a named spring, a timing curve, a Bezier curve, or another animation; a transition’s opacity, blur, scale, anchor, offset, and curve; a system, bundled, or file sound and its volume, with a button to hear it; and a shadow’s color, radius, and offset.

An override is stored as a token override in the theme, so it reaches the nook, the Swift export, the preset, and the theme file exactly as the Theme page’s values do. A color one of the Theme page’s roles sets is the same value on both pages. Where a hand-built page sets the same thing - the Panel page’s metrics and shape, or the fonts and springs on Type and Motion - that page’s value wins while it is changed there, as NookConfiguration documents for metrics, typography, motion, and style, and the token’s row says so.

Composing companions

A companion holds a list of items, each one of:

a button - an SF Symbol, a name, a glyph color, a fill (none, subtle, a color, or the nook’s material) with an optional fade, a size, and an action (post a status, toggle the rim glow, keep open, Settings, or collapse);
a label - an SF Symbol and some text;
the nook’s own lock or gear.

A group of controls is one companion with several items, laid out in a row or a column; a control that stands apart is a companion of its own. Add starts a companion from a template - an action pill, a round button, the nook controls, a status chip, or nothing - and its Content tab adds, reorders, and edits the items. The Every Companion card sets the size, entrance, fade, edge, shadow, and hover every companion shares, and each companion’s Style tab can set its own, with Default following the card. A button sized Surface is as tall as the companion and draws its own surface, so a companion holding only those draws none around them and takes the .plain style.

How a change reaches the nook

The playground is a NookModule whose makeConfiguration() builds a NookConfiguration from its current settings. After each change it calls reloadActiveConfiguration() on the coordinator, which builds the configuration again and applies it to the running chrome. A slider drag changes the settings many times a second, so the playground applies them once per main-actor turn, inside withAnimation.

Two things take a different path, as they would in any app. The appearance preferences belong to the user, so the playground writes them to AppState with replaceAppearancePreferences(_:), as the built-in Settings screen does. Hover behavior belongs to the whole host rather than to a module, so it goes through replaceChromeBehavior(_:). Nothing needs a relaunch.

Doing the same in your app

Any module whose configuration depends on state that changes at runtime - its own preferences, a feature flag, a live preview - can use the same seam. Build the configuration from that state in makeConfiguration(), keep the coordinator from onReady, and reload when the state changes:

@MainActor
final class DashboardModule: NookModule {
    nonisolated static let moduleDescriptor = NookModuleDescriptor(
        id: "com.example.dashboard",
        displayName: "Dashboard"
    )

    let descriptor = DashboardModule.moduleDescriptor
    private let preferences = DashboardPreferences()   // your own state
    private weak var coordinator: AppCoordinator?

    func makeConfiguration() -> NookConfiguration {
        var configuration = NookConfiguration()
        configuration.setHome { DashboardHome() }
        configuration.expandedWidth = preferences.isWide ? 640 : nil
        if preferences.showsTimer {
            configuration.addCompanion(id: "timer", visibility: .both, shape: .circle) { TimerButton() }
        }
        configuration.onReady = { [weak self] coordinator in
            self?.coordinator = coordinator
        }
        return configuration
    }

    func setShowsTimer(_ showsTimer: Bool) {
        preferences.showsTimer = showsTimer
        withAnimation(.snappy) { coordinator?.reloadActiveConfiguration() }
    }
}

A reload applies everything a module switch applies - the home and compact content, theme, top bar, labels, metrics, motion, typography, width, lifecycle hooks, file-drop handler, companions, rim glow, and scroll edge fade - and leaves Settings when the new configuration turns Settings off. It also applies style and transitions, which the chrome otherwise reads only at launch. It does not call onActivate() or onReady again, and it leaves the nook in whatever state it was in.

A few things stay as they are:

The process-wide values a single-module configuration carries - preferenceDefaults, chromeBehavior, branding, and showsMenuBarExtra - are read once at launch. Use replaceChromeBehavior(_:) to change chrome behavior.
NookApp.main(configuration) wraps one fixed configuration, so a reload hands the same value back. Register a module, or a configuration closure with host.register(_:configuration:), to build a new one each time.

At the NookSurface level, Nook.style and Nook.hoverBehavior are settable, so a host driving a Nook directly can restyle it in place too.

Exporting Swift

The Swift export targets the single-module NookConfiguration path and sets only the values that differ from the framework’s defaults, so an untouched playground exports an empty configuration. Copy it from the code card, or from the Presets page:

import NookApp
import SwiftUI

var configuration = NookConfiguration()
configuration.setHome { MyHomeView() }  // your home view

configuration.expandedWidth = 420
configuration.style = NookConfiguration.defaultStyle
configuration.style?.bottomCornerRadius = 30

configuration.topBar.showsKeepOpenButton = false
configuration.topBar.showsSettingsButton = false

// How every companion looks and appears, unless it says otherwise.
configuration.companionStyle = .faded

configuration.addCompanion(id: "controls", anchor: .trailing, hidesInSettings: false) {
    ControlsCompanion()
}

NookApp.main(configuration)

// MARK: - Companion content

struct ControlsCompanion: View {
    var body: some View {
        VStack(spacing: 2) {
            NookKeepOpenButton()
            NookSettingsButton()
        }
    }
}

Each companion’s items are written out as a view of its own, named after the companion: glyph buttons with .nookGlyph, labels, and the framework’s lock and gear. A button’s action is a comment to replace with yours, except the ones the framework runs - keep open, Settings, and collapse - which call NookChromeActions. A companion with no items is hidden in the playground, so it is left out, with a comment saying so.
The home view appears as a placeholder - MyHomeView, and with a header beside the notch HeaderTitle and HeaderButtons - for you to replace with yours.
With Header beside notch on, the home view is wrapped in a small view type that applies nookNotchAccessories(leading:trailing:), since setHome(_:) takes a Sendable view.
Changed appearance preferences become preferenceDefaults, a launch seed: they set the first run, and a choice the user later makes in Settings wins. Keep Open is left out, since the playground uses it only to hold the nook open.
A changed shape starts from NookConfiguration.defaultStyle, so only the values you moved appear.
A changed rim glow style comes with a reminder that the rim only shows while some content lights it with nookRimGlow(_:).

The theme becomes a NookTheme with its knobs as initializer arguments, then one line per color, token override, and backdrop:

var theme = NookTheme(fontDesign: .rounded, motion: .calm)
theme.accent = "#FF8000"
theme.tokens[NookDimensionID("banner.cornerRadius")] = 12
theme.tokens[NookShadowID("shadow.chrome")] = NookShadowSpec(radius: 10, y: 4)
theme.backdrops.liquidGlass = .liquidGlass(.init(tint: .accent, variant: .clear))
configuration.chromeTheme = theme

In a multi-module host, the configuration lines go in a module’s makeConfiguration(), and preferenceDefaults and chromeBehavior go on NookHostConfiguration instead.

JSON presets

A preset is the playground’s settings plus the appearance preferences they were tuned against. The Presets page copies, pastes, saves, and opens them, and offers a few built-in starting points; applying one can be undone. The playground writes every key, sorted, so presets diff cleanly under version control, and writes colors as #RRGGBB or #RRGGBBAA. A preset written by hand can be much shorter:

{
  "appearance" : {
    "chromePalette" : "dark",
    "presentation" : "floating",
    "surfaceStyle" : "liquidGlass"
  },
  "format" : "opennook.playground-preset",
  "settings" : {
    "companionDefaults" : { "fade" : 0.35, "hover" : "lift" },
    "companions" : [
      {
        "alignment" : "end",
        "id" : "status",
        "items" : [ { "symbol" : "sparkles", "title" : "3 new", "type" : "label" } ]
      },
      {
        "gap" : 16,
        "id" : "leave",
        "items" : [
          { "action" : "collapse", "fill" : "color", "fillColor" : "#FF3B30",
            "size" : "surface", "symbol" : "phone.down.fill", "tint" : "#FFFFFF",
            "title" : "Leave", "type" : "button" }
        ],
        "backdrop" : "none",
        "outline" : "circle"
      }
    ],
    "panel" : { "expandedWidth" : 440 },
    "theme" : { "accent" : "#FA5C85", "fontDesign" : "rounded" }
  },
  "version" : 1
}

Presets are read leniently:

A missing key takes its default, so a hand-written preset can hold only the values it cares about, and a preset from an earlier playground still opens.
An unknown key is ignored.
A value of the wrong type, or a choice the playground does not know, is an error that names the JSON path of the value - for example settings.panel.expandedWidth should be a number.
A preset whose version is newer than the playground reads is refused rather than misread.
Companion ids are made unique and non-empty, and negative lengths become zero, since addCompanion traps on a duplicate id. Fades are kept between 0 and 1, and a companion keeps at most twelve items.
A companion from an earlier playground names its content with kind (actions, button, controls, or chip) rather than listing items, and opens with the items that kind stood for. The playground writes items from then on.

Keep Open is never part of a preset, and neither are the demo switches - the lit rim, the scrolling demo, the banner message - which the playground remembers separately.

Token overrides sit under settings.theme.tokens, one member per id in the form a theme file writes it, and theme backdrops under settings.theme.backdrops. A key the playground added after a preset was written is left out until you change it, so every older preset still opens and writes back with the keys it had:

"theme" : {
  "fontDesign" : "rounded",
  "tokens" : {
    "banner.cornerRadius" : 12,
    "color.label.tertiary" : { "dark" : { "white" : 0.5 }, "light" : "accent" },
    "motion.statusBanner" : "{spring.snappy}",
    "shadow.chrome" : { "radius" : 10, "y" : 4 }
  }
}

A token id the framework does not define is skipped, and a value of the wrong kind for its token is an error that names it, such as settings.theme.tokens.space.md: expected a number or a token such as "{space.md}".

Theme files

Theme under Share on the Presets page copies the theme alone - the Theme page, the token overrides, and the chrome’s shadow - as a framework theme file ({"format": "opennook.theme", "version": 1, ...}), which any host loads with NookTheme(contentsOf:) or follows live with NookThemeSource.watching(fileAt:). It lists only what differs from NookTheme.standard: semantic tokens under tokens, the chrome’s own fields under components. The appearance preferences, companions, top bar, and the other pages are not part of a theme, so they stay in the preset and the Swift export.

The assistant

The assistant proposes changes to the same settings the pages edit, including token overrides by id under settings.theme.tokens and theme backdrops. Its schema lists every token id from the framework’s registry, and an id the registry does not define is sent back to the model to correct rather than dropped. Each token it changes is a row of its own under Tokens in the proposal, which you can switch off before applying.

Under swift run the playground is an unbundled, unsandboxed binary, so the save and open panels cannot enter the folders macOS protects (Desktop, Documents, Downloads). Use another folder, or copy and paste the JSON.

Where the playground keeps its state

The settings and demo switches live in the module’s own defaults suite, context.defaults (opennook.module.com.opennook.example.playground), like any module’s state.
The appearance preferences live where the framework keeps them for any host.
The window’s own choices, such as which folded rows are open and whether the code shows, live in the app’s standard defaults.
Reset beside Everything on the Presets page returns the settings and the appearance to the defaults.

How the example is built

The playground is bigger than the other examples, so it spans several files:

Examples/PlaygroundNook/Core - the PlaygroundNookCore target: the settings model (PlaygroundSettings), presets and their JSON coder (PlaygroundPreset, PlaygroundPresetCoder), the Swift exporter (PlaygroundSwiftExporter), and the store. The exporters are pure, and Tests/PlaygroundNookTests covers them, including a check that every default still matches the framework’s.
Examples/PlaygroundNook/App - the module, the model that applies changes, the controls window, and the views shown in the nook.