scarpe 0.4.0 → 0.5.0

data/.cursor/rules/timeout_context.mdc

@@ -0,0 +1,78 @@
+---
+description: Share timeout and handler context when working with timing-related code
+globs:
+alwaysApply: false
+---
+# Timeout and Handler Context
+
+<rule>
+name: timeout_context
+description: Share relevant timeout and handler documentation when working with timing-related code
+filters:
+  - type: file
+    pattern: **/*timeout*.rb
+  - type: file
+    pattern: **/*timeout*.md
+  - type: file
+    pattern: **/*handler*.rb
+  - type: file
+    pattern: **/*handler*.md
+  - type: file
+    pattern: **/*timer*.rb
+  - type: file
+    pattern: **/*timer*.md
+
+actions:
+  - type: suggest
+    message: |
+      # Timeout and Handler Context
+
+      When working with Scarpe's timeout and handler system, consider:
+
+      1. Timeout Implementation
+         - [timeouts_and_handlers.md](mdc:docs/timeouts_and_handlers.md) - Core timeout documentation
+         - [event_loops.md](mdc:docs/event_loops.md) - Event loop integration
+
+      2. Key Concepts:
+         ```ruby
+         def after(milliseconds, &block)
+           register_timeout(Time.now + (milliseconds / 1000.0), block)
+         end
+         ```
+
+      3. Cooperative Nature:
+         - Timeouts don't interrupt execution
+         - Processed when event loop is ready
+         - Timing is approximate, not exact
+
+      4. Handler Registration:
+         - Handlers registered with specific events
+         - Multiple handlers per event possible
+         - Order of execution preserved
+
+      5. Best Practices:
+         - Keep handlers non-blocking
+         - Use appropriate timing granularity
+         - Consider event loop implications
+         - Handle errors appropriately
+
+      6. Additional Resources:
+         - Wiki: https://github.com/scarpe-team/scarpe/wiki/ScarpeDesign.md#timeouts-and-handlers
+         - Related sections:
+           * Event Loops
+           * Display Service Separation
+           * Shoes and Display Events
+
+examples:
+  - description: "Working with timeouts"
+    input: |
+      When implementing timeouts:
+      1. Consider cooperative nature
+      2. Use appropriate timing
+      3. Keep handlers non-blocking
+      4. Handle errors properly
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

data/.cursor/rules/update_lacci_and_wv.mdc

