rhales 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e468b139c203a063276ccd0f890b0b7439a7c4459a96f132ed1e53c01623b11
-  data.tar.gz: 786e0f95fa3d592b5451f7538d350f558f31545eb99973f5384bbde2fd474a99
+  metadata.gz: 7d4de8c7caddc2eb408dbb631654a055785456d23a13f28498d426a5f558464d
+  data.tar.gz: efe0545542afb04b016be65203ba8aede3e455b6075c6fe6d808764da4de6f93
 SHA512:
-  metadata.gz: fd02c37df3e02b5e423eeb7a1929ca2393a98ee0c6569724256846cd168ffa5476e4d94e18cbd9fc28149d0f50ff957423fbd1c165fe0e30f83d281e6075ab04
-  data.tar.gz: 8b9f7d88831a6e78ae811a56a4fe0c95e1c8962011ebbbcb7927e4cfb6dbcde798f66e4a2998fb89fcf30f356c7d2ca3134548971b3721331aacad6f90e501d5
+  metadata.gz: 7d9267703c89eff2da128aaecf692445e1b3533905b3c4218dd9feb5e855ecee037c52684b5d61bbb900a341d53bb14a4612bd27fc03d4f42733fa5c2621384d
+  data.tar.gz: b239a232e8d146bb3de0691151a152d85dcf42fa3117eb6e0aa4ac37745078eff4887e5ef969ed975e205c92c6b43e9cfa270a1cf981733384235ba70635d858

data/CLAUDE.md

@@ -29,7 +29,6 @@ Follow test-driven development when possible:
 2. Confirm tests fail appropriately
 3. Commit tests
 4. Implement code to pass tests WITHOUT modifying tests
-5. Ensure no global state dependencies (OT.conf references)
 6. Verify HTML escaping and security measures
 7. Commit implementation
 

data/README.md

@@ -11,7 +11,8 @@ It all started with a simple mustache template many years ago. The successor to
 ## Features
 
 - **Server-side template rendering** with Handlebars-style syntax
-- **Client-side data hydration** with secure JSON injection
+- **Enhanced hydration strategies** for optimal client-side performance
+- **API endpoint generation** for link-based hydration strategies
 - **Window collision detection** prevents silent data overwrites
 - **Explicit merge strategies** for controlled data sharing (shallow, deep, strict)
 - **Clear security boundaries** between server context and client data
@@ -19,6 +20,7 @@ It all started with a simple mustache template many years ago. The successor to
 - **Pluggable authentication adapters** for any auth system
 - **Security-first design** with XSS protection and automatic CSP generation
 - **Dependency injection** for testability and flexibility
+- **Resource hint optimization** with browser preload/prefetch support
 
 ## Installation
 
@@ -52,6 +54,13 @@ Rhales.configure do |config|
   config.features = { dark_mode: true }
   config.site_host = 'example.com'
 
+  # Enhanced Hydration Configuration
+  config.hydration.injection_strategy = :preload  # or :late, :early, :earliest, :prefetch, :modulepreload, :lazy
+  config.hydration.api_endpoint_path = '/api/hydration'
+  config.hydration.fallback_to_late = true
+  config.hydration.api_cache_enabled = true
+  config.hydration.cors_enabled = true
+
   # CSP configuration (enabled by default)
   config.csp_enabled = true           # Enable automatic CSP header generation
   config.auto_nonce = true            # Automatically generate nonces
