scarpe 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c83fb76fc149cffa58c679978dc3647689acb5b418d7e65a931bddfb1687b250
-  data.tar.gz: 2b73dae2f9f5be78d6b5637d605b089c3031b14aff91acc1eced51f021283f5a
+  metadata.gz: 63b4c563ff3a88126429d53ed2be981c0cf91f0469622ae46663102459bd77f7
+  data.tar.gz: 90201e43c50859ebfe9468228fc7380245c9c18f4faba21ffb49333dc4aa7a61
 SHA512:
-  metadata.gz: 6da8066857ec4241252fcca4bbe01a60c369260b618a65f44384666a4ed67311ee3bd065ab68bed79f7084e3f8c5ba7c8db3244c3cbcf9e166d1ad5130ccb43d
-  data.tar.gz: b8ba6762940cc53078e1461024f26b762acd302a99cb6fccd965b4c4018ac1452ad85821c78c8ab59b28db572ac899781d1e84bacd77bce602a9edeb0fe84a85
+  metadata.gz: 82d1332c1f875dba16af4891b9da1923e334f3b95f78faaca604783cfe907b05b9abf8bded7c4212d5e27546bbb4e4ee18ba3458ceeb8612a2f9b661bcf0a323
+  data.tar.gz: cd7814ee2024f9f69a0e21281e097e2aa4aef4805f43b271c36913cca47c32d58fdf2ac4272fce305f26c60a8753abfd9f4251dc837f20c6864b96a2bbafb76c

data/.cursor/rules/commit-style-preferences.mdc

@@ -0,0 +1,72 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+# Commit Style Preferences
+
+<rule>
+name: commit_style_preferences
+description: Guidelines for writing commit messages
+filters:
+  - type: event
+    pattern: "pre_commit"
+
+actions:
+  - type: suggest
+    message: |
+      # Format Requirements
+
+      1. First line (50 chars ideal):
+         - Clear, direct statement of WHAT changed
+         - Start with verb (Add, Fix, Update, etc.)
+
+      2. Empty line after header
+
+      3. Body must include:
+         - WHY the change was needed
+         - HOW it addresses the problem
+         - Technical implications
+         - Impact on stability/maintenance
+
+      4. For API changes:
+         - Explicitly state if using private/internal APIs
+         - Note any technical debt implications
+         - Include upstream context for dependency changes
+
+examples:
+  - description: "Standard feature change"
+    input: |
+      Add request validation to UserWidget
+
+      Prevents invalid requests from reaching the database layer.
+      Adds type checking and parameter validation before processing.
+
+      Impact: Improved error handling and reduced DB load.
+
+  - description: "Private API change"
+    input: |
+      Update FrobWidget to use internal Foo::Bar API
+
+      Rails changed their implementation from X to Y. While both
+      are private APIs, this change is required to maintain
+      compatibility.
+
+      Note: Created ticket RAIL-123 to track moving to public
+      APIs when available.
+
+  - description: "Dependency update"
+    input: |
+      Bump rails to 7737f646773
+
+      Updates our rails checkout to latest main. Key changes:
+      - Journey routing internals refactored
+      - ActiveSupport::TimeZone improvements
+      - New ActionMailer configuration options
+
+      Test plan: Full CI suite + extra routing specs
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

data/.cursor/rules/component_context.mdc

