Notification System Design Patterns

Org Status: 🟢 Active Cloudflare: N/A Last Audited: 2026-04-28

Every notification system faces the same fundamental tension: sources want attention, users want peace. iOS solves this with interruption levels and Focus modes. Android solves it with notification channels and importance levels. Linux solves it with D-Bus urgency hints. Car dashboards solve it with NHTSA-compliant priority preemption. Smart displays solve it with proximity-aware rendering.

But what happens when you’re building a tiny ambient display — a macOS notch HUD where multiple AI agents, system monitors, and user scripts all compete for a single line of text? None of these systems map directly. You need to understand all of them, extract the patterns that work, and design something new.

What you’ll learn:

• How iOS, macOS, Android, and Linux each handle notification priority, grouping, and filtering
• The design patterns behind Dynamic Island, Focus modes, and notification channels
• How smart displays, car dashboards, and smartwatches manage competing information
• Conflict resolution strategies: preemption, queuing, time-sharing, summarization
• A complete TypeScript API design for an intelligent notification HUD
• Policy engine architecture with rules for what shows, when, and for how long
• How to handle RSVP interruption, simultaneous senders, and quiet hours

You have a programmable status bar embedded in a macOS notch. The display area is roughly 600 pixels wide and 28 pixels tall — enough for one line of text, maybe a small icon. Multiple sources want to use it:

• AI agents (Athena, Jane) reporting system status, task completion, anomalies
• System monitors tracking CPU, memory, network, battery
• User scripts showing timers, reminders, weather, music info
• Cloud services sending webhook notifications
• RSVP reader cycling through text at 300+ words per minute

These sources don’t coordinate with each other. They don’t know what else is trying to display. They each think their content is important. Without a policy layer, the display becomes a seizure-inducing mess of flickering text.

The existing approaches all fall short for this use case:

What changes if you get this right:

• The notch becomes a calm technology — information at a glance without cognitive load
• AI agents can communicate status without interrupting focused work
• Urgent alerts break through immediately while ambient data flows smoothly
• Users retain control over their attention without needing to configure dozens of settings

1. Interruption Levels

Every notification system, regardless of platform, implicitly or explicitly defines interruption levels. The concept determines whether a notification can break through the user’s current context.

/**
 * Universal interruption level taxonomy derived from iOS, Android,
 * and Linux notification systems.
 *
 * iOS: passive | active | timeSensitive | critical
 * Android: MIN | LOW | DEFAULT | HIGH (maps to importance)
 * Linux: low | normal | critical
 * Pushover: -2 | -1 | 0 | 1 | 2
 */
enum InterruptionLevel {
  /** Silent. No visual change. Logged only.
   *  iOS: passive. Android: IMPORTANCE_MIN. Linux: low. */
  SILENT = 0,

  /** Ambient. Updates display if nothing else is showing.
   *  iOS: passive. Android: IMPORTANCE_LOW. Linux: low. */
  AMBIENT = 1,

  /** Standard. Shown at next opportunity (after current content expires).
   *  iOS: active. Android: IMPORTANCE_DEFAULT. Linux: normal. */
  STANDARD = 2,

  /** Elevated. Preempts ambient/standard content within 2 seconds.
   *  iOS: active (with sound). Android: IMPORTANCE_HIGH. Linux: normal. */
  ELEVATED = 3,

  /** Urgent. Immediately preempts everything except critical.
   *  iOS: timeSensitive. Android: IMPORTANCE_HIGH (heads-up). Linux: critical. */
  URGENT = 4,

  /** Critical. Bypasses all filters, quiet hours, focus modes.
   *  iOS: critical (requires Apple entitlement). Android: foreground service.
   *  Linux: critical. Pushover: emergency (2). */
  CRITICAL = 5,
}

Key insight: iOS nailed the taxonomy with four levels, but for an ambient display you need six. The gap between “passive” and “active” is too wide — you need AMBIENT (update if idle) and STANDARD (show at next opportunity) as distinct behaviors.

2. Notification Channels

Android introduced notification channels in API 26 (Oreo) as a way to give users per-category control over notification behavior. The concept is powerful: instead of per-app settings, you have per-purpose settings.

/**
 * A channel defines a category of notifications with shared behavior.
 * Users can override the default importance of any channel.
 *
 * Android requires channels since API 26.
 * iOS achieves similar grouping via notification categories.
 * Our HUD uses channels to partition display time.
 */
interface NotificationChannel {
  /** Unique identifier. Once created, the ID cannot change. */
  id: string;

  /** Human-readable name shown in settings UI. */
  name: string;

  /** Description of what this channel carries. */
  description: string;

  /** Default interruption level for notifications in this channel. */
  defaultLevel: InterruptionLevel;

  /** User override. If set, takes precedence over defaultLevel. */
  userOverride?: InterruptionLevel;

  /** Whether the user has muted this channel entirely. */
  muted: boolean;

  /** Maximum notifications per minute from this channel. */
  rateLimit: number;

  /** How to handle multiple notifications: replace, queue, or summarize. */
  collapseStrategy: "replace" | "queue" | "summarize";

  /** Display duration in milliseconds. null = until displaced. */
  defaultTTL: number | null;

  /** Visual style hint. */
  style?: "text" | "metric" | "progress" | "alert";
}

Key insight: Android’s fatal design flaw is that channel importance cannot be changed programmatically after creation. This is a feature for user trust — it prevents apps from escalating their own importance. Our HUD should adopt this: sources declare channels, but only the user (or the policy engine) can change their effective importance.

3. Notification Identity and Lifecycle

Every notification needs a lifecycle — it’s created, displayed, potentially updated, and eventually expires or is dismissed. The freedesktop.org D-Bus specification handles this elegantly with replaces_id.

/**
 * A notification is a discrete unit of information with an identity
 * and a lifecycle.
 *
 * Mirrors the freedesktop.org Notify method signature:
 * UINT32 Notify(app_name, replaces_id, icon, summary, body, actions, hints, expire_timeout)
 *
 * And Firebase Cloud Messaging's collapse_key concept:
 * Messages with the same collapse_key replace each other.
 */
interface Notification {
  /** Unique ID assigned by the notification system. */
  id: string;

  /** Source identifier (app, agent, service). */
  source: string;

  /** Channel this notification belongs to. */
  channel: string;

  /** If set, this notification replaces an existing one with this ID.
   *  Equivalent to freedesktop replaces_id or FCM collapse_key. */
  replacesId?: string;

  /** The content to display. */
  content: NotificationContent;

  /** Interruption level. Defaults to channel's default if not set. */
  level?: InterruptionLevel;

  /** When this notification was created. */
  createdAt: number;