@@ -574,10 +583,175 @@ Rhales uses a Handlebars-style template syntax:
 {{> navigation}}
 ```
 
-## Data Hydration
+## Enhanced Hydration Strategies
+
+Rhales provides multiple hydration strategies optimized for different performance requirements and use cases:
+
+### Traditional Strategies
+
+#### `:late` (Default - Backwards Compatible)
+Injects scripts before the closing `</body>` tag. Safe and reliable for all scenarios.
+
+```ruby
+config.hydration.injection_strategy = :late
+```
+
+#### `:early` (Mount Point Optimization)
+Injects scripts immediately before frontend mount points (`#app`, `#root`, etc.) for improved Time-to-Interactive.
+
+```ruby
+config.hydration.injection_strategy = :early
+config.hydration.mount_point_selectors = ['#app', '#root', '[data-mount]']
+config.hydration.fallback_to_late = true
+```
+
+#### `:earliest` (Head Section Injection)
+Injects scripts in the HTML head section for maximum performance, after meta tags and stylesheets.
+
+```ruby
+config.hydration.injection_strategy = :earliest
+config.hydration.fallback_to_late = true
+```
+
+### Link-Based Strategies (API Endpoints)
+
+These strategies generate separate API endpoints for hydration data, enabling better caching, parallel loading, and reduced HTML payload sizes.
+
+#### `:preload` (High Priority Loading)
+Generates `<link rel="preload">` tags with immediate script execution for critical data.
+
+```ruby
+config.hydration.injection_strategy = :preload
+config.hydration.api_endpoint_path = '/api/hydration'
+config.hydration.link_crossorigin = true
+```
+
+#### `:prefetch` (Future Page Optimization)
+Generates `<link rel="prefetch">` tags for data that will be needed on subsequent page loads.
+
+```ruby
+config.hydration.injection_strategy = :prefetch
+```
+
+#### `:modulepreload` (ES Module Support)
+Generates `<link rel="modulepreload">` tags with ES module imports for modern applications.
+
+```ruby
+config.hydration.injection_strategy = :modulepreload
+```
+
+#### `:lazy` (Intersection Observer)
+Loads data only when mount points become visible using Intersection Observer API.
+
+```ruby
+config.hydration.injection_strategy = :lazy
+config.hydration.lazy_mount_selector = '#app'
+```
+
+#### `:link` (Manual Loading)
+Generates basic link references with manual loading functions for custom hydration logic.
+
+```ruby
+config.hydration.injection_strategy = :link
+```
+
+### Strategy Performance Comparison
+
+| Strategy | Time-to-Interactive | Caching | Parallel Loading | Best Use Case |
+|----------|-------------------|---------|------------------|---------------|
+| `:late` | Standard | Basic | No | Legacy compatibility |
+| `:early` | Improved | Basic | No | SPA mount point optimization |
+| `:earliest` | Excellent | Basic | No | Critical path optimization |
+| `:preload` | Excellent | Advanced | Yes | High-priority data |
+| `:prefetch` | Standard | Advanced | Yes | Multi-page apps |
+| `:modulepreload` | Excellent | Advanced | Yes | Modern ES modules |
+| `:lazy` | Variable | Advanced | Yes | Below-fold content |
+| `:link` | Manual | Advanced | Yes | Custom implementations |
+
+### API Endpoint Setup
+
+For link-based strategies, you'll need to set up API endpoints in your application:
+
+```ruby
+# Rails example
+class HydrationController < ApplicationController
+  def show
+    template_name = params[:template]
+    endpoint = Rhales::HydrationEndpoint.new(rhales_config, current_context)
+
+    case request.format
+    when :json
+      result = endpoint.render_json(template_name)
+    when :js
+      result = endpoint.render_module(template_name)
+    else
+      result = endpoint.render_json(template_name)
+    end
+
+    render json: result[:content],
+           content_type: result[:content_type],
+           headers: result[:headers]
+  end
+end
+
+# routes.rb
+get '/api/hydration/:template', to: 'hydration#show'
+get '/api/hydration/:template.js', to: 'hydration#show', defaults: { format: :js }
+```
+
+#### Advanced Non-Rails Example
+
+For applications using custom frameworks or middleware, here's a complete controller implementation from a production Rack-based application:
+
+```ruby
+# Example from OneTime Secret (non-Rails application)
+module Manifold
+  module Controllers
+    class Data
+      include Controllers::Base
+
+      def rhales_hydration
+        publically do
+          template_name = params[:template]
+
+          # Build Rhales context from your app's current state
+          context = Rhales::Context.for_view(req, sess, cust, locale)
+          endpoint = Rhales::HydrationEndpoint.new(Rhales.configuration, context)
+
+          # Handle different formats
+          result = case req.env['HTTP_ACCEPT']
+                   when /application\/javascript/
+                     endpoint.render_module(template_name)
+                   else
+                     endpoint.render_json(template_name)
+                   end
+
+          # Set response content type and headers
+          res['Content-Type'] = result[:content_type]
+          result[:headers]&.each { |key, value| res[key] = value }
+
+          # Return the content
+          res.body = result[:content]
+        end
+      end
+    end
+  end
+end
+
+# Route configuration (framework-specific)
+# GET /api/hydration/:template -> data#rhales_hydration
+```
+
+**Key differences from Rails:**
+- **Framework-agnostic**: Uses `req`, `res`, `sess`, `cust`, `locale` from your framework
+- **Context creation**: Manually creates `Rhales::Context.for_view` with app objects
+- **Global configuration**: Uses `Rhales.configuration` instead of passing custom config
+- **Direct response handling**: Sets headers and body directly instead of using `render`
+- **Custom format detection**: Uses `req.env['HTTP_ACCEPT']` instead of `request.format`
 