@@ -0,0 +1,82 @@
+---
+description:
+globs: **/calzini/**/*.rb
+alwaysApply: false
+---
+# Component Context
+
+<rule>
+name: component_context
+description: Share relevant component documentation when working with Calzini components and widgets
+filters:
+  - type: file
+    pattern: **/*component*.rb
+  - type: file
+    pattern: **/*component*.md
+  - type: file
+    pattern: **/*calzini*.rb
+  - type: file
+    pattern: **/*calzini*.md
+  - type: file
+    pattern: **/*widget*.rb
+  - type: file
+    pattern: **/*widget*.md
+
+actions:
+  - type: suggest
+    message: |
+      # Component Context
+
+      When working with Scarpe's component system (Calzini), consider:
+
+      1. Component Architecture
+         - [calzini_components_and_updates.md](mdc:docs/calzini_components_and_updates.md) - Core component documentation
+         - [scarpe_shoes_incompatibilities.md](mdc:docs/scarpe_shoes_incompatibilities.md) - API differences from Shoes
+
+      2. Component Lifecycle:
+         ```ruby
+         class CalziniComponent
+           def initialize
+             setup_state
+             register_handlers
+           end
+
+           def update
+             calculate_layout
+             trigger_display_update
+           end
+         end
+         ```
+
+      3. State Management:
+         - Internal component state
+         - Props from parent components
+         - Global application state
+         - Shared resources
+
+      4. Best Practices:
+         - Keep components focused and single-purpose
+         - Handle state updates efficiently
+         - Consider compatibility with original Shoes
+         - Maintain proper event handling
+
+      5. Additional Resources:
+         - Wiki: https://github.com/scarpe-team/scarpe/wiki/ScarpeDesign.md#calzini-components-and-updates
+         - Related sections:
+           * Display Service Separation
+           * Event Loops
+           * Shoes and Display Events
+
+examples:
+  - description: "Working with components"
+    input: |
+      When implementing components:
+      1. Follow the component lifecycle
+      2. Handle state updates properly
+      3. Consider compatibility implications
+      4. Use proper event handling patterns
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

data/.cursor/rules/debug-failed-tests.mdc

@@ -0,0 +1,100 @@
+---
+description: A rule to guide the debugging process when tests fail by adding puts statements, analyzing output, fixing the issue, and cleaning up.
+globs: "**/*_test.rb"
+---
+# Debug Failed Tests
+
+A rule that guides you to add debugging statements when a test fails, run the test again to understand the issue, implement a fix, and then remove the debugging statements once everything works.
+
+<rule>
+name: debug_failed_tests
+description: When a test fails, add debugging statements before implementing a fix
+filters:
+  - type: event
+    pattern: "test_failed"
+
+actions:
+  - type: suggest
+    message: |
+      # Add debugging statements
+
+      Identify the failing test and add strategic 'puts' statements to print relevant variables, state, or execution flow information that might help diagnose the issue.
+
+      Example:
+      ```ruby
+      # Before
+      def calculate_total(items)
+        items.sum { |item| item[:price] * item[:quantity] }
+      end
+
+      # After adding debugging
+      def calculate_total(items)
+        puts "Items received: #{items.inspect}"
+        total = items.sum do |item|
+          puts "Processing item: #{item[:name]}, price: #{item[:price]}, quantity: #{item[:quantity]}"
+          item[:price] * item[:quantity]
+        end
+        puts "Calculated total: #{total}"
+        total
+      end
+      ```
+
+  - type: suggest
+    message: |
+      # Run the test with debugging
+
+      Run the failing test again and analyze the debugging output to understand what's happening and why the test is failing.
+
+  - type: suggest
+    message: |
+      # Implement a fix
+
+      Now that you understand the issue better from the debugging output, implement a solution to fix the failing test.
+
+  - type: suggest
+    message: |
+      # Verify the fix
+
+      Run the test again to ensure your fix resolves the issue and the test now passes.
+
+  - type: suggest
+    message: |
+      # Clean up debugging statements
+
+      Now that the test is passing, remove all the debugging statements you added to keep the code clean and production-ready.
+
+      Example:
+      ```ruby
+      # Before (with debugging)
+      def calculate_total(items)
+        puts "Items received: #{items.inspect}"
+        total = items.sum do |item|
+          puts "Processing item: #{item[:name]}, price: #{item[:price]}, quantity: #{item[:quantity]}"
+          item[:price] * item[:quantity]
+        end
+        puts "Calculated total: #{total}"
+        total
+      end
+
+      # After (debugging removed)
+      def calculate_total(items)
+        items.sum { |item| item[:price] * item[:quantity] }
+      end
+      ```
+
+examples:
+  - input: |
+      # A failing test for a calculation method
+      def test_calculate_total
+        items = [
+          { name: "Item 1", price: 10, quantity: 2 },
+          { name: "Item 2", price: 15, quantity: 3 }
+        ]
+        assert_equal 65, calculate_total(items)
+      end
+    output: "Added debugging, fixed the issue, and removed debugging statements"
+
+metadata:
+  priority: medium
+  version: 1.0
+</rule>