  /** When this notification expires. null = no expiry. */
  expiresAt: number | null;

  /** Current state in the lifecycle. */
  state: "pending" | "active" | "displayed" | "expired" | "dismissed";

  /** Number of times this notification has been updated via replacesId. */
  updateCount: number;

  /** Relevance score for summary ordering (0-1).
   *  iOS uses this for notification summary ranking. */
  relevanceScore?: number;
}

interface NotificationContent {
  /** Short text for the status bar (max ~60 chars). */
  summary: string;

  /** Longer text for hover/expanded view. */
  body?: string;

  /** Structured data for metric display. */
  metric?: { label: string; value: string; trend?: "up" | "down" | "flat" };

  /** Icon identifier or emoji. */
  icon?: string;

  /** Severity coloring. */
  severity?: "green" | "yellow" | "red";

  /** Actions the user can take (like iOS actionable notifications). */
  actions?: NotificationAction[];
}

interface NotificationAction {
  /** Unique action identifier. */
  id: string;

  /** Display label. */
  label: string;

  /** URL or callback identifier to invoke. */
  handler: string;

  /** Whether this action is destructive (shown in red). */
  destructive?: boolean;
}

Key insight: The replacesId pattern from freedesktop.org is essential for an ambient display. Without it, a CPU monitor sending updates every second would flood the queue. With it, each update replaces the previous one — the display always shows the latest value. FCM calls this “collapsible messages” and limits you to 4 simultaneous collapse keys per device.

4. Focus Modes

iOS 15 introduced Focus modes as a generalization of Do Not Disturb. Android has a simpler DND with priority exceptions. Both recognize that notification filtering should be contextual — different rules for different situations.

/**
 * A focus mode defines a notification filtering policy that activates
 * based on time, location, or manual toggle.
 *
 * iOS Focus modes: Work, Personal, Sleep, Driving, custom
 * Android: Do Not Disturb with priority exceptions
 * Grafana: Mute timings (recurring) vs silences (one-time)
 */
interface FocusMode {
  /** Unique identifier. */
  id: string;

  /** Human-readable name. */
  name: string;

  /** Whether this focus mode is currently active. */
  active: boolean;

  /** Channels that are allowed through during this focus mode. */
  allowedChannels: string[];

  /** Sources that are allowed through regardless of channel. */
  allowedSources: string[];

  /** Minimum interruption level that can break through.
   *  Everything below this level is suppressed. */
  minimumLevel: InterruptionLevel;

  /** Schedule for automatic activation. */
  schedule?: FocusModeSchedule;

  /** What to show instead of suppressed notifications. */
  fallback: "nothing" | "count" | "summary";
}

interface FocusModeSchedule {
  /** Days of the week (0=Sunday). */
  days: number[];

  /** Start time in HH:MM format. */
  startTime: string;

  /** End time in HH:MM format. */
  endTime: string;

  /** Timezone. */
  timezone: string;
}

Key insight: Grafana’s distinction between “mute timings” (recurring, like weekends) and “silences” (one-time, like a maintenance window) is more useful than iOS’s Focus model for a HUD. You want both: scheduled quiet hours AND the ability to say “mute everything for 30 minutes while I present.”

Pattern 1: Priority Queue with Preemption

The most fundamental pattern. Every notification enters a priority queue. The display always shows the highest-priority item. When a higher-priority notification arrives, it preempts what’s currently showing.

When to use it: As the base layer of any notification display system. Every other pattern builds on this.

/**
 * Priority queue with preemption for a single-line display.
 *
 * Implements the core display scheduling algorithm:
 * 1. Notifications enter the queue sorted by priority
 * 2. The display always shows the head of the queue
 * 3. Higher-priority items preempt lower-priority ones
 * 4. Items expire based on TTL and are removed
 * 5. When the current item expires, the next one shows
 *
 * This mirrors how car dashboards work: navigation directions
 * preempt music info, incoming calls preempt navigation,
 * collision warnings preempt everything.
 */
class NotificationPriorityQueue {
  private queue: QueueEntry[] = [];
  private currentDisplay: QueueEntry | null = null;
  private displayCallback: (entry: QueueEntry | null) => void;
  private expiryTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();

  constructor(onDisplayChange: (entry: QueueEntry | null) => void) {
    this.displayCallback = onDisplayChange;
  }

  /**
   * Submit a notification to the queue.
   * Returns the assigned queue position.
   */
  submit(notification: Notification): number {
    const entry: QueueEntry = {
      notification,
      effectivePriority: this.calculatePriority(notification),
      enqueuedAt: Date.now(),
      displayedAt: null,
    };

    // Check if this replaces an existing notification
    if (notification.replacesId) {
      const existingIndex = this.queue.findIndex(
        (e) => e.notification.id === notification.replacesId
      );
      if (existingIndex !== -1) {
        const existing = this.queue[existingIndex];
        entry.notification.updateCount = existing.notification.updateCount + 1;
        this.queue.splice(existingIndex, 1);
        this.clearExpiryTimer(notification.replacesId);
      }
    }

    // Insert in priority order (highest first)
    const insertIndex = this.queue.findIndex(
      (e) => e.effectivePriority < entry.effectivePriority
    );
    if (insertIndex === -1) {
      this.queue.push(entry);
    } else {
      this.queue.splice(insertIndex, 0, entry);
    }

    // Set expiry timer
    if (notification.expiresAt) {
      const delay = notification.expiresAt - Date.now();
      if (delay > 0) {
        const timer = setTimeout(() => {
          this.expire(notification.id);
        }, delay);
        this.expiryTimers.set(notification.id, timer);
      } else {
        // Already expired, don't even queue it
        return -1;
      }
    }

    // Check if this should preempt the current display
    this.evaluateDisplay();

    return this.queue.findIndex(
      (e) => e.notification.id === notification.id
    );
  }

  /**
   * Calculate effective priority from notification properties.
   *
   * Priority is a composite score:
   * - Base: interruption level (0-5) * 1000
   * - Boost: relevance score * 100
   * - Decay: time-based decay for aging notifications
   * - Escalation: +500 if notification has been waiting too long
   */
  private calculatePriority(notification: Notification): number {
    const level = notification.level ?? InterruptionLevel.STANDARD;
    let priority = level * 1000;

    // Relevance score boost (0-100 points)
    if (notification.relevanceScore !== undefined) {
      priority += notification.relevanceScore * 100;
    }

    return priority;
  }

