2026-03-03 22:40:18 +01:00
/**
* @fileoverview Five-layer notification system for session events and alerts.
*
* The NotificationManager class implements five notification layers:
* 1. In-app notification drawer (slide-out panel with grouped notifications)
2026-05-12 10:23:44 +02:00
* 2. Tab title flash (alternating "⚠️ (N) codeman:<host>" / "codeman:<host>" when tab is hidden; uses this.originalTitle so it tracks any per-host title)
2026-03-03 22:40:18 +01:00
* 3. Browser Notification API (desktop push with auto-close after 8s)
* 4. Web Push via service worker (OS-level notifications when tab is closed)
* 5. Audio alerts (Web Audio API beep, user-opt-in)
*
* Features:
2026-07-28 23:20:01 +03:00
* - Per-event-type preferences (enabled, browser, audio, push) with v1→v5 migration
2026-03-03 22:40:18 +01:00
* - Device-specific defaults (notifications disabled on mobile by default)
* - 5s notification grouping window to batch rapid-fire events
* - 100-notification cap with oldest eviction
* - Rate limiting: 3s between browser notifications
* - Visibility tracking (pauses title flash when tab becomes visible)
* - iOS Safari bfcache support via pageshow event
*
* @class NotificationManager
* @param {CodemanApp} app - Reference to the main app instance
*
* @dependency constants.js (STUCK_THRESHOLD_DEFAULT_MS, timing constants)
2026-07-28 23:20:01 +03:00
* @dependency mobile-handlers.js (MobileDetection stable handheld identity/device type)
2026-03-14 21:24:22 +01:00
* @loadorder 4 of 15 — loaded after voice-input.js, before keyboard-accessory.js
2026-03-03 22:40:18 +01:00
*/
2026-03-01 04:57:37 +01:00
// Codeman — Multi-layer notification system
// Loaded after mobile-handlers.js, before app.js
// Notification Manager - Multi-layer browser notification system
class NotificationManager {
constructor ( app ) {
this . app = app ;
this . notifications = [];
this . unreadCount = 0 ;
this . isTabVisible = ! document . hidden ;
this . isDrawerOpen = false ;
this . originalTitle = document . title ;
this . titleFlashInterval = null ;
this . titleFlashState = false ;
this . lastBrowserNotifTime = 0 ;
this . audioCtx = null ;
this . renderScheduled = false ;
// Debounce grouping: Map<key, {notification, timeout}>
this . groupingMap = new Map ();
// Load preferences
this . preferences = this . loadPreferences ();
// Visibility tracking
document . addEventListener ( 'visibilitychange' , () => {
this . isTabVisible = ! document . hidden ;
if ( this . isTabVisible ) {
this . onTabVisible ();
}
});
// iOS Safari: pageshow fires on back-forward cache restore (bfcache)
window . addEventListener ( 'pageshow' , ( e ) => {
if ( e . persisted ) {
this . isTabVisible = true ;
this . onTabVisible ();
}
});
}
2026-07-28 23:20:01 +03:00
_usesMobilePreferences () {
return (
MobileDetection . isHandheldDevice ? .() ??
MobileDetection . getDeviceType () === 'mobile'
);
}
getDefaultPreferences () {
2026-03-01 04:57:37 +01:00
const defaultEventTypes = {
permission_prompt : { enabled : true , browser : true , audio : true , push : false },
elicitation_dialog : { enabled : true , browser : true , audio : true , push : false },
idle_prompt : { enabled : true , browser : true , audio : false , push : false },
2026-07-28 23:20:01 +03:00
stop : { enabled : false , browser : false , audio : false , push : false },
2026-03-01 04:57:37 +01:00
session_error : { enabled : true , browser : true , audio : false , push : false },
respawn_cycle : { enabled : true , browser : false , audio : false , push : false },
token_milestone : { enabled : true , browser : false , audio : false , push : false },
ralph_complete : { enabled : true , browser : true , audio : true , push : false },
subagent_spawn : { enabled : false , browser : false , audio : false , push : false },
subagent_complete : { enabled : false , browser : false , audio : false , push : false },
};
// Device-specific defaults: mobile has notifications disabled by default
2026-07-28 23:20:01 +03:00
const isMobile = this . _usesMobilePreferences ();
return {
2026-03-01 04:57:37 +01:00
enabled : ! isMobile , // Disabled on mobile by default
browserNotifications : ! isMobile ,
audioAlerts : false ,
stuckThresholdMs : STUCK_THRESHOLD_DEFAULT_MS ,
// Legacy urgency muting (keep for backwards compat)
muteCritical : false ,
muteWarning : false ,
muteInfo : false ,
// Per-event-type preferences
eventTypes : defaultEventTypes ,
2026-07-28 23:20:01 +03:00
_version : 5 ,
2026-03-01 04:57:37 +01:00
};
2026-07-28 23:20:01 +03:00
}
/**
* Apply the complete v1→v5 migration to either local or server-hydrated
* preferences. Keeping one normalization path prevents fresh browsers from
* reviving retired drawer-only hook defaults.
*/
normalizePreferences ( rawPreferences ) {
const defaults = this . getDefaultPreferences ();
if (
! rawPreferences ||
typeof rawPreferences !== 'object' ||
Array . isArray ( rawPreferences )
) {
return defaults ;
}
const prefs = {
... rawPreferences ,
eventTypes :
rawPreferences . eventTypes &&
typeof rawPreferences . eventTypes === 'object' &&
! Array . isArray ( rawPreferences . eventTypes )
? Object . fromEntries (
Object . entries ( rawPreferences . eventTypes ). map (([ key , value ]) => [
key ,
value && typeof value === 'object' ? { ... value } : value ,
])
)
: undefined ,
};
const version = Number . isInteger ( prefs . _version ) ? prefs . _version : 0 ;
// Migrate: v1 had browserNotifications defaulting to false
if ( version < 2 ) {
prefs . browserNotifications = true ;
}
// Migrate: v2 -> v3 adds eventTypes
if ( version < 3 ) {
prefs . eventTypes = { ... defaults . eventTypes };
}
// Migrate: v3 -> v4 adds push field to all eventTypes
if ( version < 4 && prefs . eventTypes ) {
for ( const key of Object . keys ( prefs . eventTypes )) {
if ( prefs . eventTypes [ key ] && prefs . eventTypes [ key ]. push === undefined ) {
prefs . eventTypes [ key ]. push = false ;
}
}
}
// Migrate: v4 -> v5 removes the drawer-only Response Complete default.
// Preserve users who opted into any external delivery channel.
if ( version < 5 ) {
const stopPref = prefs . eventTypes ? . stop ;
if (
stopPref ? . enabled === true &&
! stopPref . browser &&
! stopPref . audio &&
! stopPref . push
) {
stopPref . enabled = false ;
}
}
return {
... defaults ,
... prefs ,
eventTypes : { ... defaults . eventTypes , ... prefs . eventTypes },
_version : 5 ,
};
}
loadPreferences () {
2026-03-01 04:57:37 +01:00
try {
const storageKey = this . getStorageKey ();
const saved = localStorage . getItem ( storageKey );
if ( saved ) {
2026-07-28 23:20:01 +03:00
const normalized = this . normalizePreferences ( JSON . parse ( saved ));
localStorage . setItem ( storageKey , JSON . stringify ( normalized ));
return normalized ;
2026-03-01 04:57:37 +01:00
}
} catch ( _e ) { /* ignore */ }
2026-07-28 23:20:01 +03:00
return this . getDefaultPreferences ();
2026-03-01 04:57:37 +01:00
}
// Get storage key for notification prefs (device-specific)
getStorageKey () {
2026-07-28 23:20:01 +03:00
return this . _usesMobilePreferences ()
? 'codeman-notification-prefs-mobile'
: 'codeman-notification-prefs' ;
2026-03-01 04:57:37 +01:00
}
savePreferences () {
localStorage . setItem ( this . getStorageKey (), JSON . stringify ( this . preferences ));
}
notify ({ urgency , category , sessionId , sessionName , title , message }) {
if ( ! this . preferences . enabled ) return ;
// Map notification categories to eventType preference keys
const categoryToEventType = {
'hook-permission' : 'permission_prompt' ,
'hook-elicitation' : 'elicitation_dialog' ,
'hook-idle' : 'idle_prompt' ,
'hook-stop' : 'stop' ,
'session-error' : 'session_error' ,
'session-crash' : 'session_error' ,
'session-stuck' : 'idle_prompt' ,
'respawn-blocked' : 'respawn_cycle' ,
'auto-accept' : 'respawn_cycle' ,
'auto-clear' : 'respawn_cycle' ,
'ralph-complete' : 'ralph_complete' ,
'circuit-breaker' : 'respawn_cycle' ,
'exit-gate' : 'ralph_complete' ,
'subagent-spawn' : 'subagent_spawn' ,
'subagent-complete' : 'subagent_complete' ,
2026-07-28 23:20:01 +03:00
// Team lifecycle hooks are agent activity, not session-idle/stop alerts.
// Reuse the existing opt-in agent categories instead of making them noisy.
'hook-teammate-idle' : 'subagent_spawn' ,
'hook-task-completed' : 'subagent_complete' ,
2026-03-01 04:57:37 +01:00
};
const eventTypeKey = categoryToEventType [ category ] || category ;
// Check per-event-type preferences first
const eventPref = this . preferences . eventTypes ? .[ eventTypeKey ];
let shouldBrowserNotify = false ;
let shouldAudioAlert = false ;
if ( eventPref ) {
// Event type found - use its specific preferences
if ( ! eventPref . enabled ) return ;
shouldBrowserNotify = eventPref . browser && this . preferences . browserNotifications ;
shouldAudioAlert = eventPref . audio && this . preferences . audioAlerts ;
} else {
// Fall back to urgency-based muting for unknown categories
if ( urgency === 'critical' && this . preferences . muteCritical ) return ;
if ( urgency === 'warning' && this . preferences . muteWarning ) return ;
if ( urgency === 'info' && this . preferences . muteInfo ) return ;
// Default browser/audio behavior based on urgency
shouldBrowserNotify = this . preferences . browserNotifications &&
( urgency === 'critical' || urgency === 'warning' || ! this . isTabVisible );
shouldAudioAlert = urgency === 'critical' && this . preferences . audioAlerts ;
}
// Grouping: same category+session within 5s updates count instead of new entry
const groupKey = ` ${ category } : ${ sessionId || 'global' } ` ;
const existing = this . groupingMap . get ( groupKey );
if ( existing ) {
existing . notification . count = ( existing . notification . count || 1 ) + 1 ;
existing . notification . message = message ;
existing . notification . timestamp = Date . now ();
clearTimeout ( existing . timeout );
existing . timeout = setTimeout (() => this . groupingMap . delete ( groupKey ), GROUPING_TIMEOUT_MS );
this . scheduleRender ();
return ;
}
const notification = {
id : Date . now () + '-' + Math . random (). toString ( 36 ). slice ( 2 , 7 ),
urgency ,
category ,
sessionId ,
sessionName ,
title ,
message ,
timestamp : Date . now (),
read : false ,
count : 1 ,
};
2026-03-01 17:26:31 +01:00
// Add to log (cap at NOTIFICATION_LIST_CAP)
2026-03-01 04:57:37 +01:00
this . notifications . unshift ( notification );
2026-03-01 17:26:31 +01:00
if ( this . notifications . length > NOTIFICATION_LIST_CAP ) this . notifications . pop ();
2026-03-01 04:57:37 +01:00
// Track for grouping
const timeout = setTimeout (() => this . groupingMap . delete ( groupKey ), GROUPING_TIMEOUT_MS );
this . groupingMap . set ( groupKey , { notification , timeout });
// Update unread
this . unreadCount ++ ;
this . updateBadge ();
this . scheduleRender ();
// Layer 2: Tab title (when tab unfocused)
if ( ! this . isTabVisible ) {
this . updateTabTitle ();
}
// Layer 3: Browser notification
if ( shouldBrowserNotify ) {
this . sendBrowserNotif ( title , message , category , sessionId );
}
// Layer 4: Audio alert
if ( shouldAudioAlert ) {
this . playAudioAlert ();
}
}
// Layer 1: Drawer rendering
scheduleRender () {
if ( this . renderScheduled ) return ;
this . renderScheduled = true ;
requestAnimationFrame (() => {
this . renderScheduled = false ;
this . renderDrawer ();
});
}
renderDrawer () {
const list = document . getElementById ( 'notifList' );
const empty = document . getElementById ( 'notifEmpty' );
if ( ! list || ! empty ) return ;
if ( this . notifications . length === 0 ) {
list . style . display = 'none' ;
empty . style . display = 'flex' ;
return ;
}
list . style . display = 'block' ;
empty . style . display = 'none' ;
list . innerHTML = this . notifications . map ( n => {
const urgencyClass = `notif-item- ${ n . urgency } ` ;
const readClass = n . read ? '' : ' unread' ;
const countLabel = n . count > 1 ? `<span class="notif-item-count">× ${ n . count } </span>` : '' ;
const sessionChip = n . sessionName ? `<span class="notif-item-session"> ${ escapeHtml ( n . sessionName ) } </span>` : '' ;
2026-06-19 15:26:42 +02:00
return `<div class="notif-item ${ urgencyClass }${ readClass } " data-notif-id=" ${ n . id } " data-session-id=" ${ n . sessionId || '' } " onclick="app.notificationManager.clickNotification( ${ escapeHtml ( JSON . stringify ( n . id )) } )">
2026-03-01 04:57:37 +01:00
<div class="notif-item-header">
<span class="notif-item-title"> ${ escapeHtml ( n . title ) }${ countLabel } </span>
<span class="notif-item-time"> ${ this . relativeTime ( n . timestamp ) } </span>
</div>
<div class="notif-item-message"> ${ escapeHtml ( n . message ) } </div>
${ sessionChip }
</div>` ;
}). join ( '' );
}
// Layer 2: Tab title with unread count
updateTabTitle () {
if ( this . unreadCount > 0 && ! this . isTabVisible ) {
if ( ! this . titleFlashInterval ) {
this . titleFlashInterval = setInterval (() => {
this . titleFlashState = ! this . titleFlashState ;
document . title = this . titleFlashState
2026-05-12 03:11:33 -04:00
? `\u26A0\uFE0F ( ${ this . unreadCount } ) ${ this . originalTitle } `
2026-03-01 04:57:37 +01:00
: this . originalTitle ;
}, TITLE_FLASH_INTERVAL_MS );
// Set immediately
2026-05-12 03:11:33 -04:00
document . title = `\u26A0\uFE0F ( ${ this . unreadCount } ) ${ this . originalTitle } ` ;
2026-03-01 04:57:37 +01:00
}
}
}
stopTitleFlash () {
if ( this . titleFlashInterval ) {
clearInterval ( this . titleFlashInterval );
this . titleFlashInterval = null ;
this . titleFlashState = false ;
document . title = this . originalTitle ;
}
}
// Layer 3: Web Notification API
sendBrowserNotif ( title , body , tag , sessionId ) {
if ( ! this . preferences . browserNotifications ) return ;
if ( typeof Notification === 'undefined' ) return ;
if ( Notification . permission === 'default' ) {
// Auto-request on first notification attempt
Notification . requestPermission (). then ( result => {
if ( result === 'granted' ) {
// Re-send this notification now that we have permission
this . sendBrowserNotif ( title , body , tag , sessionId );
}
});
return ;
}
if ( Notification . permission !== 'granted' ) return ;
2026-03-01 17:26:31 +01:00
// Rate limit
2026-03-01 04:57:37 +01:00
const now = Date . now ();
2026-03-01 17:26:31 +01:00
if ( now - this . lastBrowserNotifTime < BROWSER_NOTIF_RATE_LIMIT_MS ) return ;
2026-03-01 04:57:37 +01:00
this . lastBrowserNotifTime = now ;
2026-07-21 02:49:25 +08:00
const localizedTitle = window . codemanT ? .( title ) || title ;
const localizedBody = window . codemanT ? .( body ) || body ;
const notif = new Notification ( ` ${ this . originalTitle } : ${ localizedTitle } ` , {
body : localizedBody ,
2026-03-01 04:57:37 +01:00
tag , // Groups same-tag notifications
2026-09-04 12:10:20 -04:00
icon : ( window . CodemanBase ? . url || (( p ) => p ))( '/favicon.ico' ),
2026-03-01 04:57:37 +01:00
silent : true , // We handle audio ourselves
});
notif . onclick = () => {
window . focus ();
if ( sessionId && this . app . sessions . has ( sessionId )) {
this . app . selectSession ( sessionId );
}
notif . close ();
};
2026-03-01 17:26:31 +01:00
// Auto-close
setTimeout (() => notif . close (), AUTO_CLOSE_NOTIFICATION_MS );
2026-03-01 04:57:37 +01:00
}
async requestPermission () {
if ( typeof Notification === 'undefined' ) {
this . app . showToast ( 'Browser notifications not supported' , 'warning' );
return ;
}
const result = await Notification . requestPermission ();
const statusEl = document . getElementById ( 'notifPermissionStatus' );
if ( statusEl ) statusEl . textContent = `Status: ${ result } ` ;
if ( result === 'granted' ) {
this . preferences . browserNotifications = true ;
this . savePreferences ();
this . app . showToast ( 'Notifications enabled' , 'success' );
} else {
this . app . showToast ( `Permission ${ result } ` , 'warning' );
}
}
// Layer 4: Audio alert via Web Audio API
playAudioAlert () {
try {
if ( ! this . audioCtx ) {
this . audioCtx = new ( window . AudioContext || window . webkitAudioContext )();
}
if ( this . audioCtx . state === 'suspended' ) {
this . audioCtx . resume ();
}
const ctx = this . audioCtx ;
const oscillator = ctx . createOscillator ();
const gain = ctx . createGain ();
oscillator . connect ( gain );
gain . connect ( ctx . destination );
oscillator . type = 'sine' ;
oscillator . frequency . setValueAtTime ( 660 , ctx . currentTime );
gain . gain . setValueAtTime ( 0.15 , ctx . currentTime );
gain . gain . exponentialRampToValueAtTime ( 0.01 , ctx . currentTime + 0.15 );
oscillator . start ( ctx . currentTime );
oscillator . stop ( ctx . currentTime + 0.15 );
} catch ( _e ) { /* Audio not available */ }
}
// UI interactions
toggleDrawer () {
const drawer = document . getElementById ( 'notifDrawer' );
if ( ! drawer ) return ;
this . isDrawerOpen = ! this . isDrawerOpen ;
drawer . classList . toggle ( 'open' , this . isDrawerOpen );
if ( this . isDrawerOpen ) {
this . renderDrawer ();
}
}
clickNotification ( notifId ) {
const notif = this . notifications . find ( n => n . id === notifId );
if ( ! notif ) return ;
// Mark as read
if ( ! notif . read ) {
notif . read = true ;
this . unreadCount = Math . max ( 0 , this . unreadCount - 1 );
this . updateBadge ();
}
// Switch to session if available
if ( notif . sessionId && this . app . sessions . has ( notif . sessionId )) {
this . app . selectSession ( notif . sessionId );
this . toggleDrawer ();
}
this . scheduleRender ();
}
markAllRead () {
this . notifications . forEach ( n => { n . read = true ; });
this . unreadCount = 0 ;
this . updateBadge ();
this . stopTitleFlash ();
this . scheduleRender ();
}
clearAll () {
this . notifications = [];
this . unreadCount = 0 ;
this . updateBadge ();
this . stopTitleFlash ();
this . scheduleRender ();
}
updateBadge () {
const badge = document . getElementById ( 'notifBadge' );
if ( ! badge ) return ;
if ( this . unreadCount > 0 ) {
badge . style . display = 'flex' ;
badge . textContent = this . unreadCount > 99 ? '99+' : String ( this . unreadCount );
} else {
badge . style . display = 'none' ;
}
}
onTabVisible () {
this . stopTitleFlash ();
// If drawer is open, mark all as read
if ( this . isDrawerOpen ) {
this . markAllRead ();
}
// Re-fit terminal and send resize to PTY so this client's dimensions win.
// Fixes broken layout when switching between desktop and mobile on the same session.
2026-09-22 13:07:33 +05:30
// sendResize fits (floored) as its first synchronous step, so the bare
// fit that used to precede it was both redundant and a chance to leave
// xterm at the unfloored proposal (#464).
if ( this . app ? . activeSessionId ) {
2026-03-01 04:57:37 +01:00
this . app . sendResize ( this . app . activeSessionId );
}
}
// Utilities
relativeTime ( ts ) {
const diff = Math . floor (( Date . now () - ts ) / 1000 );
if ( diff < 60 ) return 'now' ;
if ( diff < 3600 ) return ` ${ Math . floor ( diff / 60 ) } m ago` ;
if ( diff < 86400 ) return ` ${ Math . floor ( diff / 3600 ) } h ago` ;
return ` ${ Math . floor ( diff / 86400 ) } d ago` ;
}
}