data/.cursor/rules/display_service_context.mdc

@@ -0,0 +1,80 @@
+---
+description:
+globs: **/*display*.rb,**/*display_service*.rb,**/*display*.md
+alwaysApply: false
+---
+# Display Service Context
+
+<rule>
+name: display_service_context
+description: Share relevant display service documentation and implementation details when working with display service files
+filters:
+  - type: file
+    pattern: **/*display*.rb
+  - type: file
+    pattern: **/*display_service*.rb
+  - type: file
+    pattern: **/*display*.md
+
+actions:
+  - type: suggest
+    message: |
+      # Display Service Context
+
+      When working with Scarpe's display service, it's important to understand the core architectural decisions:
+
+      1. The display service runs as a separate process from the main application
+      2. Communication happens through a well-defined protocol
+      3. Different display implementations can be swapped out
+      4. The system supports both local and relay-based display services
+
+      Key files and concepts:
+      - [display_service_separation.md](mdc:docs/display_service_separation.md) - Core architectural documentation
+      - `Shoes::DisplayService` - Base display service class
+      - `Scarpe::Webview::DisplayService` - Webview implementation
+      - `Scarpe::Webview::RelayDisplayService` - Process separation implementation
+
+      Implementation patterns:
+      ```ruby
+      # Display service singleton pattern
+      class DisplayService < Shoes::DisplayService
+        class << self
+          attr_accessor :instance
+        end
+
+        def initialize
+          if DisplayService.instance
+            raise Shoes::Errors::SingletonError, "ERROR! This is meant to be a singleton!"
+          end
+          DisplayService.instance = self
+        end
+      end
+      ```
+
+      Event handling:
+      ```ruby
+      # Event dispatch pattern
+      def dispatch_event(event_name, event_target, *args, **kwargs)
+        handlers = [
+          same_name_handlers[:any],           # Same name, any target
+          same_name_handlers[event_target],   # Same name, same target
+          any_name_handlers[:any],            # Any name, any target
+          any_name_handlers[event_target],    # Any name, same target
+        ].compact.inject([], &:+)
+        handlers.each { |h| h[:handler].call(*args, **kwargs) }
+      end
+      ```
+
+examples:
+  - description: "Working with display service implementation"
+    input: |
+      When implementing a new display service or modifying an existing one:
+      1. Follow the singleton pattern for display service instances
+      2. Implement proper event handling and dispatch
+      3. Ensure clean process separation if using relay approach
+      4. Handle drawable creation and management consistently
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

data/.cursor/rules/event_handling_context.mdc