  /**
   * Evaluate whether the current display should change.
   * Called after every queue mutation.
   */
  private evaluateDisplay(): void {
    if (this.queue.length === 0) {
      if (this.currentDisplay !== null) {
        this.currentDisplay = null;
        this.displayCallback(null);
      }
      return;
    }

    const topEntry = this.queue[0];

    // Nothing currently displayed — show the top item
    if (!this.currentDisplay) {
      this.showEntry(topEntry);
      return;
    }

    // Something is displayed — check if the top item should preempt it
    const currentPriority = this.currentDisplay.effectivePriority;
    const newPriority = topEntry.effectivePriority;

    if (topEntry.notification.id === this.currentDisplay.notification.id) {
      // Same notification (possibly updated) — refresh display
      this.showEntry(topEntry);
      return;
    }

    if (newPriority > currentPriority) {
      // Higher priority — preempt
      this.showEntry(topEntry);
      return;
    }

    // Lower or equal priority — wait for current to expire
  }

  private showEntry(entry: QueueEntry): void {
    entry.displayedAt = Date.now();
    entry.notification.state = "displayed";
    this.currentDisplay = entry;
    this.displayCallback(entry);
  }

  /**
   * Remove an expired notification from the queue.
   */
  private expire(notificationId: string): void {
    const index = this.queue.findIndex(
      (e) => e.notification.id === notificationId
    );
    if (index !== -1) {
      this.queue[index].notification.state = "expired";
      this.queue.splice(index, 1);
    }
    this.clearExpiryTimer(notificationId);

    // If the expired item was being displayed, show the next one
    if (this.currentDisplay?.notification.id === notificationId) {
      this.currentDisplay = null;
      this.evaluateDisplay();
    }
  }

  private clearExpiryTimer(notificationId: string): void {
    const timer = this.expiryTimers.get(notificationId);
    if (timer) {
      clearTimeout(timer);
      this.expiryTimers.delete(notificationId);
    }
  }

  /**
   * Dismiss a notification (user action).
   */
  dismiss(notificationId: string): void {
    const index = this.queue.findIndex(
      (e) => e.notification.id === notificationId
    );
    if (index !== -1) {
      this.queue[index].notification.state = "dismissed";
      this.queue.splice(index, 1);
    }
    this.clearExpiryTimer(notificationId);

    if (this.currentDisplay?.notification.id === notificationId) {
      this.currentDisplay = null;
      this.evaluateDisplay();
    }
  }

  /** Get queue state for debugging/UI. */
  getState(): { current: QueueEntry | null; queued: QueueEntry[] } {
    return {
      current: this.currentDisplay,
      queued: [...this.queue],
    };
  }
}

interface QueueEntry {
  notification: Notification;
  effectivePriority: number;
  enqueuedAt: number;
  displayedAt: number | null;
}

Gotchas:

• Priority inversion: a long-TTL medium-priority notification can block lower-priority items indefinitely. Solution: add a maximum display time per priority level.
• Starvation: if high-priority sources keep sending, low-priority content never shows. Solution: time-sharing (Pattern 3).
• Thundering herd: if 10 agents all send ELEVATED notifications at once, which one wins? Solution: use relevance score as a tiebreaker, then FIFO within the same level.

Connection to other patterns: This is the foundation. Pattern 2 (Rate Limiting) prevents queue flooding. Pattern 3 (Time-Sharing) prevents starvation. Pattern 4 (Channel Policies) maps source behavior to queue priorities.

Pattern 2: Rate Limiting and Notification Budget

iOS throttles notifications from noisy apps. Android rate-limits notification updates. Firebase Cloud Messaging has a per-device notification budget. Pushover limits emergency retries. Every system needs rate limiting to prevent abuse.

When to use it: Always. Without rate limiting, a single misbehaving source can monopolize the display.

/**
 * Rate limiter for notification sources.
 *
 * Implements three strategies:
 * 1. Token bucket: allows bursts but limits sustained rate
 * 2. Sliding window: hard limit per time window
 * 3. Adaptive: adjusts limits based on user engagement
 *
 * iOS budget system: undocumented per-device budget, progressive
 * throttling for background execution.
 * Android: automatically groups when an app sends 4+ notifications.
 * FCM: can store max 4 collapsible messages per device per collapse key.
 * Pushover emergency: retry every 30+ seconds, expire after N seconds.
 */
class NotificationRateLimiter {
  private buckets: Map<string, TokenBucket> = new Map();
  private windowCounters: Map<string, SlidingWindowCounter> = new Map();
  private channelLimits: Map<string, ChannelRateConfig> = new Map();

  constructor(private defaultConfig: RateLimitConfig) {}

  /**
   * Register rate limit configuration for a channel.
   */
  configureChannel(channelId: string, config: ChannelRateConfig): void {
    this.channelLimits.set(channelId, config);
  }

  /**
   * Check if a notification from a source/channel is allowed.
   * Returns { allowed, retryAfterMs, reason }.
   */
  check(
    source: string,
    channel: string,
    level: InterruptionLevel
  ): RateLimitResult {
    // Critical notifications bypass rate limiting entirely
    // This mirrors iOS critical alerts that bypass all controls
    if (level >= InterruptionLevel.CRITICAL) {
      return { allowed: true };
    }

    const channelConfig = this.channelLimits.get(channel);
    const config = channelConfig ?? this.defaultConfig;

    // Check source-level rate limit (token bucket)
    const sourceKey = `${source}:${channel}`;
    let bucket = this.buckets.get(sourceKey);
    if (!bucket) {
      bucket = new TokenBucket(
        config.maxBurst,
        config.refillRate,
        config.refillIntervalMs
      );
      this.buckets.set(sourceKey, bucket);
    }

    if (!bucket.tryConsume()) {
      return {
        allowed: false,
        retryAfterMs: bucket.msUntilNextToken(),
        reason: `Source ${source} exceeded burst limit for channel ${channel}`,
      };
    }

    // Check global per-source limit (sliding window)
    let counter = this.windowCounters.get(source);
    if (!counter) {
      counter = new SlidingWindowCounter(
        config.windowMs,
        config.maxPerWindow
      );
      this.windowCounters.set(source, counter);
    }

    if (!counter.tryIncrement()) {
      return {
        allowed: false,
        retryAfterMs: counter.msUntilWindowSlides(),
        reason: `Source ${source} exceeded ${config.maxPerWindow} notifications per ${config.windowMs}ms`,
      };
    }

    return { allowed: true };
  }
}

/**
 * Token bucket algorithm for burst-tolerant rate limiting.
 * Allows short bursts while limiting sustained throughput.
 */
class TokenBucket {
  private tokens: number;
  private lastRefill: number;

  constructor(
    private maxTokens: number,
    private refillRate: number,
    private refillIntervalMs: number
  ) {
    this.tokens = maxTokens;
    this.lastRefill = Date.now();
  }

