Standards alignment: Document .js tools deviation, fix port 3030, enhance tool documentation

tools/screen-record/index.js

@@ -3,6 +3,12 @@
  * Records the user's screen using the Screen Capture API and MediaRecorder API
  * 
  * @module ScreenRecord
+ * @description Standalone utility for capturing screen recordings. Exposes window.recordScreen()
+ *   function for use in frontend code. No external dependencies beyond browser APIs.
+ * @usage Call window.recordScreen() after page load. User will see browser's native
+ *   screen selector dialog. Returns Promise resolving to recording controller.
+ * @dependencies None (browser APIs only: Screen Capture API, MediaRecorder, Web Audio API)
+ * @integration Used in index.html to provide screen recording UI controls
  */
 
 (function() {

tools/user-alert/README.md

@@ -0,0 +1,157 @@
+# User Alert System
+
+A standalone utility for monitoring shared notes and alerting the current user when notes are shared with them. Provides real-time notifications with desktop alerts and audio feedback.
+
+## Features
+
+- 🔔 Real-time desktop notifications when notes are shared
+- 🔊 Audio alert system with fallback bell tones
+- 📍 Prevents duplicate alerts for the same note
+- 🎯 PocketBase integration for realtime subscriptions
+- 🛡️ Graceful error handling for permission denials
+- ♿ Respects browser notification permissions
+
+## Installation
+
+Copy the `user-alert` folder to your project:
+
+```bash
+cp -r user-alert /path/to/project/tools/
+```
+
+## Usage
+
+After the tool is loaded, instantiate with your PocketBase instance:
+
+```javascript
+import { UserAlertSystem } from 'tools/user-alert/index.js';
+
+// Create alert system
+const alertSystem = new UserAlertSystem(
+  pocketbaseInstance,
+  userEmail,      // Current user's email
+  userName        // Current user's display name
+);
+
+// Start monitoring for shared notes
+await alertSystem.watchForSharedNotes();
+
+// Stop monitoring when needed
+alertSystem.stop();
+```
+
+## API
+
+### Constructor
+
+```javascript
+new UserAlertSystem(pocketbaseInstance, userEmail, userName)
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `pocketbaseInstance` | PocketBase | Initialized PocketBase client |
+| `userEmail` | string | Current user's email address |
+| `userName` | string | Current user's display name |
+
+### Methods
+
+#### `watchForSharedNotes()`
+
+Starts monitoring the notes collection for changes. Sets up realtime subscription that watches for notes where `sharedWith` includes the current user's email.
+
+```javascript
+await alertSystem.watchForSharedNotes();
+```
+
+#### `stop()`
+
+Unsubscribes from collection changes and stops monitoring.
+
+```javascript
+alertSystem.stop();
+```
+
+#### `playNotificationSound()`
+
+Plays a double-bell audio alert. Called automatically on alert, but can be triggered manually.
+
+```javascript
+await alertSystem.playNotificationSound();
+```
+
+## Integration
+
+This tool is integrated into Prism Notes via `index.html`. Include it in your HTML:
+
+```html
+<script type="module">
+  import { UserAlertSystem } from 'tools/user-alert/index.js';
+  
+  // Initialize after PocketBase and user auth is ready
+  const alertSystem = new UserAlertSystem(pb, userEmail, userName);
+  await alertSystem.watchForSharedNotes();
+</script>
+```
+
+## PocketBase Collection Requirements
+
+Your notes collection must have:
+- `sharedWith` field (array of email addresses)
+- `title`, `content` fields for display
+
+Example schema:
+```
+notes {
+  id: string (primary)
+  title: string
+  content: string
+  createdBy: string
+  sharedWith: array (of email strings)
+  createdAt: date
+}
+```
+
+## Browser Compatibility
+
+Requires:
+- Web Audio API for notification sounds
+- Notifications API for desktop alerts
+- ES6 modules for import/export
+- PocketBase realtime subscriptions
+
+Tested on:
+- Chrome 90+
+- Edge 90+
+- Firefox 88+
+
+## Permissions
+
+The system requires user permission for:
+- **Notifications**: Desktop notification display
+- **Audio**: Playing notification sounds (may be blocked by autoplay policy until user gesture)
+
+Users will be prompted by the browser to grant these permissions.
+
+## Dependencies
+
+- `pocketbase` (passed in constructor) — Realtime subscription system
+- Browser APIs: Notifications API, Web Audio API, DOM
+
+## Notes
+
+- Notifications are persistent once dismissed; consider adding notification center
+- Audio alerts may fail silently if browser blocks autoplay; notifications still work
+- Prevent duplicate alerts by tracking `alertedNotes` Set internally
+- Performance: Realtime subscription uses websocket; consider unsubscribing when user leaves page
+
+## Troubleshooting
+
+### "Permission denied" error
+User denied notification permission. System will continue working but won't show desktop alerts.
+
+### No audio on notification
+Browser autoplay policy may block audio until user gesture. Desktop notification still appears.
+
+### Alerts duplicating
+Check that PocketBase realtime updates aren't sending multiple change events. Duplicate tracking should prevent this, but verify collection triggers.

tools/user-alert/index.js

@@ -1,6 +1,18 @@
 /**
  * User Alert System
  * Monitors shared notes and alerts when someone shares a note with the current user
+ * 
+ * @module UserAlertSystem
+ * @description Standalone utility for monitoring PocketBase note collection changes.
+ *   Watches for notes shared with current user and triggers desktop notifications and
+ *   audio alerts. Exports UserAlertSystem class for instantiation with PocketBase instance.
+ * @usage Instantiate with PocketBase instance: new UserAlertSystem(pb, userEmail, userName).
+ *   Call watchForSharedNotes() to start monitoring.
+ * @dependencies PocketBase instance (passed in constructor). Browser APIs: Notifications,
+ *   Web Audio API, DOM manipulation.
+ * @integration Used in index.html to provide real-time alert functionality for shared notes
+ * @gotchas Requires user permission for desktop notifications. Audio context may be blocked
+ *   on some browsers until user gesture. Track alertedNotes Set to prevent duplicate alerts.
  */
 
 export class UserAlertSystem {