Add modal_open and modal_close global events

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

app/RSpade/upstream_changes/CLAUDE.md

@@ -1,23 +1,42 @@
 # Upstream Changes Log
 
-## Purpose
+## Critical: Understanding the Purpose
 
-This directory contains migration guides for significant framework changes that affect existing RSX applications. When framework updates introduce breaking changes or new patterns that downstream projects should adopt, a detailed migration document is created here.
+**The `/rsx/` directory is the starter template that end users fork to create their applications.**
 
-These documents serve as technical references for updating existing applications to match the current framework patterns.
+When we make changes to files in `/rsx/`, users who previously forked the template do NOT automatically receive those changes. They must manually update their own copies.
+
+**Upstream changes documents tell users EXACTLY what to change in their forked `/rsx/` code to match the upstream template.**
+
+## Audience
+
+The audience is a developer who:
+- Forked the `/rsx/` starter template weeks or months ago
+- Has been building their own application on top of it
+- Wants to incorporate improvements we've made to the starter template
+- Needs to know the EXACT file paths and code changes to make
 
 ## When to Create a Document
 
-Create a migration guide when:
+Create an upstream changes document when:
-- Breaking changes affect existing application code
+- **ANY file in `/rsx/` is modified** that users would want to replicate
-- New patterns replace old patterns (and old code should be updated)
+- New features are added to `/rsx/` files
-- Configuration or directory structure changes
+- Bug fixes are made to `/rsx/` files
-- New required dependencies or bundle includes
+- Patterns or APIs change in `/rsx/` files
 
 Do NOT create documents for:
-- Internal framework refactoring that doesn't affect applications
+- Changes to `/system/` (framework core) - users get these automatically via submodule
-- New features that don't require changes to existing code
+- Internal refactoring that doesn't change functionality users would want
-- Bug fixes
+
+## What the Document Must Contain
+
+The document must provide everything needed to replicate the change:
+
+1. **AFFECTED FILES** - Exact file paths in `/rsx/` that were changed
+2. **WHAT CHANGED** - The specific code additions, modifications, or deletions
+3. **HOW TO APPLY** - Step-by-step instructions or copy-paste code blocks
+
+The goal is: a user can read the document and make the exact same changes to their fork without needing to diff files or guess what changed.
 
 ## File Naming Convention
 
@@ -26,55 +45,38 @@ Do NOT create documents for:
 ```
 
 Examples:
+- `modal_events_01_28.txt` - Modal event changes on January 28
 - `responsive_12_18.txt` - Responsive system changes on December 18
-- `bundle_api_03_15.txt` - Bundle API changes on March 15
-- `auth_session_07_22.txt` - Authentication/session changes on July 22
 
-Use lowercase with underscores. Date is MM_DD format (no year - files are naturally ordered by creation).
+Use lowercase with underscores. Date is MM_DD format.
 
 ## Document Structure
 
-Each migration guide should include:
-
 ```
-FEATURE NAME - MIGRATION GUIDE
+FEATURE NAME
 Date: YYYY-MM-DD
 
 SUMMARY
-    One paragraph describing what changed and why.
+    Brief description of what changed and why users might want it.
 
 AFFECTED FILES
-    List of file paths that need modification in downstream projects.
+    /rsx/path/to/file.js
+    /rsx/path/to/other_file.php
 
 CHANGES REQUIRED
 
-    1. First Change Category
+    File: /rsx/path/to/file.js
-       - What to do
+    -------------------------------------------------------------------------
-       - Code examples (before/after)
+    [Exact code to add/change, with enough context to locate where]
 
-    2. Second Change Category
+    File: /rsx/path/to/other_file.php
-       - What to do
+    -------------------------------------------------------------------------
-       - Code examples
+    [Exact code to add/change]
-
-CONFIGURATION
-    Any new configuration values, bundle includes, or settings.
 
 VERIFICATION
-    How to verify the migration was successful.
+    How to verify the change works after applying it.
-
-REFERENCE
-    Links to man pages or other documentation.
 ```
 
-## Level of Detail
+## Key Principle
 
-Migration guides should be:
+**Show the code.** Don't just describe what changed - show the exact lines to add or modify. Users should be able to copy-paste from the document into their files.
-- **Complete**: Every change needed to migrate, no assumptions
-- **Actionable**: Clear steps, not just descriptions
-- **Example-driven**: Show before/after code for each change type
-- **Self-contained**: Reader shouldn't need to reference other docs to complete migration
-
-Assume the reader:
-- Has an existing RSX application
-- Understands the framework basics
-- Does NOT know what changed or why

app/RSpade/upstream_changes/modal_events_01_28.txt

@@ -0,0 +1,75 @@
+Modal Open/Close Events
+Date: 2026-01-28
+
+SUMMARY
+    Added global Rsx events for modal open and close. This allows any part of
+    your application to react to modal lifecycle without direct modal access.
+    Useful for pausing background processes, analytics, keyboard shortcuts, etc.
+
+AFFECTED FILES
+    /rsx/lib/modal/modal.js
+    /rsx/lib/modal/CLAUDE.md (documentation only)
+
+CHANGES REQUIRED
+
+    File: /rsx/lib/modal/modal.js
+    -------------------------------------------------------------------------
+    In the _process_queue() method, add the modal_open trigger after setting
+    this._current. Find this code:
+
+        // Create modal instance
+        const modal_instance = await this._create_modal();
+        this._current = modal_instance;
+
+        // Determine if we should animate based on:
+
+    Change it to:
+
+        // Create modal instance
+        const modal_instance = await this._create_modal();
+        this._current = modal_instance;
+
+        // Trigger modal open event
+        Rsx.trigger('modal_open', { modal: modal_instance, options });
+
+        // Determine if we should animate based on:
+
+    -------------------------------------------------------------------------
+    In the same _process_queue() method, add the modal_close trigger before
+    resolving the promise. Find this code:
+
+        // Record close timestamp BEFORE resolving (ensures it's set before next modal can start)
+        this._last_close_timestamp = Date.now();
+
+        // Resolve the promise with the result
+        resolve(result);
+
+    Change it to:
+
+        // Record close timestamp BEFORE resolving (ensures it's set before next modal can start)
+        this._last_close_timestamp = Date.now();
+
+        // Trigger modal close event before resolving
+        Rsx.trigger('modal_close', { modal: modal_instance, result });
+
+        // Resolve the promise with the result
+        resolve(result);
+
+USAGE
+
+    // Listen for modal open
+    Rsx.on('modal_open', (data) => {
+        console.log('Modal opened:', data.modal, data.options);
+    });
+
+    // Listen for modal close
+    Rsx.on('modal_close', (data) => {
+        console.log('Modal closed:', data.modal, data.result);
+    });
+
+VERIFICATION
+
+    1. Open any modal in your application
+    2. Check browser console for 'modal_open' event (if you added a listener)
+    3. Close the modal
+    4. Check browser console for 'modal_close' event