  tryConsume(): boolean {
    this.refill();
    if (this.tokens >= 1) {
      this.tokens -= 1;
      return true;
    }
    return false;
  }

  msUntilNextToken(): number {
    this.refill();
    if (this.tokens >= 1) return 0;
    return this.refillIntervalMs;
  }

  private refill(): void {
    const now = Date.now();
    const elapsed = now - this.lastRefill;
    const tokensToAdd = Math.floor(
      (elapsed / this.refillIntervalMs) * this.refillRate
    );
    if (tokensToAdd > 0) {
      this.tokens = Math.min(this.maxTokens, this.tokens + tokensToAdd);
      this.lastRefill = now;
    }
  }
}

/**
 * Sliding window counter for hard rate limits.
 */
class SlidingWindowCounter {
  private timestamps: number[] = [];

  constructor(
    private windowMs: number,
    private maxCount: number
  ) {}

  tryIncrement(): boolean {
    const now = Date.now();
    const windowStart = now - this.windowMs;

    // Remove expired timestamps
    this.timestamps = this.timestamps.filter((t) => t > windowStart);

    if (this.timestamps.length >= this.maxCount) {
      return false;
    }

    this.timestamps.push(now);
    return true;
  }

  msUntilWindowSlides(): number {
    if (this.timestamps.length === 0) return 0;
    const oldest = this.timestamps[0];
    return Math.max(0, oldest + this.windowMs - Date.now());
  }
}

interface RateLimitConfig {
  /** Maximum burst size (tokens). */
  maxBurst: number;
  /** Tokens refilled per interval. */
  refillRate: number;
  /** Interval for token refill in ms. */
  refillIntervalMs: number;
  /** Sliding window size in ms. */
  windowMs: number;
  /** Max notifications per window. */
  maxPerWindow: number;
}

interface ChannelRateConfig extends RateLimitConfig {
  /** Whether to auto-summarize when rate-limited. */
  summarizeOnLimit: boolean;
}

interface RateLimitResult {
  allowed: boolean;
  retryAfterMs?: number;
  reason?: string;
}

Gotchas:

• Rate limiting should apply before queueing, not after. A rate-limited notification should never enter the priority queue.
• Different channels need different limits. A system metrics channel updating every second is normal; a social notification channel sending once per second is abuse.
• Emergency/critical notifications must bypass rate limits, or you’ll suppress fire alarms.
• FCM limits collapsible messages to 4 per collapse key per device. This is a good design constraint — if you have more than 4 types of collapsible update, your channel taxonomy is wrong.

Pattern 3: Time-Sharing Rotation

When multiple notifications have the same priority and all deserve display time, rotate between them. This is how smartwatch complications work — each complication gets a slot on the face, and the watch rotates through them when the user taps.

When to use it: When the display is idle (no urgent content) and multiple ambient sources want visibility.

/**
 * Time-sharing rotation for ambient content.
 *
 * When the display has no urgent notifications, it rotates
 * through ambient content sources on a configurable interval.
 *
 * Inspired by:
 * - Apple Watch complications: each gets a fixed position,
 *   data rotates on interaction
 * - Google Nest Hub: ambient mode cycles through photos,
 *   weather, calendar
 * - Car instrument clusters: info display cycles between
 *   odometer, range, average MPG
 * - RSVP reading: words rotate at a fixed interval
 */
class TimeShareRotation {
  private sources: RotationSource[] = [];
  private currentIndex: number = 0;
  private timer: ReturnType<typeof setInterval> | null = null;
  private paused: boolean = false;
  private displayCallback: (content: NotificationContent | null) => void;

  constructor(
    private intervalMs: number,
    onContentChange: (content: NotificationContent | null) => void
  ) {
    this.displayCallback = onContentChange;
  }

  /**
   * Register a content source for rotation.
   * The source provides a function that returns current content.
   */
  addSource(source: RotationSource): void {
    this.sources.push(source);
    if (this.sources.length === 1 && !this.paused) {
      this.start();
    }
  }

  removeSource(sourceId: string): void {
    this.sources = this.sources.filter((s) => s.id !== sourceId);
    if (this.currentIndex >= this.sources.length) {
      this.currentIndex = 0;
    }
    if (this.sources.length === 0) {
      this.stop();
    }
  }

  /**
   * Start rotation. Called when the priority queue is empty
   * and the display enters ambient mode.
   */
  start(): void {
    if (this.timer) return;
    this.paused = false;

    // Show first source immediately
    this.showCurrent();

    this.timer = setInterval(() => {
      this.advance();
    }, this.intervalMs);
  }

  /**
   * Pause rotation. Called when a priority notification
   * preempts the rotation.
   */
  pause(): void {
    this.paused = true;
    if (this.timer) {
      clearInterval(this.timer);
      this.timer = null;
    }
  }

  /**
   * Resume rotation from where it left off.
   */
  resume(): void {
    if (!this.paused) return;
    this.paused = false;
    this.start();
  }

  private advance(): void {
    if (this.sources.length === 0) return;

    // Find the next source with content
    let attempts = 0;
    do {
      this.currentIndex = (this.currentIndex + 1) % this.sources.length;
      attempts++;
    } while (
      !this.sources[this.currentIndex].hasContent() &&
      attempts < this.sources.length
    );

    this.showCurrent();
  }

  private showCurrent(): void {
    if (this.sources.length === 0) {
      this.displayCallback(null);
      return;
    }

    const source = this.sources[this.currentIndex];
    const content = source.getContent();
    this.displayCallback(content);
  }

  /** Update rotation interval dynamically. */
  setInterval(ms: number): void {
    this.intervalMs = ms;
    if (this.timer) {
      this.stop();
      this.start();
    }
  }
}

interface RotationSource {
  /** Unique identifier for this source. */
  id: string;

  /** Human-readable name. */
  name: string;

  /** Weight for weighted rotation (higher = more frequent). */
  weight: number;

  /** Whether this source currently has content to display. */
  hasContent(): boolean;

  /** Get the current content to display. */
  getContent(): NotificationContent;
}

Gotchas:

• Rotation speed matters enormously. Too fast (< 3 seconds) and the display is distracting. Too slow (> 30 seconds) and sources feel ignored. 5-10 seconds is the sweet spot for ambient content.
• When a priority notification preempts rotation, you need to decide: resume from where you left off, or restart from the beginning? Resume is less jarring.
• Weighted rotation is better than round-robin. A weather source that updates hourly doesn’t need the same display time as a system monitor updating every second.

Pattern 4: Channel Policy Engine

This is where it all comes together. A policy engine that evaluates incoming notifications against channels, focus modes, rate limits, and the current display state to make a decision: display, queue, suppress, or summarize.