@@ -0,0 +1,8 @@
+---
+description:
+globs: lacci/**/*,lib/scarpe/wv/**/*,lib/scarpe/wv/*.rb
+alwaysApply: false
+---
+Ensure, that you recognize that a webview (WV) drawable and lacci drawable must BOTH be updated when adding new user DSL/features.
+
+You also need to update calzini under scarpe-components

data/.cursor/rules/what_is_scarpe.mdc

@@ -0,0 +1,22 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+Scarpe is a modern attempt at an implementation of Why The Lucky Stiff's Shoes.rb.
+
+It is not complete.
+
+It is built on Webview.
+
+Our primary goal is to as many shoes apps from `examples/legacy/not_checked` working as possible. So, you can check them for bits of DSL that aren't yet up to scratch. They used to work.
+
+`docs/static/manual-en.txt` is our "bible". It is nearly a perfect representation of how Shoes _should_ work. It's what we want to do. With every fibre of your being I want you to help me get the not checked examples working and anything from this manual.
+
+It is 3,500 lines long though.
+
+To run an example to see if it's working (I'll have to check) run something like:
+
+`SCARPE_BOOTSTRAP_THEME=sketchy bundle exec ./exe/scarpe examples/page_navigation_single_app.rb --debug
+`
+

data/.cursor/rules/writing-new-rules.mdc

@@ -0,0 +1,73 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+# Writing New Rules
+
+<rule>
+name: writing_new_rules
+description: Guidelines for creating and formatting new rules in the rules directory
+filters:
+  - type: event
+    pattern: "new_rule_creation"
+
+actions:
+  - type: suggest
+    message: |
+      # Rule Creation Process
+
+      1. Always create new rules with .mc extension first:
+         - Create file as `.cursor/rules/rule-name.mc`
+         - Only convert to .mdc after content is approved
+
+      2. Required File Structure:
+         ```
+         ---
+         description: Brief description of the rule's purpose
+         globs: "pattern to match files this rule applies to"
+         ---
+         # Rule Title
+
+         <rule>
+         name: rule_name
+         description: Detailed description
+         filters:
+           - type: event
+             pattern: "relevant_event"
+
+         actions:
+           - type: suggest
+             message: |
+               # Action Title
+               Action content...
+
+         examples:
+           - description: "Example scenario"
+             input: |
+               Example input...
+
+         metadata:
+           priority: level
+           version: 1.0
+         </rule>
+         ```
+
+      3. After approval, rename to .mdc:
+         ```bash
+         mv .cursor/rules/rule-name.mc .cursor/rules/rule-name.mdc
+         ```
+
+examples:
+  - description: "Creating a new rule"
+    input: |
+      # First create with .mc extension
+      touch .cursor/rules/new-feature.mc
+
+      # After approval, rename to .mdc
+      mv .cursor/rules/new-feature.mc .cursor/rules/new-feature.mdc
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

data/CHANGELOG.md

@@ -4,12 +4,21 @@ Here we write upgrading notes for brands. It's a team effort to make them as
 straightforward as possible.
 
 ### Enhancements
+- Added CLAUDE.md for agentic coding assistance
+- Removed bloops as a required dependency - sound is now opt-in (install bloops gem separately if needed)
+- Added base64 gem dependency for Ruby 3.4+ compatibility
 
 ### Bugs Fixed
-- #-some-pr-number <description> @author-of-pr
+- #569 link(click: "/path") now triggers internal navigation via visit(); paths like "/foo" also fall back to page(:foo) if no URL route matches
+- Support for `class MyApp < Shoes` inheritance pattern with URL routing
+- Fixed background() with remote URLs (now properly wrapped in CSS url())
 
 ### Incompatibilities
 
+## [0.4.0] - 2024-05-06 - Strangers
+
+Core Scarpe has been relatively stable for awhile. A lot of this release is bugfixes and refactors.
+
 ## [0.3.1] - 2023-??-?? - Up
 
 Lots of bug fixes. We're also still implementing major Shoes3 features.

data/CLAUDE.md

@@ -0,0 +1,223 @@
+# Scarpe - AI Assistant Context
+
+> *In loving memory of Noah Gibbs, who believed in this project and whose thoughtful documentation lives on in every design decision.*
+
+## What is Scarpe?
+
+**Scarpe** (Italian for "shoes") is a modern reimplementation of [Why The Lucky Stiff's Shoes](https://github.com/shoes/shoes-deprecated) - a beloved Ruby GUI toolkit that made desktop app creation accessible to absolute beginners.
+
+```ruby
+# This is all it takes to create a window with a button
+Shoes.app { button("Click me!") { alert("Good job.") } }
+```
+
+Scarpe preserves _why's elegant DSL while building on modern technology (Webview). It is **not yet complete**, but actively maintained.
+
+## The Mission
+
+Our primary goal is **backwards compatibility with classic Shoes apps**. We want old Shoes programs to just work.
+
+### The Bible
+
+`docs/static/manual.md` (3,500+ lines) is our authoritative reference for how Shoes _should_ work. Every implementation decision should align with this manual.
+
+### The Proving Ground
+
+`examples/legacy/not_checked/` contains Shoes apps that **used to work** in classic Shoes. Getting these examples running is our north star.
+
+## Architecture Overview
+
+Scarpe has a layered architecture:
+
+### Lacci (The Compatibility Layer)
+**Location:** `lacci/`
+
+Lacci (Italian for "laces") translates Shoes commands into display-agnostic operations:
+- Implements the Shoes4 drawing model (stacks, flows, slots)
+- Handles margin calculations, fonts, layout
+- Uses **Niente** (null display service) for testing
+
+See: `docs/lacci.md`
+
+### Display Service (The Renderer)
+**Location:** `lib/scarpe/`
+
+The display service runs as a **separate process** from the main application:
+- Clear separation between app logic and display logic
+- Different display implementations can be swapped
+- Communication via well-defined message protocol
+- Supports local and relay-based services
+
+See: `docs/display_service_separation.md`
+
+### Calzini (The Components)
+Components follow a lifecycle pattern with state management and event handling.
+
+See: `docs/calzini_components_and_updates.md`
+
+## Key Documentation
+
+All in `docs/`:
+
+| Document | Purpose |
+|----------|---------|
+| `static/manual.md` | **THE BIBLE** - How Shoes should work |
+| `lacci.md` | Compatibility layer documentation |
+| `display_service_separation.md` | Architecture decisions |
+| `shoes_and_display_events.md` | Event handling details |
+| `event_loops.md` | Event loop architecture |
+| `timeouts_and_handlers.md` | Timing and callbacks |
+| `calzini_components_and_updates.md` | Component system |
+| `scarpe_shoes_incompatibilities.md` | Known differences from Shoes |
+| `shoes_implementations.md` | History of Shoes implementations |
+| `SCARPE_FEATURES.md` | New features beyond original Shoes |
+| `yard/catscradle.md` | Fiber-based testing approach |
+
+## Running Scarpe
+
+```bash
+# Install dependencies (Linux only - Mac works out of the box)
+sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev  # Ubuntu/Debian
+
+# Install gems
+bundle install
+
+# Run an example
+./exe/scarpe examples/button.rb --dev --debug
+
+# With a theme
+SCARPE_BOOTSTRAP_THEME=sketchy bundle exec ./exe/scarpe examples/button.rb --debug
+
+# Optional: For sound support (bloopsaphone examples)
+# gem install bloops  # requires portaudio: brew install portaudio (Mac)
+```
+
+## Testing
+
+```bash
+# Run all tests
+bundle exec rake ci_test
+
+# Run component tests
+bundle exec rake lacci_test      # Lacci tests
+bundle exec rake component_test  # Scarpe-components tests
+bundle exec rake test           # Scarpe tests
+
+# Check HTML output
+bundle exec rake test:check_html_fixtures
+```
+
+### Testing Philosophy
+
+- Test new features with **Niente** (null display) first
+- Use **Fiber-based testing** for complex event interactions (see CatsCradle)
+- Keep handlers non-blocking
+- Maintain backward compatibility
+
+## Development Workflow
+
+### When Debugging Failed Tests
+
+1. Add strategic `puts` statements to understand the issue
+2. Run the test and analyze output
+3. Implement the fix
+4. Verify the fix
+5. **Remove all debugging statements before committing**
+
+### Commit Style
+
+```
+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.
+```
+
+- First line: Clear statement of WHAT (50 chars ideal)
+- Empty line after header
+- Body: WHY needed, HOW it works, technical implications
+
+## Code Patterns
+
+### Display Service Singleton
+```ruby
+class DisplayService < Shoes::DisplayService
+  class << self
+    attr_accessor :instance
+  end
+
+  def initialize
+    if DisplayService.instance
+      raise Shoes::Errors::SingletonError, "This is meant to be a singleton!"
+    end
+    DisplayService.instance = self
+  end
+end
+```
+
+### Event Dispatch
+```ruby
+def dispatch_event(event_name, event_target, *args, **kwargs)
+  handlers = [
+    same_name_handlers[:any],
+    same_name_handlers[event_target],
+    any_name_handlers[:any],
+    any_name_handlers[event_target],
+  ].compact.inject([], &:+)
+  handlers.each { |h| h[:handler].call(*args, **kwargs) }
+end
+```
+
+## Core Values
+
+From the README:
+- **Resiliency** - Tested and trustworthy
+- **User Experience** - Beautiful, easy DSL
+- **Whimsy** - We're here to have fun! Chunky Bacon. 🥓
+- **Empathy** - Help one another
+
+## Adding New Features
+
+New features beyond original Shoes require approval and must:
+1. Not conflict with backwards compatibility
+2. Be documented in `docs/SCARPE_FEATURES.md`
+3. Follow existing patterns
+
+Example: Page navigation (`page(:home)`, `visit(:another_page)`)
+
+## Project Structure
+
+```
+scarpe/
+├── lacci/           # Shoes4 compatibility layer
+├── lib/scarpe/      # Display service implementations
+├── scarpe-components/  # Shared components
+├── examples/        # Example apps
+│   └── legacy/not_checked/  # Apps to fix!
+├── docs/            # Design documentation
+│   └── static/manual.md    # THE BIBLE
+├── test/            # Test suite
+└── exe/scarpe       # Main executable
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `SCARPE_DISPLAY_SERVICE` | Choose display service (wv_local, wv_relay, etc.) |
+| `SCARPE_TEST_CONTROL` | Path to test control script |
+| `SCARPE_LOG_CONFIG` | YAML file for component log levels |
+| `SCARPE_BOOTSTRAP_THEME` | UI theme (e.g., "sketchy") |
+
+## Links
+
+- [GitHub Repository](https://github.com/scarpe-team/scarpe)
+- [Wiki](https://github.com/scarpe-team/scarpe/wiki)
+- [Discord](https://discord.gg/Ca5EHSsGYp)
+- [Nobody Knows Shoes - _why's Manual](https://github.com/whymirror/why-archive/raw/master/shoes/nobody-knows-shoes.pdf)
+
+---
+
+*Scarpe Diem: Seize the Shoes*

data/Gemfile

@@ -8,7 +8,6 @@ gemspec
 gem "lacci", path: "lacci"
 gem "scarpe-components", path: "scarpe-components"
 
-gem "bloops", "~> 0.5" #path: "../bloopsaphone" #git: "https://github.com/scarpe-team/bloopsaphone"
 gem "rake", "~> 13.0"
 
 group :test do

data/Gemfile.lock

@@ -1,101 +1,122 @@
 PATH
   remote: .
   specs:
-    scarpe (0.3.0)
-      bloops (~> 0.5)
-      fastimage
-      lacci
+    scarpe (0.4.0)
+      base64
+      fastimage (~> 2.2.7)
+      lacci (~> 0.4.0)
       logging (~> 2.3.1)
-      nokogiri
-      scarpe-components
-      sqlite3
-      webrick
+      nokogiri (~> 1.15.2)
+      scarpe-components (~> 0.4.0)
+      sqlite3 (~> 1.6.3)
+      webrick (~> 1.7.0)
       webview_ruby (~> 0.1.1)
 
 PATH
   remote: lacci
   specs:
-    lacci (0.3.0)
-      scarpe-components
+    lacci (0.4.0)
+      scarpe-components (~> 0.4.0)
 
 PATH
   remote: scarpe-components
   specs:
-    scarpe-components (0.3.0)
+    scarpe-components (0.4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ansi (1.5.0)
-    ast (2.4.2)
-    bloops (0.5)
-    builder (3.2.4)
-    debug (1.8.0)
-      irb (>= 1.5.0)
-      reline (>= 0.3.1)
-    diff-lcs (1.5.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    builder (3.3.0)
+    date (3.5.1)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
+    erb (6.0.1)
     fastimage (2.2.7)
-    ffi (1.15.5)
-    ffi-compiler (1.0.1)
-      ffi (>= 1.0.0)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    ffi-compiler (1.3.2)
+      ffi (>= 1.15.5)
       rake
-    htmlbeautifier (1.4.2)
-    io-console (0.6.0)
-    irb (1.6.4)
-      reline (>= 0.3.0)
-    json (2.6.3)
+    htmlbeautifier (1.4.3)
+    io-console (0.8.2)
+    irb (1.16.0)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
     little-plugger (1.1.4)
     logging (2.3.1)
       little-plugger (~> 1.1)
       multi_json (~> 1.14)
-    minitest (5.18.0)
-    minitest-reporters (1.6.0)
+    mini_portile2 (2.8.9)
+    minitest (5.27.0)
+    minitest-reporters (1.7.1)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
-    multi_json (1.15.0)
-    nokogiri (1.15.2-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.15.2-x86_64-darwin)
+    multi_json (1.18.0)
+    nokogiri (1.15.7)
+      mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
-    nokogiri (1.15.2-x86_64-linux)
-      racc (~> 1.4)
-    parallel (1.22.1)
-    parser (3.2.1.0)
+    parallel (1.27.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
-    racc (1.7.1)
+      racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.7.0)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    redcarpet (3.6.0)
-    regexp_parser (2.7.0)
-    reline (0.3.4)
+    rake (13.3.1)
+    rdoc (7.0.2)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    redcarpet (3.6.1)
+    regexp_parser (2.11.3)
+    reline (0.6.3)
       io-console (~> 0.5)
-    rexml (3.2.5)
-    rubocop (1.46.0)
+    rubocop (1.82.0)
       json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.26.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.26.0)
-      parser (>= 3.2.1.0)
-    ruby-progressbar (1.11.0)
-    sqlite3 (1.6.3-arm64-darwin)
-    sqlite3 (1.6.3-x86_64-darwin)
-    sqlite3 (1.6.3-x86_64-linux)
-    unicode-display_width (2.4.2)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.48.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    sqlite3 (1.6.9)
+      mini_portile2 (~> 2.8.0)
+    stringio (3.2.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
     webrick (1.7.0)
     webview_ruby (0.1.2)
       ffi
       ffi-compiler
       rake
-    yard (0.9.28)
-      webrick (~> 1.7.0)
+    yard (0.9.38)
 
 PLATFORMS
   arm64-darwin-21
@@ -108,7 +129,6 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  bloops (~> 0.5)
   debug
   diff-lcs
   htmlbeautifier

data/README.md

@@ -5,7 +5,7 @@
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-shopify-brightgreen.svg)](https://github.com/Shopify/ruby-style-guide)
 [![Discord](https://img.shields.io/discord/1072538177321058377?label=discord)](https://discord.gg/Ca5EHSsGYp)
 
-<img src="https://user-images.githubusercontent.com/7865030/217309905-7f25e3cf-1850-481d-811b-dfddea2df54a.png" width="200" height="200">
+<img src="docs/static/scarpe-logo.png">
 
 "Scarpe" means shoes in Italian. "Scarpe" also means [Shoes](https://github.com/shoes/shoes-deprecated) in modern Ruby and Webview!
 
@@ -64,14 +64,11 @@ Scarpe requires [Ruby 3.2](https://www.ruby-lang.org/en/downloads/) or higher! Y
 This repo is where most of the action is happening right now, and to have the full Scarpe experience _today_ this is probably what you want to do.
 
 ```
-# dependencies - Mac version
-brew install portaudio pkg-config # for sound!
-# dependencies - Mac M1 version
-brew install portaudio && bundle config build.bloops --with-portaudio-dir=$(brew --prefix portaudio)
 # dependencies - Ubuntu Linux version
-sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev portaudio19-dev
+sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev
 
-for any other Linux or Windows please see the webview docs for your [platform](https://github.com/webview/webview#prerequisites)
+# for any other Linux or Windows please see the webview docs for your platform:
+# https://github.com/webview/webview#prerequisites
 
 # get it
 git clone http://github.com/scarpe-team/scarpe