-The `<data>` section creates client-side JavaScript:
+### Data Hydration Examples
 
+#### Traditional Inline Hydration
 ```erb
 <data window="myData">
 {
@@ -598,6 +772,131 @@ window.myData = JSON.parse(document.getElementById('rsfc-data-abc123').textConte
 </script>
 ```
 
+#### Link-Based Hydration (`:preload` strategy)
+```erb
+<data window="myData">
+{
+  "apiUrl": "{{api_base_url}}",
+  "user": {{user}},
+  "csrfToken": "{{csrf_token}}"
+}
+</data>
+```
+
+Generates:
+```html
+<link rel="preload" href="/api/hydration/my_template" as="fetch" crossorigin>
+<script nonce="nonce123" data-hydration-target="myData">
+fetch('/api/hydration/my_template')
+  .then(r => r.json())
+  .then(data => {
+    window.myData = data;
+    window.dispatchEvent(new CustomEvent('rhales:hydrated', {
+      detail: { target: 'myData', data: data }
+    }));
+  })
+  .catch(err => console.error('Rhales hydration error:', err));
+</script>
+```
+
+#### ES Module Hydration (`:modulepreload` strategy)
+```html
+<link rel="modulepreload" href="/api/hydration/my_template.js">
+<script type="module" nonce="nonce123" data-hydration-target="myData">
+import data from '/api/hydration/my_template.js';
+window.myData = data;
+window.dispatchEvent(new CustomEvent('rhales:hydrated', {
+  detail: { target: 'myData', data: data }
+}));
+</script>
+```
+
+### Migration Guide
+
+#### From Basic to Enhanced Hydration
+
+**Step 1**: Update your configuration to use enhanced strategies:
+
+```ruby
+# Before (implicit :late strategy)
+Rhales.configure do |config|
+  # Basic configuration
+end
+
+# After (explicit strategy selection)
+Rhales.configure do |config|
+  # Choose your strategy based on your needs
+  config.hydration.injection_strategy = :preload  # or :early, :earliest, etc.
+  config.hydration.fallback_to_late = true        # Safe fallback
+  config.hydration.api_endpoint_path = '/api/hydration'
+  config.hydration.api_cache_enabled = true
+end
+```
+
+**Step 2**: Set up API endpoints for link-based strategies (if using `:preload`, `:prefetch`, `:modulepreload`, `:lazy`, or `:link`):
+
+```ruby
+# Add to your routes
+get '/api/hydration/:template', to: 'hydration#show'
+get '/api/hydration/:template.js', to: 'hydration#show', defaults: { format: :js }
+
+# Create controller
+class HydrationController < ApplicationController
+  def show
+    template_name = params[:template]
+    endpoint = Rhales::HydrationEndpoint.new(rhales_config, current_context)
+    result = endpoint.render_json(template_name)
+
+    render json: result[:content],
+           content_type: result[:content_type],
+           headers: result[:headers]
+  end
+end
+```
+
+**Step 3**: Update your frontend code to listen for hydration events (optional):
+
+```javascript
+// Listen for hydration completion
+window.addEventListener('rhales:hydrated', (event) => {
+  console.log('Data loaded:', event.detail.target, event.detail.data);
+
+  // Initialize your app with the loaded data
+  if (event.detail.target === 'appData') {
+    initializeApp(event.detail.data);
+  }
+});
+```
+
+### Troubleshooting
+
+#### Common Issues
+
+**1. Link-based strategies not working**
+- Ensure API endpoints are set up correctly
+- Check that `config.hydration.api_endpoint_path` matches your routes
+- Verify CORS settings if loading from different domains
+
+**2. Mount points not detected with `:early` strategy**
+- Check that your HTML contains valid mount point selectors (`#app`, `#root`, etc.)
+- Verify `config.hydration.mount_point_selectors` includes your selectors
+- Enable fallback: `config.hydration.fallback_to_late = true`
+
+**3. CSP violations with link-based strategies**
+- Ensure nonces are properly configured: `config.auto_nonce = true`
+- Add API endpoint domains to CSP `connect-src` directive
+- Check that `crossorigin` attribute is properly configured
+
+**4. Performance not improving with advanced strategies**
+- Verify browser support for chosen strategy (modulepreload requires modern browsers)
+- Check network timing in DevTools to confirm parallel loading
+- Consider using `:prefetch` for subsequent page loads vs `:preload` for current page
+
+**5. Hydration events not firing**
+- Ensure JavaScript is not blocked by CSP
+- Check browser console for script errors
+- Verify API endpoints return valid JSON responses
+
 ### Window Collision Detection
 
 Rhales automatically detects when multiple templates try to use the same window attribute, preventing silent data overwrites:

data/lib/rhales/configuration.rb

@@ -1,6 +1,115 @@
 # lib/rhales/configuration.rb
 
 module Rhales
+  # Hydration-specific configuration settings
+  #
+  # Controls how hydration scripts are injected into HTML templates.
+  # Supports multiple injection strategies for different performance characteristics:
+  #
+  # ## Traditional Strategies
+  # - `:late` (default) - injects before </body> tag (safest, backwards compatible)
+  # - `:early` - injects before detected mount points for improved performance
+  # - `:earliest` - injects in HTML head section for maximum performance
+  #
+  # ## Link-Based Strategies (API endpoints)
+  # - `:link` - basic link reference to API endpoint
+  # - `:prefetch` - browser prefetch for future page loads
+  # - `:preload` - high priority preload for current page
+  # - `:modulepreload` - ES module preloading
+  # - `:lazy` - intersection observer-based lazy loading
+  class HydrationConfiguration
+    VALID_STRATEGIES = [:late, :early, :earliest, :link, :prefetch, :preload, :modulepreload, :lazy].freeze
+    LINK_BASED_STRATEGIES = [:link, :prefetch, :preload, :modulepreload, :lazy].freeze
+    DEFAULT_API_CACHE_TTL = 300  # 5 minutes
+
+    # Injection strategy - one of VALID_STRATEGIES
+    attr_accessor :injection_strategy
+
+    # Array of CSS selectors to detect frontend mount points
+    attr_accessor :mount_point_selectors
+
+    # Whether to fallback to late injection when no mount points detected
+    attr_accessor :fallback_to_late
+
+    # Whether to fallback to late injection when early injection is unsafe
+    attr_accessor :fallback_when_unsafe
+
+    # Disable early injection for specific templates (array of template names)
+    attr_accessor :disable_early_for_templates
+
+    # API endpoint configuration for link-based strategies
+    attr_accessor :api_endpoint_enabled, :api_endpoint_path
+
+    # Link tag configuration
+    attr_accessor :link_crossorigin
+
+    # Module export configuration for :modulepreload strategy
+    attr_accessor :module_export_enabled
+
+    # Lazy loading configuration
+    attr_accessor :lazy_mount_selector
+
+    # Data attribute reflection system
+    attr_accessor :reflection_enabled
+
+    # Caching configuration for API endpoints
+    attr_accessor :api_cache_enabled, :api_cache_ttl
+
+    # CORS configuration for API endpoints
+    attr_accessor :cors_enabled, :cors_origin
+
+    def initialize
+      # Traditional strategy settings
+      @injection_strategy = :late
+      @mount_point_selectors = ['#app', '#root', '[data-rsfc-mount]', '[data-mount]']
+      @fallback_to_late = true
+      @fallback_when_unsafe = true
+      @disable_early_for_templates = []
+
+      # API endpoint settings
+      @api_endpoint_enabled = false
+      @api_endpoint_path = '/api/hydration'
+
+      # Link tag settings
+      @link_crossorigin = true
+
+      # Module export settings
+      @module_export_enabled = false
+
+      # Lazy loading settings
+      @lazy_mount_selector = '#app'
+
+      # Reflection system settings
+      @reflection_enabled = true
+
+      # Caching settings
+      @api_cache_enabled = false
+      @api_cache_ttl = DEFAULT_API_CACHE_TTL
+
+      # CORS settings
+      @cors_enabled = false
+      @cors_origin = '*'
+    end
+
+    # Validate the injection strategy
+    def injection_strategy=(strategy)
+      unless VALID_STRATEGIES.include?(strategy)
+        raise ArgumentError, "Invalid injection strategy: #{strategy}. Valid options: #{VALID_STRATEGIES.join(', ')}"
+      end
+      @injection_strategy = strategy
+    end
+
+    # Check if current strategy is link-based
+    def link_based_strategy?
+      LINK_BASED_STRATEGIES.include?(@injection_strategy)
+    end
+
+    # Check if API endpoints should be enabled
+    def api_endpoints_required?
+      link_based_strategy? || @api_endpoint_enabled
+    end
+  end
+
   # Configuration management for Rhales library
   #
   # Provides a clean, testable alternative to global configuration access.