When to use it: This is the brain of the notification system. Every notification passes through it.

/**
 * The policy engine evaluates every incoming notification and decides
 * what to do with it.
 *
 * Decision flow:
 * 1. Validate the notification (required fields, known channel)
 * 2. Check rate limits
 * 3. Check focus mode filters
 * 4. Apply channel policies (collapse, summarize)
 * 5. Calculate effective priority
 * 6. Submit to the priority queue or rotation
 *
 * This mirrors the layered policy approach used by:
 * - iOS: interruption level → Focus mode → notification summary
 * - Grafana: alert rules → notification policies → silences → mute timings
 * - PagerDuty: event rules → services → escalation policies → user notification rules
 */
class PolicyEngine {
  private channels: Map<string, NotificationChannel> = new Map();
  private focusModes: Map<string, FocusMode> = new Map();
  private rateLimiter: NotificationRateLimiter;
  private queue: NotificationPriorityQueue;
  private rotation: TimeShareRotation;
  private history: NotificationHistoryLog;
  private suppressionRules: SuppressionRule[] = [];

  constructor(config: PolicyEngineConfig) {
    this.rateLimiter = new NotificationRateLimiter(config.defaultRateLimit);
    this.queue = new NotificationPriorityQueue((entry) => {
      if (entry) {
        // Priority notification: pause rotation and show it
        this.rotation.pause();
        this.onDisplay(entry);
      } else {
        // Queue empty: resume rotation
        this.rotation.resume();
      }
    });
    this.rotation = new TimeShareRotation(
      config.rotationIntervalMs,
      (content) => {
        this.onRotationDisplay(content);
      }
    );
    this.history = new NotificationHistoryLog(config.historySize);
  }

  /**
   * Register a notification channel.
   */
  registerChannel(channel: NotificationChannel): void {
    this.channels.set(channel.id, channel);
    this.rateLimiter.configureChannel(channel.id, {
      maxBurst: channel.rateLimit,
      refillRate: 1,
      refillIntervalMs: 60_000 / channel.rateLimit,
      windowMs: 60_000,
      maxPerWindow: channel.rateLimit,
      summarizeOnLimit: channel.collapseStrategy === "summarize",
    });
  }

  /**
   * Set a focus mode. Only one can be active at a time.
   */
  activateFocusMode(modeId: string): void {
    // Deactivate all others
    for (const mode of this.focusModes.values()) {
      mode.active = false;
    }
    const mode = this.focusModes.get(modeId);
    if (mode) {
      mode.active = true;
    }
  }

  /**
   * Process an incoming notification.
   * Returns the decision made by the policy engine.
   */
  process(notification: Notification): PolicyDecision {
    // Step 1: Validate
    const channel = this.channels.get(notification.channel);
    if (!channel) {
      return {
        action: "reject",
        reason: `Unknown channel: ${notification.channel}`,
      };
    }

    // Apply channel defaults
    if (notification.level === undefined) {
      notification.level = channel.userOverride ?? channel.defaultLevel;
    }

    // Step 2: Check suppression rules
    for (const rule of this.suppressionRules) {
      if (rule.matches(notification)) {
        this.history.log(notification, "suppressed", rule.reason);
        return {
          action: "suppress",
          reason: rule.reason,
        };
      }
    }

    // Step 3: Check if channel is muted
    if (
      channel.muted &&
      notification.level! < InterruptionLevel.CRITICAL
    ) {
      this.history.log(notification, "muted", "Channel is muted");
      return {
        action: "suppress",
        reason: `Channel ${channel.id} is muted`,
      };
    }

    // Step 4: Check focus mode
    const activeFocus = this.getActiveFocusMode();
    if (activeFocus) {
      const allowed = this.checkFocusMode(activeFocus, notification);
      if (!allowed) {
        this.history.log(
          notification,
          "filtered",
          `Blocked by focus mode: ${activeFocus.name}`
        );

        // Still log for summary display if configured
        if (activeFocus.fallback === "summary") {
          return {
            action: "defer",
            reason: `Deferred by focus mode: ${activeFocus.name}`,
          };
        }

        return {
          action: "suppress",
          reason: `Blocked by focus mode: ${activeFocus.name}`,
        };
      }
    }

    // Step 5: Check rate limits
    const rateResult = this.rateLimiter.check(
      notification.source,
      notification.channel,
      notification.level!
    );
    if (!rateResult.allowed) {
      this.history.log(
        notification,
        "rate-limited",
        rateResult.reason!
      );
      return {
        action: "rate-limited",
        reason: rateResult.reason!,
        retryAfterMs: rateResult.retryAfterMs,
      };
    }

    // Step 6: Apply collapse strategy
    if (channel.collapseStrategy === "replace" && notification.replacesId) {
      // The queue handles replacement via replacesId
    } else if (channel.collapseStrategy === "summarize") {
      // Check if we should summarize instead of showing individually
      const pendingCount = this.countPendingForChannel(
        notification.channel
      );
      if (pendingCount >= 3) {
        return this.summarize(notification);
      }
    }

    // Step 7: Set TTL from channel default if not specified
    if (notification.expiresAt === null && channel.defaultTTL !== null) {
      notification.expiresAt = Date.now() + channel.defaultTTL;
    }

    // Step 8: Submit to priority queue
    const position = this.queue.submit(notification);
    this.history.log(notification, "queued", `Position: ${position}`);

    return {
      action: "queued",
      position,
    };
  }

  private checkFocusMode(
    mode: FocusMode,
    notification: Notification
  ): boolean {
    // Critical always breaks through (iOS behavior)
    if (notification.level! >= InterruptionLevel.CRITICAL) {
      return true;
    }

    // Check minimum level
    if (notification.level! < mode.minimumLevel) {
      return false;
    }

    // Check allowed channels
    if (mode.allowedChannels.includes(notification.channel)) {
      return true;
    }

    // Check allowed sources
    if (mode.allowedSources.includes(notification.source)) {
      return true;
    }

    return false;
  }

  private getActiveFocusMode(): FocusMode | null {
    for (const mode of this.focusModes.values()) {
      if (mode.active) return mode;
    }

    // Check scheduled modes
    const now = new Date();
    for (const mode of this.focusModes.values()) {
      if (mode.schedule && this.isScheduleActive(mode.schedule, now)) {
        mode.active = true;
        return mode;
      }
    }

    return null;
  }

  private isScheduleActive(
    schedule: FocusModeSchedule,
    now: Date
  ): boolean {
    const day = now.getDay();
    if (!schedule.days.includes(day)) return false;

    const timeStr = now.toLocaleTimeString("en-US", {
      hour12: false,
      hour: "2-digit",
      minute: "2-digit",
      timeZone: schedule.timezone,
    });

    return timeStr >= schedule.startTime && timeStr <= schedule.endTime;
  }

