Add include_routes feature, documentation, and code quality improvements

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

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

app/RSpade/CodeQuality/Rules/Scss/NoAnimations_CodeQualityRule.php

@@ -57,6 +57,12 @@ class NoAnimations_CodeQualityRule extends CodeQualityRule_Abstract
             return;
         }
 
+        // Check for file-level exception comment
+        // Supports: /* rsx:disable SCSS-ANIM-01 */ or // rsx:disable SCSS-ANIM-01
+        if (preg_match('/(?:\/\*|\/\/)\s*rsx:disable\s+SCSS-ANIM-01/', $contents)) {
+            return;
+        }
+
         // Parse SCSS using our context parser
         // See App\RSpade\CodeQuality\Parsers\ScssContextParser for implementation
         // This parser provides accurate SCSS context analysis including proper

app/RSpade/man/blade_to_spa_conversion.txt

@@ -0,0 +1,136 @@
+BLADE_TO_SPA_CONVERSION(3)      RSX Framework Manual      BLADE_TO_SPA_CONVERSION(3)
+
+TEMPORARY DOCUMENT NOTICE
+    This man page was created on 2025-11-23 to assist with porting RSpade
+    projects from Blade templates to SPA actions.
+
+    This document will be removed when all consumers of the framework report
+    that their conversion is complete.
+
+NAME
+    blade_to_spa_conversion - Converting legacy Blade pages to SPA actions
+
+DESCRIPTION
+    This document preserves the process for converting legacy Blade pages to
+    SPA actions, for reference when dealing with old code or third-party
+    integrations.
+
+CONVERSION PROCESS
+
+    1. CREATE ACTION FILES
+
+        In the feature directory, create the JavaScript action and template:
+
+            touch Feature_Index_Action.js Feature_Index_Action.jqhtml
+
+    2. CREATE ACTION CLASS
+
+        Add the necessary decorators to define the SPA action:
+
+            @route('/path')
+            @layout('Frontend_Layout')
+            @spa('Frontend_Spa_Controller::index')
+            class Feature_Index_Action extends Spa_Action {
+                full_width = true;  // For DataGrid pages
+                async on_load() {
+                    this.data.items = await Feature_Controller.fetch_items();
+                }
+            }
+
+    3. CONVERT TEMPLATE SYNTAX
+
+        Variable Interpolation:
+            {{ $var }}      ->  <%= this.args.var %> or <%= this.data.var %>
+            {!! $html !!}   ->  <%!= this.data.html %>
+
+        Control Structures:
+            @if($cond) / @endif             ->  <% if (cond) { %> / <% } %>
+            @foreach($items as $item)       ->  <% for (let item of items) { %>
+            @endforeach                     ->  <% } %>
+            @for / @endfor                  ->  Standard JavaScript for loop
+            @while / @endwhile              ->  Standard JavaScript while loop
+
+        Comments:
+            {{-- comment --}}               ->  <%-- comment --%>
+
+        Includes:
+            @include('partial')             ->  Create a jqhtml component instead
+
+        Blade Directives:
+            @auth / @endauth                ->  Handle in action's on_load() method
+            @guest / @endguest              ->  Handle in action's on_load() method
+            @can / @endcan                  ->  Check permissions in controller
+
+    4. UPDATE CONTROLLER
+
+        Remove the server-side route method and replace with Ajax endpoints:
+
+            // Remove this:
+            #[Route('/feature')]
+            public static function index(Request $request, array $params = []) {
+                return view('feature.index', ['items' => Feature_Model::all()]);
+            }
+
+            // Add this instead:
+            #[Ajax_Endpoint]
+            public static function fetch_items(Request $request, array $params = []) {
+                return ['items' => Feature_Model::all()];
+            }
+
+    5. UPDATE ROUTE REFERENCES
+
+        Search for all references to the old controller method:
+
+            grep -r "Feature_Controller::method_name" rsx/app/
+
+        Update route generation:
+            Rsx::Route('Feature_Controller::method')  ->  Rsx::Route('Feature_Action')
+
+        Check these common locations:
+            - DataGrid templates (action buttons, row links)
+            - Navigation menus
+            - Redirect responses in controllers
+            - Breadcrumb configurations
+
+    6. ARCHIVE BLADE FILES
+
+        Move old Blade files to the archive directory:
+
+            mkdir -p /rsx/resource/archive/feature/
+            mv rsx/app/feature/*.blade.php /rsx/resource/archive/feature/
+
+    7. TEST THE CONVERSION
+
+        Verify the SPA action works correctly:
+
+            php artisan rsx:debug /path --console
+            php artisan rsx:debug /path --screenshot-path=screenshot.png
+
+COMMON CONVERSION PATTERNS
+
+    FORMS
+        Blade forms using @csrf and method="POST" should be converted to
+        <Rsx_Form> components that handle Ajax submission automatically.
+
+    AUTHENTICATION CHECKS
+        Blade's @auth directive should be handled by the SPA controller's
+        pre_dispatch() method or in the action's on_load() method.
+
+    ASSET URLS
+        {{ asset('path/to/file') }}  ->  Use bundle system or public directory
+        {{ mix('app.js') }}          ->  Handled automatically by RSX bundle
+
+    LARAVEL HELPERS
+        {{ route('name') }}          ->  Rsx.Route('Action_Name')
+        {{ url('/path') }}           ->  Rsx.Route('Action_Name')
+        {{ config('key') }}          ->  Pass from controller or Ajax endpoint
+
+NOTES
+    - This conversion process is complete for the RSX starter template
+    - New features should be built directly as SPA actions, not Blade views
+    - Blade knowledge is only needed for understanding legacy code
+
+SEE ALSO
+    spa(3), jqhtml(3), routing(3)
+
+RSX Framework                     2025-11-23            BLADE_TO_SPA_CONVERSION(3)

app/RSpade/man/bundle_api.txt

@@ -252,6 +252,45 @@ INCLUDE TYPES
         cached in Redis for performance. Generates tags with filemtime() for
         fresh cache-busting on each page render.
 
+ROUTE EXTRACTION (include_routes)
+    Bundles can extract route definitions from directories without bundling
+    their assets. This enables Rsx.Route() calls for controllers outside
+    the bundle's include paths.
+
+    SYNTAX
+        class Frontend_Bundle extends Rsx_Module_Bundle_Abstract
+        {
+            public static function define(): array
+            {
+                return [
+                    'include' => [
+                        __DIR__,
+                    ],
+                    'include_routes' => [
+                        'rsx/app/login',    // Extract routes only, no assets
+                        'rsx/app/admin',
+                    ],
+                ];
+            }
+        }
+
+    USE CASE
+        The frontend module needs to generate URLs to the login module
+        (e.g., logout link) but shouldn't bundle login's JavaScript/CSS.
+        Using include_routes extracts route patterns and makes them
+        available to Rsx.Route() without including the module's assets.
+
+    HOW IT WORKS
+        - Scans directories for PHP files extending Rsx_Controller_Abstract
+        - Extracts #[Route] attribute patterns from public static methods
+        - Generates Rsx._define_routes() call in compiled bundle
+        - Routes become available via Rsx.Route('Controller', 'method')
+
+    EXAMPLE
+        // In frontend JavaScript (with login routes extracted)
+        const logout_url = Rsx.Route('Login_Controller', 'logout');
+        // Returns: '/logout'
+
 PUBLIC ASSET INCLUDES
     Bundles can include static assets from any public/ directory with
     automatic cache-busting via filemtime().