Build Custom Modules
for Itchy

Here's a complete example of a custom Nook module with Live Activity support:

// ============================================
// 1. PLUGIN ENTRY POINT (ClockModule.swift)
// ============================================
import AppKit
import SwiftUI
import itchy

@objc(MyClockModule)
final class MyClockModule: NSObject, ItchyModulePlugin {
    
    // Module metadata - tells Itchy how to display your module
    var metadata: ItchyModuleMetadata {
        ItchyModuleMetadata(
            identifier: "com.example.clock",      // Unique reverse-DNS ID
            displayName: "Clock",                 // Shown in settings/headers
            summary: "A custom clock module",     // Short description
            preferredWidth: 220,                 // Width in Nook (min 160pt)
            placement: .nookModule,              // .nookModule or .menuApp
            iconSystemName: "clock",             // SF Symbol for menu apps
            supportsLiveActivity: true           // Enable Notch view
        )
    }
    
    // Return your SwiftUI view wrapped in NSViewController
    func makeViewController() -> NSViewController {
        NSHostingController(rootView: ClockModuleView())
    }
    
    // Called when Itchy has fully loaded your bundle
    @objc func pluginDidLoad() {
        // Start timers, send notifications, etc.
    }
    
    // --- LIVE ACTIVITY SUPPORT ---
    
    // Compact view shown in Notch when collapsed
    @objc func makeLiveActivityViewController() -> NSViewController {
        NSHostingController(rootView: ClockLiveActivityView())
    }
    
    // Control visibility (polled every second)
    @objc var isLiveActivityActive: Bool {
        return true // Always show when module is enabled
    }
    
    // Trigger instant notification (alternative to persistent mode)
    func triggerDownloadNotification() {
        ItchyLiveActivityTrigger.trigger(
            identifier: "com.example.clock",
            title: "Download",
            message: "file.zip",
            trailingMessage: "85%",      // Bold monospaced on right
            systemIcon: "arrow.down.circle.fill",
            duration: 3.0
        )
    }
}

// ============================================
// 2. SWIFTUI VIEW (ClockModuleView.swift)
// ============================================
import SwiftUI

struct ClockModuleView: View {
    @State private var now = Date()
    
    var body: some View {
        // Use nookModuleLayout() for consistent alignment
        TimelineView(.periodic(from: .now, by: 1)) { context in
            VStack(alignment: .leading, spacing: 8) {
                Text(context.date.formatted(date: .omitted, time: .standard))
                    .font(.system(size: 28, weight: .bold, design: .rounded))
                    .foregroundStyle(.white)
            }
            // Spacer ensures top alignment even if content is short
            .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
            .nookModuleLayout() // Required for consistent spacing
        }
        .background(.clear) // Keep transparent
    }
}

// Compact view for Notch (Live Activity)
struct ClockLiveActivityView: View {
    var body: some View {
        HStack(spacing: 8) {
            Image(systemName: "clock.fill")
                .font(.system(size: 14))
            Text(Date().formatted(date: .omitted, time: .shortened))
                .font(.system(size: 14, weight: .semibold, design: .monospaced))
        }
        .padding(.horizontal, 12)
        .padding(.vertical, 6)
    }
}

// ============================================
// 3. INFO.PLIST (Info.plist)
// ============================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleIdentifier</key>
  <string>com.example.itchy.clock</string>
  <key>CFBundleName</key>
  <string>ClockModule</string>
  <key>CFBundlePackageType</key>
  <string>BNDL</string>
  <key>NSPrincipalClass</key>
  <string>MyClockModule</string>
</dict>
</plist>

// ============================================
// 4. BUNDLE STRUCTURE
// ============================================
ClockModule.bundle/
  Contents/
    Info.plist
    MacOS/
      ClockModule

// ============================================
// 5. BUILD FROM TERMINAL
// ============================================
swift build

mkdir -p BuiltBundles/ClockModule.bundle/Contents/MacOS \
  BuiltBundles/ClockModule.bundle/Contents/Resources

cp Templates/ClockModule/Info.plist \
  BuiltBundles/ClockModule.bundle/Contents/Info.plist

swiftc -parse-as-library -emit-library -Xlinker -bundle \
  -module-name ClockModule \
  -I .build/arm64-apple-macosx/debug/Modules \
  Templates/ClockModule/ClockModule.swift \
  Templates/ClockModule/ClockModuleView.swift \
  .build/arm64-apple-macosx/debug/itchy.build/ItchyModulePlugin.swift.o \
  -o BuiltBundles/ClockModule.bundle/Contents/MacOS/ClockModule

// ============================================
// 6. VALIDATE BEFORE SHIPPING
// ============================================
swift run itchy-module-validator /path/to/ClockModule.bundle

Live Activities are compact views shown in the Notch when it is collapsed. They support two modes:

// Triggered Mode Example
ItchyLiveActivityTrigger.trigger(
    identifier: "com.user.mod",
    title: "Download",
    message: "file.zip",
    trailingMessage: "85%",
    systemIcon: "arrow.down.circle.fill",
    duration: 3.0
)