  private countPendingForChannel(channelId: string): number {
    return this.queue
      .getState()
      .queued.filter(
        (e) => e.notification.channel === channelId
      ).length;
  }

  private summarize(notification: Notification): PolicyDecision {
    // Aggregate pending notifications for this channel into a summary
    const pending = this.queue
      .getState()
      .queued.filter(
        (e) => e.notification.channel === notification.channel
      );

    const summaryContent: NotificationContent = {
      summary: `${pending.length + 1} ${notification.channel} notifications`,
      body: pending
        .map((e) => e.notification.content.summary)
        .concat(notification.content.summary)
        .join("\n"),
      icon: "stack",
    };

    // Replace all pending with a single summary
    for (const entry of pending) {
      this.queue.dismiss(entry.notification.id);
    }

    const summaryNotification: Notification = {
      ...notification,
      id: `summary:${notification.channel}:${Date.now()}`,
      content: summaryContent,
      relevanceScore: 0.5,
    };

    this.queue.submit(summaryNotification);

    return {
      action: "summarized",
      reason: `Aggregated with ${pending.length} pending notifications`,
    };
  }

  private onDisplay(entry: QueueEntry): void {
    // Hook for external display rendering
  }

  private onRotationDisplay(content: NotificationContent | null): void {
    // Hook for ambient rotation rendering
  }
}

interface PolicyDecision {
  action:
    | "queued"
    | "reject"
    | "suppress"
    | "rate-limited"
    | "defer"
    | "summarized";
  reason?: string;
  position?: number;
  retryAfterMs?: number;
}

interface PolicyEngineConfig {
  defaultRateLimit: RateLimitConfig;
  rotationIntervalMs: number;
  historySize: number;
}

interface SuppressionRule {
  reason: string;
  matches(notification: Notification): boolean;
}

Gotchas:

• The order of policy evaluation matters. Rate limiting should come before focus mode checks — you don’t want a rate-limited but urgent notification to be counted against the rate limit and then also blocked by focus mode.
• Summarization changes the notification identity. The original notifications are gone; only the summary exists. Make sure the history log captures the originals.
• Focus mode transitions need careful handling. When a focus mode deactivates, should deferred notifications flood the display? No — they should be shown as a summary.

Pattern 5: RSVP Interruption Protocol

Rapid Serial Visual Presentation (RSVP) displays words one at a time at high speed. This is a special case because the display is “occupied” — showing content that the user is actively reading. Interrupting RSVP is like interrupting someone mid-sentence.

When to use it: When the HUD has a speed-reading mode that cycles through text word-by-word.

/**
 * RSVP-aware notification delivery.
 *
 * When the display is in RSVP mode (showing words at 300+ WPM),
 * interruptions must be handled carefully:
 *
 * - SILENT/AMBIENT: queue silently, show after RSVP completes
 * - STANDARD: queue, show subtle indicator (dot color change)
 * - ELEVATED: pause RSVP, show notification, resume RSVP
 * - URGENT: immediately stop RSVP, show notification
 * - CRITICAL: immediately stop RSVP, show notification, cannot dismiss
 *
 * This mirrors how car dashboards handle navigation + calls:
 * - Music info: hidden during turn-by-turn
 * - Phone call: pauses navigation, shows caller
 * - Collision warning: overrides everything, cannot be dismissed
 */
class RSVPInterruptionHandler {
  private rsvpState: RSVPState | null = null;
  private pendingDuringRSVP: Notification[] = [];

  constructor(
    private policyEngine: PolicyEngine,
    private displayController: DisplayController
  ) {}

  /**
   * Called when RSVP mode starts.
   */
  startRSVP(text: string, wpm: number): void {
    this.rsvpState = {
      text,
      words: text.split(/\s+/),
      currentWordIndex: 0,
      wpm,
      startedAt: Date.now(),
      pausedAt: null,
      intervalMs: 60_000 / wpm,
    };
    this.pendingDuringRSVP = [];
    this.displayController.setMode("rsvp");
    this.advanceRSVP();
  }

  /**
   * Handle a notification arriving during RSVP.
   */
  handleDuringRSVP(notification: Notification): RSVPInterruptAction {
    if (!this.rsvpState) {
      // Not in RSVP mode — process normally
      return { action: "normal" };
    }

    const level = notification.level ?? InterruptionLevel.STANDARD;

    switch (level) {
      case InterruptionLevel.SILENT:
      case InterruptionLevel.AMBIENT:
        // Queue silently — don't disturb the reader
        this.pendingDuringRSVP.push(notification);
        return {
          action: "queued-silent",
          resumeAfterRSVP: true,
        };

      case InterruptionLevel.STANDARD:
        // Queue but show subtle indicator
        this.pendingDuringRSVP.push(notification);
        this.displayController.showIndicator("pending", {
          count: this.pendingDuringRSVP.length,
        });
        return {
          action: "queued-indicated",
          resumeAfterRSVP: true,
        };

      case InterruptionLevel.ELEVATED:
        // Pause RSVP, show notification, then resume
        this.pauseRSVP();
        this.displayController.showNotification(notification);

        // Auto-resume after notification TTL or 5 seconds
        const resumeDelay = notification.expiresAt
          ? notification.expiresAt - Date.now()
          : 5_000;

        setTimeout(() => {
          this.resumeRSVP();
        }, resumeDelay);

        return {
          action: "pause-show-resume",
          resumeAfterMs: resumeDelay,
        };

      case InterruptionLevel.URGENT:
      case InterruptionLevel.CRITICAL:
        // Stop RSVP entirely
        this.stopRSVP();
        this.displayController.showNotification(notification);
        return {
          action: "stop-rsvp",
          rsvpCancelled: true,
        };

      default:
        return { action: "normal" };
    }
  }

  private pauseRSVP(): void {
    if (!this.rsvpState) return;
    this.rsvpState.pausedAt = Date.now();
    this.displayController.setMode("notification");
  }

  private resumeRSVP(): void {
    if (!this.rsvpState || !this.rsvpState.pausedAt) return;
    this.rsvpState.pausedAt = null;
    this.displayController.setMode("rsvp");
    this.advanceRSVP();
  }

  private stopRSVP(): void {
    this.rsvpState = null;

    // Process any notifications that accumulated during RSVP
    for (const pending of this.pendingDuringRSVP) {
      this.policyEngine.process(pending);
    }
    this.pendingDuringRSVP = [];
  }