@@ -0,0 +1,100 @@
+---
+description: Share event handling context when working with event-related files
+globs:
+alwaysApply: false
+---
+# Event Handling Context
+
+<rule>
+name: event_handling_context
+description: Share relevant event handling and testing documentation when working with event-related files
+filters:
+  - type: file
+    pattern: **/*event*.rb
+  - type: file
+    pattern: **/*event*.md
+  - type: file
+    pattern: **/*loop*.rb
+  - type: file
+    pattern: **/*loop*.md
+  - type: file
+    pattern: **/*fiber*.rb
+  - type: file
+    pattern: **/*fiber*.md
+  - type: file
+    pattern: **/*catscradle*.rb
+  - type: file
+    pattern: **/*catscradle*.md
+
+actions:
+  - type: suggest
+    message: |
+      # Event Handling Context
+
+      When working with Scarpe's event system, it's important to understand:
+
+      1. Event Loop Architecture
+         - [event_loops.md](mdc:docs/event_loops.md) - Core event loop documentation
+         - [shoes_and_display_events.md](mdc:docs/shoes_and_display_events.md) - Event handling details
+         - [catscradle.md](mdc:docs/yard/catscradle.md) - Fiber-based testing approach
+
+      2. Key Testing Concepts:
+         ```ruby
+         # Example of Fiber-based test
+         def test_html_dom_multiple_update
+           run_test_scarpe_code(<<-'SCARPE_APP', app_test_code: <<-'TEST_CODE')
+             Shoes.app do
+               para "Hello World"
+             end
+           SCARPE_APP
+             on_heartbeat do
+               p = para()
+               assert_include dom_html, "Hello World"
+               p.replace("Goodbye World")
+               wait fully_updated
+               assert_include dom_html, "Goodbye World"
+               test_finished
+             end
+           TEST_CODE
+         end
+         ```
+
+      3. Event Types:
+         - Mouse events (click, hover, etc.)
+         - Keyboard events
+         - Window events
+         - Custom events
+         - Heartbeat events
+
+      4. Implementation Details:
+         - Events are queued in order of arrival
+         - Priority system for critical events
+         - Fiber-based coordination for testing
+         - Cooperative multitasking approach
+
+      5. Best Practices:
+         - Keep handlers fast and focused
+         - Use Fiber-based testing for complex interactions
+         - Handle errors appropriately
+         - Maintain proper process separation
+
+      6. Additional Resources:
+         - Wiki: https://github.com/scarpe-team/scarpe/wiki/ScarpeDesign.md#event-loops
+         - Related sections:
+           * Display Service Separation
+           * Shoes and Display Events
+           * Timeouts and handlers
+
+examples:
+  - description: "Working with event handlers"
+    input: |
+      When implementing event handling:
+      1. Consider using Fiber-based testing for complex scenarios
+      2. Keep handlers non-blocking
+      3. Use proper event dispatch patterns
+      4. Consider process separation implications
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

data/.cursor/rules/git-pager-handling.mdc

@@ -0,0 +1,64 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+<rule>
+name: git_pager_handling
+description: When running git commands that would normally use a pager, append | cat to prevent breaking automated environments
+
+filters:
+  - type: command
+    pattern: "^git (diff|log|show|blame)"
+  - type: command
+    pattern: "^git.*\\|(\\s+)?less"
+  - type: command
+    pattern: "^git.*\\|(\\s+)?more"
+
+actions:
+  - type: suggest
+    message: |
+      # Git Pager Handling
+
+      When running git commands that would normally use a pager (like `git diff`, `git log`, etc.), always append `| cat` to prevent the pager from breaking the output. This is especially important in automated environments.
+
+      ## Examples
+
+      ```bash
+      # Good
+      git diff HEAD~1 HEAD | cat
+      git log | cat
+      git show | cat
+
+      # Bad
+      git diff HEAD~1 HEAD
+      git log
+      git show
+      ```
+
+      ## Common Commands Needing `| cat`
+
+      - `git diff`
+      - `git log`
+      - `git show`
+      - `git blame`
+      - Any other git command that might produce paginated output
+
+      ## Why?
+
+      The pager (usually `less` or `more`) expects user interaction, which isn't available in automated environments. Piping to `cat` ensures we get the full output without pagination.
+
+examples:
+  - description: "Running git diff in automated environment"
+    input: |
+      git diff HEAD~1 HEAD | cat
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

data/.cursor/rules/lacci-context.mdc

@@ -0,0 +1,52 @@
+---
+description:
+globs: lacci/**/*
+alwaysApply: false
+---
+# Lacci Context
+
+<rule>
+name: lacci_context
+description: Provides information about Lacci's purpose and operation
+filters:
+  - type: glob
+    pattern: "lacci/**/*"
+
+actions:
+  - type: suggest
+    message: |
+      # Working with Lacci
+
+      [lacci.md](mdc:docs/lacci.md)
+
+      You are currently working in Lacci, the Shoes4 compatibility layer for Scarpe.
+      For detailed documentation, see: docs/lacci.md
+
+      Key points to remember:
+      1. Lacci translates Shoes4 commands to display-agnostic operations
+      2. Uses Niente (null display service) for testing
+      3. Implements drawing context inheritance
+      4. Handles margins, fonts, and layout
+
+      Common patterns:
+      - Test new features with Niente first
+      - Follow existing error handling patterns
+      - Maintain backward compatibility
+      - Document changes thoroughly
+
+examples:
+  - description: "Adding a new drawing primitive"
+    input: |
+      # Example of adding a new shape
+      module Shoes
+        class Triangle < Shape
+          def initialize(app, left, top, width, height, **styles)
+            super(app, left, top, width, height, **styles)
+          end
+        end
+      end
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

