Skip to content

v0.1.0 - Foundation

Choose a tag to compare

View all tags
@glendonC glendonC released this 24 May 20:43
· 80 commits to main since this release
v0.1.0
7d2a735

v0.1.0 - Foundation

The first tagged release of OpenNook - an open-source Swift framework for
building macOS notch apps. The notch window, lifecycle, hotkey, settings
shell, and an opt-in components layer are all here.

This is 0.x: the public API is intentionally not frozen yet. Pin to a
tag, expect minor surface adjustments before 1.0.

What's in the box

  • NookSurface (MIT) - the notch window engine: shape, panel, hover
    behavior, translucent backdrop, shimmer feedback. Multi-display aware;
    survives fullscreen; falls back to a floating capsule on non-notched
    Macs.
  • NookKit (Apache-2.0) - the app chrome: AppCoordinator lifecycle,
    AppState, persisted appearance/display/hotkey preferences, the top bar
    • settings panels, Carbon-backed global hotkey, screen locator with
      stable display UUIDs.
  • NookApp - the library entry point. NookApp.main { MyHomeView() }
    is the headline "register a view, go" signature.
  • NookComponents (Apache-2.0, opt-in) - three production-ready
    add-ons:
    • File shelf - drop files on the notch, drag them back out (promise-
      backed, works for Mail/upload widgets), persistent across launches via
      scoped bookmarks, sandbox-aware acceptance modes.
    • Activity queue - priority-ordered transient takeovers of the
      expanded surface; yields back to the user automatically.
    • Ambient volume glyph - CoreAudio-backed indicator in the compact
      pill. No HUD interception - it's an ambient cue, not a replacement.

Highlights

  • Multiple modules in one notch. A single host can run several
    interchangeable notch surfaces sharing one window, one menu bar, and one
    set of preferences. Module switching is one atomic transaction -
    arbiter claims do not leak across modules.
  • Surface-ownership arbiter. NookSurfacePresenting generalizes the
    expand/compact save/restore pattern. Sticky owners (shelf), transient
    owners (activity), and the user (hotkey/hover) coexist without colliding.
  • Layout: auto / notch / floating. NookPresentation adapts to the
    display: notched-shape on notched displays, floating capsule on others.
    User-overridable in Settings → Appearance.
  • Optional chrome. showsTopBar / showsSettings flags strip the
    framework chrome for a bare glance/widget surface without forking.
  • Strict concurrency, every target. StrictConcurrency upcoming
    feature opted in across the package - including examples and tests, so
    the public idiom can't drift from the rules.
  • Dual-license boundary, CI-enforced. Every Swift file carries an SPDX
    header; CI fails if Sources/NookSurface/ drifts off MIT or anything
    else drifts off Apache-2.0.

Seven runnable examples

Each is a single main.swift using the public API:

swift run HelloNook     # register one view, go
swift run ClockNook     # custom home + custom compact slot
swift run ThemedNook    # host-supplied theme + lifecycle hooks
swift run ShelfNook     # drop-files shelf (NookComponents)
swift run ActivityNook  # priority live-activity queue (NookComponents)
swift run VolumeNook    # ambient volume glyph (NookComponents)
swift run MultiNook     # multiple modules sharing one surface

Install

Add OpenNook to your Package.swift:

.package(url: "https://github.com/glendonC/opennook", from: "0.1.0")

Then depend on NookApp (and optionally NookComponents) in your target.

Requirements

  • macOS 13 or later
  • Swift 5.9+
  • Apple Silicon or Intel; notched display preferred but not required

What's deliberately not in 0.1

  • No Now Playing / media integration in-package - the only working path is
    private MediaRemote, which disqualifies hosts from the Mac App Store.
    A documented out-of-tree integration is planned.
  • No brightness indicator - requires private DisplayServices on Apple
    Silicon. Volume is shipped (CoreAudio is fully public).
  • No native HUD suppression - would require SIP-off / event interception,
    not viable for a framework.

Licensing

  • Everything is Apache-2.0 except Sources/NookSurface/, which is
    MIT (forked from
    DynamicNotchKit by Kai
    Azim). Both licenses are permissive; you can ship closed-source on top.
  • See LICENSE, LICENSE-MIT-NOOKSURFACE, NOTICE.md, and
    ThirdPartyLicenses/.

Thanks

Built on top of Kai Azim's
DynamicNotchKit. The
chrome-primitive layer remains MIT and acknowledges the upstream
throughout - see NOTICE.md for the full attribution.

Assets 2
Loading