  private advanceRSVP(): void {
    if (!this.rsvpState || this.rsvpState.pausedAt) return;

    const state = this.rsvpState;
    if (state.currentWordIndex >= state.words.length) {
      // RSVP complete
      this.stopRSVP();
      return;
    }

    const word = state.words[state.currentWordIndex];
    this.displayController.showWord(word, state.currentWordIndex, state.words.length);
    state.currentWordIndex++;

    setTimeout(() => {
      this.advanceRSVP();
    }, state.intervalMs);
  }
}

interface RSVPState {
  text: string;
  words: string[];
  currentWordIndex: number;
  wpm: number;
  startedAt: number;
  pausedAt: number | null;
  intervalMs: number;
}

interface RSVPInterruptAction {
  action:
    | "normal"
    | "queued-silent"
    | "queued-indicated"
    | "pause-show-resume"
    | "stop-rsvp";
  resumeAfterRSVP?: boolean;
  resumeAfterMs?: number;
  rsvpCancelled?: boolean;
}

interface DisplayController {
  setMode(mode: "rsvp" | "notification" | "ambient" | "idle"): void;
  showWord(word: string, index: number, total: number): void;
  showNotification(notification: Notification): void;
  showIndicator(
    type: string,
    data: Record<string, unknown>
  ): void;
}

Gotchas:

• Resuming RSVP after an interruption is disorienting. Consider backing up 2-3 words so the reader can re-find their place.
• RSVP at high WPM (500+) means even a 2-second pause for a notification breaks the reading flow completely. At those speeds, only URGENT and CRITICAL should interrupt.
• The pending notification indicator should be minimal — a dot color change, not text. Anything more disrupts RSVP.

Pattern 6: Escalation and Acknowledgment

Some notifications become more important over time. PagerDuty’s entire business model is built on escalation: if the first responder doesn’t acknowledge in N minutes, escalate to the next level. Pushover’s emergency priority retries every 30+ seconds until acknowledged.

When to use it: For notifications that require human awareness — not just display, but confirmation that the human saw it.

/**
 * Escalation engine for notifications that require acknowledgment.
 *
 * Implements PagerDuty-style escalation:
 * 1. Show notification at initial level
 * 2. If not acknowledged within timeout, escalate to next level
 * 3. Repeat until acknowledged or escalation chain exhausted
 * 4. If chain exhausted, mark as unacknowledged and log
 *
 * Also implements Pushover-style retry:
 * - Retry display every N seconds
 * - Expire after M seconds
 * - Cancel retries on acknowledgment
 *
 * Grafana uses similar concepts: group_wait, group_interval, repeat_interval.
 */
class EscalationEngine {
  private escalations: Map<string, EscalationState> = new Map();
  private policyEngine: PolicyEngine;

  constructor(policyEngine: PolicyEngine) {
    this.policyEngine = policyEngine;
  }

  /**
   * Submit a notification with an escalation policy.
   */
  submitWithEscalation(
    notification: Notification,
    policy: EscalationPolicy
  ): void {
    const state: EscalationState = {
      notification,
      policy,
      currentStep: 0,
      startedAt: Date.now(),
      acknowledged: false,
      retryCount: 0,
      timers: [],
    };

    this.escalations.set(notification.id, state);

    // Submit at initial level
    this.policyEngine.process(notification);

    // Set up escalation timer
    this.scheduleEscalation(state);

    // Set up retry timer if configured
    if (policy.retryIntervalMs) {
      this.scheduleRetry(state);
    }

    // Set up expiry timer
    if (policy.expireAfterMs) {
      const expiryTimer = setTimeout(() => {
        this.expire(notification.id);
      }, policy.expireAfterMs);
      state.timers.push(expiryTimer);
    }
  }

  /**
   * Acknowledge a notification, stopping escalation and retries.
   */
  acknowledge(notificationId: string): AcknowledgmentResult {
    const state = this.escalations.get(notificationId);
    if (!state) {
      return { success: false, reason: "Notification not found" };
    }

    state.acknowledged = true;

    // Clear all timers
    for (const timer of state.timers) {
      clearTimeout(timer);
    }
    state.timers = [];

    const elapsed = Date.now() - state.startedAt;

    return {
      success: true,
      acknowledgedAfterMs: elapsed,
      escalationLevel: state.currentStep,
      retryCount: state.retryCount,
    };
  }

  private scheduleEscalation(state: EscalationState): void {
    const step = state.policy.steps[state.currentStep];
    if (!step) return;

    const timer = setTimeout(() => {
      if (state.acknowledged) return;

      // Move to next escalation step
      state.currentStep++;
      const nextStep = state.policy.steps[state.currentStep];

      if (nextStep) {
        // Re-submit at higher level
        const escalated: Notification = {
          ...state.notification,
          level: nextStep.level,
          content: {
            ...state.notification.content,
            summary: `[ESCALATED] ${state.notification.content.summary}`,
          },
          replacesId: state.notification.id,
        };
        this.policyEngine.process(escalated);

        // Execute escalation action (e.g., send to additional channels)
        if (nextStep.action) {
          nextStep.action(state.notification);
        }

        // Schedule next escalation
        this.scheduleEscalation(state);
      } else {
        // Escalation chain exhausted
        this.onEscalationExhausted(state);
      }
    }, step.timeoutMs);

    state.timers.push(timer);
  }

  private scheduleRetry(state: EscalationState): void {
    if (!state.policy.retryIntervalMs) return;

    const timer = setTimeout(() => {
      if (state.acknowledged) return;

      state.retryCount++;

      // Re-display the notification
      const retry: Notification = {
        ...state.notification,
        id: `${state.notification.id}:retry:${state.retryCount}`,
        replacesId: state.notification.id,
        content: {
          ...state.notification.content,
          summary: `[${state.retryCount}x] ${state.notification.content.summary}`,
        },
      };
      this.policyEngine.process(retry);

      // Schedule next retry
      this.scheduleRetry(state);
    }, state.policy.retryIntervalMs);

    state.timers.push(timer);
  }

  private expire(notificationId: string): void {
    const state = this.escalations.get(notificationId);
    if (!state || state.acknowledged) return;

    // Clear all timers
    for (const timer of state.timers) {
      clearTimeout(timer);
    }

    this.escalations.delete(notificationId);
  }

  private onEscalationExhausted(state: EscalationState): void {
    // All escalation steps exhausted without acknowledgment
    // This is the "nobody is responding" case
    const finalNotification: Notification = {
      ...state.notification,
      level: InterruptionLevel.CRITICAL,
      content: {
        ...state.notification.content,
        summary: `[UNACK] ${state.notification.content.summary}`,
        severity: "red",
      },
      replacesId: state.notification.id,
    };
    this.policyEngine.process(finalNotification);
  }
}