data/.cursor/rules/scarpe_design_context.mdc

@@ -0,0 +1,46 @@
+---
+description: Share Scarpe design context when working on related files
+globs: docs/*.md
+alwaysApply: false
+---
+# Scarpe Design Context
+
+<rule>
+name: scarpe_design_context
+description: Share relevant Scarpe design documentation when working on related files
+filters:
+  - type: file
+    pattern: "docs/*.md"
+
+actions:
+  - type: suggest
+    message: |
+      # Scarpe Design Context
+
+      When working on Scarpe-related files, it's important to consider the design principles and decisions made during its development. Here are key documents that provide context:
+
+      - @display_service_separation.md
+      - @shoes_and_display_events.md
+      - @event_loops.md
+      - @timeouts_and_handlers.md
+      - @calzini_components_and_updates.md
+      - @scarpe_shoes_incompatibilities.md
+      - @shoes_implementations.md
+      - @web_archaeology.md
+
+      These documents cover various aspects of Scarpe's design, including its relationship with Shoes, event handling, and component updates. Refer to them for a deeper understanding of the project's architecture and design choices.
+
+examples:
+  - description: "Working on a Scarpe component"
+    input: |
+      # Working on a new Scarpe component
+
+      When creating a new component, it's crucial to understand how Scarpe handles updates and events. Refer to the following documents for guidance:
+
+      - @calzini_components_and_updates.md
+      - @shoes_and_display_events.md
+
+metadata:
+  priority: medium
+  version: 1.0
+</rule>

data/.cursor/rules/shoes_compatibility_context.mdc

@@ -0,0 +1,75 @@
+---
+description:
+globs: **/*shoes*.rb,**/*shoes*.md
+alwaysApply: false
+---
+# Shoes Compatibility Context
+
+<rule>
+name: shoes_compatibility_context
+description: Share relevant compatibility documentation when working with Shoes implementations
+filters:
+  - type: file
+    pattern: **/*shoes*.rb
+  - type: file
+    pattern: **/*shoes*.md
+  - type: file
+    pattern: **/*compatibility*.rb
+  - type: file
+    pattern: **/*compatibility*.md
+  - type: file
+    pattern: **/*compat*.rb
+  - type: file
+    pattern: **/*compat*.md
+
+actions:
+  - type: suggest
+    message: |
+      # Shoes Compatibility Context
+
+      When working with Shoes compatibility, consider:
+
+      1. Implementation History
+         - @docs/shoes_implementations.md - Various Shoes implementations
+         - @docs/scarpe_shoes_incompatibilities.md - Known differences
+         - @docs/web_archaeology.md - Historical context
+
+      2. Key Differences:
+         - Method names and signatures
+         - Event handling behavior
+         - Layout system changes
+         - API modifications
+
+      3. Implementation Types:
+         - Original Shoes (C/Ruby)
+         - Green Shoes (GTK+)
+         - Purple Shoes (Windows)
+         - Scarpe (Web-based)
+
+      4. Best Practices:
+         - Document incompatibilities clearly
+         - Provide migration paths when possible
+         - Consider cross-implementation testing
+         - Maintain historical context
+
+      5. Additional Resources:
+         - Wiki: https://github.com/scarpe-team/scarpe/wiki/ScarpeDesign.md#scarpe-shoes-incompatibilities
+         - Related sections:
+           * Display Service Separation
+           * Event Loops
+           * Timeouts and handlers
+           * Calzini Components
+
+examples:
+  - description: "Working with Shoes compatibility"
+    input: |
+      When handling compatibility:
+      1. Check implementation differences
+      2. Document API changes
+      3. Consider migration paths
+      4. Test across implementations
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>