@@ -31,6 +140,9 @@ module Rhales
     # Performance settings
     attr_accessor :cache_parsed_templates, :cache_ttl
 
+    # Hydration settings
+    attr_accessor :hydration
+
     def initialize
       # Set sensible defaults
       @default_locale         = 'en'
@@ -47,6 +159,7 @@ module Rhales
       @site_ssl_enabled       = false
       @cache_parsed_templates = true
       @cache_ttl              = 3600 # 1 hour
+      @hydration              = HydrationConfiguration.new
     end
 
     # Build API base URL from site configuration
@@ -86,7 +199,7 @@ module Rhales
         'worker-src' => ["'self'"],
         'manifest-src' => ["'self'"],
         'prefetch-src' => ["'self'"],
-        'upgrade-insecure-requests' => []
+        'upgrade-insecure-requests' => [],
       }.freeze
     end
 

data/lib/rhales/context.rb

@@ -97,7 +97,6 @@ module Rhales
 
     private
 
-
       # Build consolidated app data (replaces runtime_data + computed_data)
       def build_app_data
         app = {}

data/lib/rhales/earliest_injection_detector.rb

@@ -0,0 +1,149 @@
+require 'strscan'
+require_relative 'safe_injection_validator'
+
+module Rhales
+  # Detects the earliest safe injection points in HTML head and body sections
+  # for optimal hydration script placement performance
+  #
+  # ## Injection Priority Order
+  #
+  # For `<head></head>` section:
+  # 1. After the last `<link>` tag
+  # 2. After the last `<meta>` tag
+  # 3. After the first `<script>` tag (assuming early scripts are intentional)
+  # 4. Before the `</head>` tag
+  #
+  # If no `<head>` but there is `<body>`:
+  # - Before the `<body>` tag
+  #
+  # All injection points are validated for safety using SafeInjectionValidator
+  # to prevent injection inside unsafe contexts (scripts, styles, comments).
+  class EarliestInjectionDetector
+    def detect(template_html)
+      scanner = StringScanner.new(template_html)
+      validator = SafeInjectionValidator.new(template_html)
+
+      # Try head section injection points first
+      head_injection_point = detect_head_injection_point(scanner, validator, template_html)
+      return head_injection_point if head_injection_point
+
+      # Fallback to body tag injection
+      body_injection_point = detect_body_injection_point(scanner, validator, template_html)
+      return body_injection_point if body_injection_point
+
+      # No suitable injection point found
+      nil
+    end
+
+    private
+
+    def detect_head_injection_point(scanner, validator, template_html)
+      # Find head section bounds
+      head_start, head_end = find_head_section(template_html)
+      return nil unless head_start && head_end
+
+      # Try injection points in priority order within head section
+      injection_candidates = [
+        find_after_last_link(template_html, head_start, head_end),
+        find_after_last_meta(template_html, head_start, head_end),
+        find_after_first_script(template_html, head_start, head_end),
+        head_end # Before </head>
+      ].compact
+
+      # Return first safe injection point
+      injection_candidates.each do |position|
+        safe_position = find_safe_injection_position(validator, position)
+        return safe_position if safe_position
+      end
+
+      nil
+    end
+
+    def detect_body_injection_point(scanner, validator, template_html)
+      scanner.pos = 0
+
+      # Find opening <body> tag
+      if scanner.scan_until(/<body\b[^>]*>/i)
+        body_start = scanner.pos - scanner.matched.length
+        safe_position = find_safe_injection_position(validator, body_start)
+        return safe_position if safe_position
+      end
+
+      nil
+    end
+
+    def find_head_section(template_html)
+      scanner = StringScanner.new(template_html)
+
+      # Find opening <head> tag
+      return nil unless scanner.scan_until(/<head\b[^>]*>/i)
+      head_start = scanner.pos
+
+      # Find closing </head> tag
+      return nil unless scanner.scan_until(/<\/head>/i)
+      head_end = scanner.pos - scanner.matched.length
+
+      [head_start, head_end]
+    end
+
+    def find_after_last_link(template_html, head_start, head_end)
+      head_content = template_html[head_start...head_end]
+      scanner = StringScanner.new(head_content)
+      last_link_end = nil
+
+      while scanner.scan_until(/<link\b[^>]*\/?>/i)
+        last_link_end = scanner.pos
+      end
+
+      last_link_end ? head_start + last_link_end : nil
+    end
+
+    def find_after_last_meta(template_html, head_start, head_end)
+      head_content = template_html[head_start...head_end]
+      scanner = StringScanner.new(head_content)
+      last_meta_end = nil
+
+      while scanner.scan_until(/<meta\b[^>]*\/?>/i)
+        last_meta_end = scanner.pos
+      end
+
+      last_meta_end ? head_start + last_meta_end : nil
+    end
+
+    def find_after_first_script(template_html, head_start, head_end)
+      head_content = template_html[head_start...head_end]
+      scanner = StringScanner.new(head_content)
+
+      # Find first script opening tag
+      if scanner.scan_until(/<script\b[^>]*>/i)
+        script_start = scanner.pos - scanner.matched.length
+
+        # Find corresponding closing tag
+        if scanner.scan_until(/<\/script>/i)
+          first_script_end = scanner.pos
+          return head_start + first_script_end
+        end
+      end
+
+      nil
+    end
+
+    def find_safe_injection_position(validator, preferred_position)
+      return nil unless preferred_position
+
+      # First check if the preferred position is safe
+      return preferred_position if validator.safe_injection_point?(preferred_position)
+
+      # Try to find a safe position before the preferred position
+      safe_before = validator.nearest_safe_point_before(preferred_position)
+      return safe_before if safe_before
+
+      # As a last resort, try after the preferred position
+      safe_after = validator.nearest_safe_point_after(preferred_position)
+      return safe_after if safe_after
+
+      # No safe position found
+      nil
+    end
+  end
+end

data/lib/rhales/errors/hydration_collision_error.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+# lib/rhales/errors/hydration_collision_error.rb
 
 module Rhales
   class HydrationCollisionError < Error