interface EscalationPolicy {
  /** Ordered escalation steps. */
  steps: EscalationStep[];

  /** Retry interval in ms (Pushover-style). Min 30000. */
  retryIntervalMs?: number;

  /** Total time before escalation expires in ms. */
  expireAfterMs?: number;
}

interface EscalationStep {
  /** Interruption level at this step. */
  level: InterruptionLevel;

  /** Time to wait before escalating to next step (ms). */
  timeoutMs: number;

  /** Optional action to execute at this step. */
  action?: (notification: Notification) => void;
}

interface EscalationState {
  notification: Notification;
  policy: EscalationPolicy;
  currentStep: number;
  startedAt: number;
  acknowledged: boolean;
  retryCount: number;
  timers: ReturnType<typeof setTimeout>[];
}

interface AcknowledgmentResult {
  success: boolean;
  reason?: string;
  acknowledgedAfterMs?: number;
  escalationLevel?: number;
  retryCount?: number;
}

Example 1: Registering Channels for a HUD

const engine = new PolicyEngine({
  defaultRateLimit: {
    maxBurst: 5,
    refillRate: 1,
    refillIntervalMs: 10_000,
    windowMs: 60_000,
    maxPerWindow: 30,
  },
  rotationIntervalMs: 8_000,
  historySize: 500,
});

// AI agent status channel — replace old status with new
engine.registerChannel({
  id: "agent-status",
  name: "Agent Status",
  description: "Athena and Jane operational status",
  defaultLevel: InterruptionLevel.AMBIENT,
  muted: false,
  rateLimit: 12, // max 12/minute (one every 5 seconds)
  collapseStrategy: "replace",
  defaultTTL: 30_000, // 30 seconds
  style: "metric",
});

// System alerts — queue multiple, don't replace
engine.registerChannel({
  id: "system-alerts",
  name: "System Alerts",
  description: "CPU, memory, disk, network anomalies",
  defaultLevel: InterruptionLevel.ELEVATED,
  muted: false,
  rateLimit: 6,
  collapseStrategy: "summarize",
  defaultTTL: 60_000,
  style: "alert",
});

// User timers — high priority, replace on update
engine.registerChannel({
  id: "timers",
  name: "Timers & Reminders",
  description: "User-set timers, calendar reminders",
  defaultLevel: InterruptionLevel.URGENT,
  muted: false,
  rateLimit: 10,
  collapseStrategy: "replace",
  defaultTTL: null, // persist until dismissed
  style: "text",
});

// Weather — ambient, very low rate
engine.registerChannel({
  id: "weather",
  name: "Weather",
  description: "Current conditions and alerts",
  defaultLevel: InterruptionLevel.SILENT,
  muted: false,
  rateLimit: 2, // max 2/minute
  collapseStrategy: "replace",
  defaultTTL: 300_000, // 5 minutes
  style: "metric",
});

Example 2: Sending a Notification from an AI Agent

function agentStatusUpdate(
  agentName: string,
  status: string,
  severity: "green" | "yellow" | "red"
): Notification {
  const level =
    severity === "red"
      ? InterruptionLevel.URGENT
      : severity === "yellow"
        ? InterruptionLevel.STANDARD
        : InterruptionLevel.AMBIENT;

  return {
    id: `agent:${agentName}:${Date.now()}`,
    source: agentName,
    channel: "agent-status",
    replacesId: `agent:${agentName}:latest`,
    content: {
      summary: `${agentName}: ${status}`,
      severity,
      icon: agentName === "athena" ? "owl" : "sparkle",
      metric: severity === "yellow" || severity === "red"
        ? { label: agentName, value: status, trend: "down" }
        : undefined,
    },
    level,
    createdAt: Date.now(),
    expiresAt: Date.now() + 30_000,
    state: "pending",
    updateCount: 0,
    relevanceScore: severity === "red" ? 1.0 : severity === "yellow" ? 0.7 : 0.3,
  };
}

// Normal operation
engine.process(agentStatusUpdate("athena", "nominal", "green"));

// Something unusual
engine.process(agentStatusUpdate("athena", "traffic spike 3x", "yellow"));

// System down
engine.process(agentStatusUpdate("athena", "UNREACHABLE", "red"));

Example 3: Focus Mode for Deep Work

const deepWorkMode: FocusMode = {
  id: "deep-work",
  name: "Deep Work",
  active: false,
  // Only agent alerts and timers break through
  allowedChannels: ["timers"],
  // Only Athena (the system) can interrupt, not individual agents
  allowedSources: ["athena"],
  // Only URGENT and above can break through
  minimumLevel: InterruptionLevel.URGENT,
  schedule: {
    days: [1, 2, 3, 4, 5], // weekdays
    startTime: "09:00",
    endTime: "12:00",
    timezone: "America/Chicago",
  },
  fallback: "summary", // show count of suppressed notifications
};

// Manual activation
engine.activateFocusMode("deep-work");

Example 4: System Monitor as a Rotation Source

class CPUMonitorSource implements RotationSource {
  id = "cpu-monitor";
  name = "CPU Usage";
  weight = 1;
  private lastReading: number = 0;

  hasContent(): boolean {
    return true; // always has something to show
  }

  getContent(): NotificationContent {
    const usage = this.lastReading;
    const trend =
      usage > 80 ? "up" : usage < 20 ? "down" : ("flat" as const);

    return {
      summary: `CPU ${usage}%`,
      metric: {
        label: "CPU",
        value: `${usage}%`,
        trend,
      },
      severity: usage > 90 ? "red" : usage > 70 ? "yellow" : "green",
      icon: "cpu",
    };
  }

  update(usage: number): void {
    this.lastReading = usage;

    // If CPU is critically high, send as a priority notification
    // instead of waiting for rotation
    if (usage > 95) {
      // This would be submitted to the policy engine directly
    }
  }
}

class MemoryMonitorSource implements RotationSource {
  id = "memory-monitor";
  name = "Memory Usage";
  weight = 1;
  private usedGB: number = 0;
  private totalGB: number = 16;

  hasContent(): boolean {
    return true;
  }

  getContent(): NotificationContent {
    const pct = Math.round((this.usedGB / this.totalGB) * 100);
    return {
      summary: `RAM ${this.usedGB.toFixed(1)}/${this.totalGB}GB`,
      metric: {
        label: "RAM",
        value: `${pct}%`,
        trend: pct > 80 ? "up" : "flat",
      },
      severity: pct > 90 ? "red" : pct > 75 ? "yellow" : "green",
      icon: "memory",
    };
  }

  update(usedGB: number): void {
    this.usedGB = usedGB;
  }
}