pulse_zero 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d243fa7e75252ee44f79f39ca3b2c94718a541745662db23950d654f4b781ae9
-  data.tar.gz: f40ad0d09e0f3befd5ac36d4826ec49c87ef6de99299b580537f66ccb13c7dea
+  metadata.gz: e6a8b21ed27a36968fdafbc307f696a435bec0aa776f4d217e6f92c73a81b890
+  data.tar.gz: a68d614d85077616fa9187618242d4437f4dd27e09330ef563e703442b27c719
 SHA512:
-  metadata.gz: b2d0f0a24c3df60801a5a90298100ae52ed4ff5172f2ba5d0f3b1aa59f7d2f140b10e0fa65f394997ccb92dd93f8a81ea413ad84d44946b7de3d2ddc47173c96
-  data.tar.gz: 0f03276d631c1ef157db668eb8dae7e86f875c7e7c5f87b72fe559890f83fbc753eabae8fbff11869c4ab690d0b040cacd8c114ed0bef91ecaf4bc4c839deaec
+  metadata.gz: ff16c5c80bc52b4c739fd308e4c79f177b0ea9d4d6a2eacd7cb4501e622bd0a9a91b4992ece15d827a77b9ee789d4ad1e5a502aecb89a67fb693af78f19d50ce
+  data.tar.gz: ca85a9f358c257668e05fdd569f3f4a1ffc78cfa54cd7096928081b87c78da25290640eeea1b307510aacd1225d47c7d60853ed5f7cacacee9d9f545b94c5576

data/README.md

@@ -6,6 +6,8 @@ Real-time broadcasting generator for Rails + Inertia.js applications. Generate a
 
 Pulse Zero generates a complete real-time broadcasting system directly into your Rails application. Unlike traditional gems, all code is copied into your project, giving you full ownership and the ability to customize everything.
 
+Inspired by Turbo Rails, Pulse Zero brings familiar broadcasting patterns to Inertia.js applications. If you've used `broadcasts_to` in Turbo Rails, you'll feel right at home with Pulse Zero's API.
+
 Features:
 - 🚀 WebSocket broadcasting via ActionCable
 - 🔒 Secure signed streams
@@ -13,6 +15,7 @@ Features:
 - 🔄 Automatic reconnection with exponential backoff
 - 📦 TypeScript support for Inertia + React
 - 🎯 Zero runtime dependencies
+- 🏗️ Turbo Rails-inspired API design
 
 ## Installation
 
@@ -57,11 +60,11 @@ rails generate pulse_zero:install
 class Post < ApplicationRecord
   include Pulse::Broadcastable
   
-  # Broadcast to account-scoped channel
-  broadcasts_to ->(post) { [post.account, "posts"] }
+  # Broadcast to a simple channel
+  broadcasts_to ->(post) { "posts" }
   
-  # Or broadcast to a simple channel
-  broadcasts "posts"
+  # Or broadcast to account-scoped channel
+  # broadcasts_to ->(post) { [post.account, "posts"] }
 end
 ```
 
@@ -70,41 +73,106 @@ end
 ```ruby
 class PostsController < ApplicationController
   def index
-    @posts = Current.account.posts
-    @pulse_stream = Pulse::Streams::StreamName
-      .signed_stream_name([Current.account, "posts"])
+    @posts = Post.all
+
+    render inertia: "Post/Index", props: {
+      posts: @posts.map do |post|
+        serialize_post(post)
+      end,
+      pulseStream: Pulse::Streams::StreamName.signed_stream_name("posts")
+    }
+  end
+  
+  private
+  
+  def serialize_post(post)
+    {
+      id: post.id,
+      title: post.title,
+      content: post.content,
+      created_at: post.created_at
+    }
   end
 end
 ```
 
+**Why pulseStream?** Following Turbo Rails' security model, Pulse uses signed stream names to prevent unauthorized access to WebSocket channels. Since Inertia.js doesn't have a built-in way to access streams like Turbo does, we pass the signed stream name as a prop. This approach:
+- Maintains security through cryptographically signed tokens
+- Works naturally with Inertia's prop system
+- Keeps the API simple and explicit
+
 ### 3. Subscribe in React Component
 
 ```tsx
+import { useState } from 'react'
 import { usePulse } from '@/hooks/use-pulse'
 import { useVisibilityRefresh } from '@/hooks/use-visibility-refresh'
 import { router } from '@inertiajs/react'
 
-export default function Posts({ posts, pulseStream }) {
-  // Handle tab visibility
+interface IndexProps {
+  posts: Array<{
+    id: number
+    title: string
+    content: string
+    created_at: string
+  }>
+  pulseStream: string
+  flash: {
+    success?: string
+    error?: string
+  }
+}
+
+export default function Index({ posts: initialPosts, flash, pulseStream }: IndexProps) {
+  // Use local state for posts to enable real-time updates
+  const [posts, setPosts] = useState(initialPosts)
+  
+  // Automatically refresh data when returning to the tab after 30+ seconds
+  // This ensures users see fresh data after being away, handling cases where
+  // WebSocket messages might have been missed during browser suspension
   useVisibilityRefresh(30, () => {
     router.reload({ only: ['posts'] })
   })
-  
-  // Subscribe to real-time updates
+
+  // Subscribe to Pulse updates for real-time changes
   usePulse(pulseStream, (message) => {
     switch (message.event) {
       case 'created':
+        // Add the new post to the beginning of the list
+        setPosts(prev => [message.payload, ...prev])
+        break
       case 'updated':
+        // Replace the updated post in the list
+        setPosts(prev => 
+          prev.map(post => post.id === message.payload.id ? message.payload : post)
+        )
+        break
       case 'deleted':
-        router.reload({ only: ['posts'] })
+        // Remove the deleted post from the list
+        setPosts(prev => 
+          prev.filter(post => post.id !== message.payload.id)
+        )
+        break
+      case 'refresh':
+        // Full reload for refresh events
+        router.reload()
         break
     }
   })
   
-  return <PostsList posts={posts} />
+  return (
+    <>
+      {flash.success && <div className="alert-success">{flash.success}</div>}
+      <PostsList posts={posts} />
+    </>
+  )
 }
 ```
 
+**Note:** This example shows optimistic UI updates using local state. Alternatively, you can use `router.reload({ only: ['posts'] })` for all events to fetch fresh data from the server, which ensures consistency but may feel less responsive.
+
+**Why useVisibilityRefresh?** When users switch tabs or minimize their browser, WebSocket connections can be suspended and messages may be lost. The `useVisibilityRefresh` hook detects when users return to your app and automatically refreshes the data if they've been away for more than the specified threshold (30 seconds in this example). This ensures users always see up-to-date information without manual refreshing.
+
 ## Broadcasting Events
 
 Pulse broadcasts four types of events:
@@ -265,12 +333,13 @@ console.log(stats)
 
 ## Philosophy
 
-Pulse Zero follows the same philosophy as [authentication-zero](https://github.com/lazaronixon/authentication-zero):
+Pulse Zero follows the same philosophy as [authentication-zero](https://github.com/lazaronixon/authentication-zero), and is heavily inspired by [Turbo Rails](https://github.com/hotwired/turbo-rails). The API design closely mirrors Turbo Rails patterns, making it intuitive for developers already familiar with the Hotwire ecosystem.
 
 - **Own your code**: All code is generated into your project
 - **No runtime dependencies**: The gem is only needed during generation
 - **Customizable**: Modify any generated code to fit your needs
 - **Production-ready**: Includes battle-tested patterns from real applications
+- **Familiar API**: Inspired by Turbo Rails, uses similar broadcasting patterns and conventions
 
 ## Contributing
 

data/lib/generators/pulse_zero/install/install_generator.rb

@@ -131,31 +131,55 @@ module PulseZero
       def create_documentation
         template "docs/PULSE_USAGE.md.tt", "docs/PULSE_USAGE.md"
 
-        say "\n✅ Pulse real-time broadcasting has been installed!", :green
+        say "\n✅ Pulse Zero has been installed!", :green
+        say "🚀 Real-time broadcasting system generated with zero runtime dependencies", :blue
         say "\n⚠️  IMPORTANT: Configure authentication!", :yellow
         say "The default ApplicationCable connection accepts all connections."
         say "Edit app/channels/application_cable/connection.rb to add your authentication logic."
-        say "\nNext steps:", :yellow
-        say "1. Configure authentication in app/channels/application_cable/connection.rb"
-        say "2. Read docs/PULSE_USAGE.md for complete setup instructions"
-        say "3. Add 'include Pulse::Broadcastable' to models that need broadcasting"
-        say "4. Use 'usePulse' hook in your React components"
-        say "\nExample:", :blue
+        say "\nWhat was generated:", :yellow
+        say "• Backend: Broadcasting system in lib/pulse/, models, controllers, channels, and jobs"
+        say "• Frontend: TypeScript WebSocket management and React hooks"
+        say "• Security: Signed streams for secure channel subscriptions"
+        say "• Features: Auto-reconnection, tab suspension handling, and more"
+        say "\nQuick start:", :blue
         say <<~EXAMPLE
-          # In your model:
+          # 1. Enable broadcasting on a model:
           class Post < ApplicationRecord
             include Pulse::Broadcastable
-            broadcasts_to ->(post) { [post.account, "posts"] }
+            broadcasts_to ->(post) { "posts" }
           end
 
-          # In your controller:
-          @pulse_stream = Pulse::Streams::StreamName.signed_stream_name([Current.account, "posts"])
+          # 2. Pass stream token to frontend:
+          render inertia: "Post/Index", props: {
+            posts: @posts,
+            pulseStream: Pulse::Streams::StreamName.signed_stream_name("posts")
+          }
 
-          # In your React component:
+          # 3. Subscribe in React component:
           usePulse(pulseStream, (message) => {
-            router.reload({ only: ['posts'] })
+            switch (message.event) {
+              case 'created':
+                setPosts(prev => [message.payload, ...prev])
+                break
+              case 'updated':
+                setPosts(prev => 
+                  prev.map(post => post.id === message.payload.id ? message.payload : post)
+                )
+                break
+              case 'deleted':
+                setPosts(prev => prev.filter(post => post.id !== message.payload.id))
+                break
+              case 'refresh':
+                router.reload()
+                break
+            }
           })
         EXAMPLE
+        say "\nNext steps:", :yellow
+        say "1. Configure authentication in app/channels/application_cable/connection.rb"
+        say "2. Read docs/PULSE_USAGE.md for complete documentation"
+        say "3. Enable debug logging: localStorage.setItem('PULSE_DEBUG', 'true')"
+        say "\nInspired by Turbo Rails • Full ownership of generated code • Customize everything!"
       end
 
       private

data/lib/generators/pulse_zero/install/templates/docs/PULSE_USAGE.md.tt

@@ -1,110 +1,142 @@
-# Pulse Real-time Broadcasting Guide
+# Pulse Zero Usage Guide
 
-## Overview
+## What is Pulse Zero?
 
-Pulse is a real-time broadcasting system that keeps your UI in sync with database changes. It's designed for Inertia.js + React applications, broadcasting JSON messages through WebSockets.
+Pulse Zero generated a complete real-time broadcasting system directly into your Rails application. Unlike traditional gems, all code is now part of your project, giving you full ownership and the ability to customize everything.
 
-## Quick Start
-
-### 1. Enable Broadcasting on a Model
+Inspired by Turbo Rails, Pulse brings familiar broadcasting patterns to Inertia.js applications. If you've used `broadcasts_to` in Turbo Rails, you'll feel right at home with Pulse's API.
 
-Add `include Pulse::Broadcastable` to your model. You have two approaches:
+Features:
+- 🚀 WebSocket broadcasting via ActionCable
+- 🔒 Secure signed streams
+- 📱 Browser tab suspension handling
+- 🔄 Automatic reconnection with exponential backoff
+- 📦 TypeScript support for Inertia + React
+- 🎯 Zero runtime dependencies
+- 🏗️ Turbo Rails-inspired API design
 
-#### Option A: Direct Broadcasting (More Control)
-
-```ruby
-class Post < ApplicationRecord
-  include Pulse::Broadcastable
-
-  # Direct broadcasts with custom payloads
-  after_create_commit  -> { broadcast_created_later_to([account, "posts"], payload: to_inertia_json) }
-  after_update_commit  -> { broadcast_updated_later_to([account, "posts"], payload: to_inertia_json) }
-  after_destroy_commit -> { broadcast_deleted_to([account, "posts"], payload: { id: id.to_s }) }
-
-  private
-
-  def to_inertia_json
-    {
-      id: id,
-      content: content,
-      state: state,
-      created_at: created_at.iso8601,
-      # ... other fields
-    }
-  end
-end
-```
+## Quick Start
 
-#### Option B: DSL Broadcasting (Simpler)
+### 1. Enable Broadcasting on a Model
 
 ```ruby
 class Post < ApplicationRecord
   include Pulse::Broadcastable
-
-  # Broadcast to account-scoped channel
-  broadcasts_to ->(post) { [post.account, "posts"] }
-
-  # Or broadcast to a simple channel
-  broadcasts "posts"
+  
+  # Broadcast to a simple channel
+  broadcasts_to ->(post) { "posts" }
+  
+  # Or broadcast to account-scoped channel
+  # broadcasts_to ->(post) { [post.account, "posts"] }
 end
 ```
 
 ### 2. Pass Stream Token to Frontend
 
-In your controller, generate a signed stream token:
-
 ```ruby
 class PostsController < ApplicationController
   def index
-    @posts = Current.account.posts
-    @pulse_stream = Pulse::Streams::StreamName
-      .signed_stream_name([Current.account, "posts"])
+    @posts = Post.all
 
-    # The stream token is automatically available in your React component
+    render inertia: "Post/Index", props: {
+      posts: @posts.map do |post|
+        serialize_post(post)
+      end,
+      pulseStream: Pulse::Streams::StreamName.signed_stream_name("posts")
+    }
+  end
+  
+  private
+  
+  def serialize_post(post)
+    {
+      id: post.id,
+      title: post.title,
+      content: post.content,
+      created_at: post.created_at
+    }
   end
 end
 ```
 
-### 3. Subscribe in React Component
+**Why pulseStream?** Following Turbo Rails' security model, Pulse uses signed stream names to prevent unauthorized access to WebSocket channels. Since Inertia.js doesn't have a built-in way to access streams like Turbo does, we pass the signed stream name as a prop. This approach:
+- Maintains security through cryptographically signed tokens
+- Works naturally with Inertia's prop system
+- Keeps the API simple and explicit
 
-Use the `usePulse` hook to receive real-time updates:
+### 3. Subscribe in React Component
 
 ```tsx
+import { useState } from 'react'
 import { usePulse } from '@/hooks/use-pulse'
 import { useVisibilityRefresh } from '@/hooks/use-visibility-refresh'
 import { router } from '@inertiajs/react'
 
-export default function Posts({ posts, pulseStream }) {
-  // Handle tab visibility (refreshes data when returning to tab)
+interface IndexProps {
+  posts: Array<{
+    id: number
+    title: string
+    content: string
+    created_at: string
+  }>
+  pulseStream: string
+  flash: {
+    success?: string
+    error?: string
+  }
+}
+
+export default function Index({ posts: initialPosts, flash, pulseStream }: IndexProps) {
+  // Use local state for posts to enable real-time updates
+  const [posts, setPosts] = useState(initialPosts)
+  
+  // Automatically refresh data when returning to the tab after 30+ seconds
+  // This ensures users see fresh data after being away, handling cases where
+  // WebSocket messages might have been missed during browser suspension
   useVisibilityRefresh(30, () => {
     router.reload({ only: ['posts'] })
   })
 
-  // Subscribe to real-time updates
+  // Subscribe to Pulse updates for real-time changes
   usePulse(pulseStream, (message) => {
     switch (message.event) {
       case 'created':
+        // Add the new post to the beginning of the list
+        setPosts(prev => [message.payload, ...prev])
+        break
       case 'updated':
+        // Replace the updated post in the list
+        setPosts(prev => 
+          prev.map(post => post.id === message.payload.id ? message.payload : post)
+        )
+        break
       case 'deleted':
-        // Reload posts from server
-        router.reload({ only: ['posts'] })
+        // Remove the deleted post from the list
+        setPosts(prev => 
+          prev.filter(post => post.id !== message.payload.id)
+        )
         break
       case 'refresh':
-        // Full page refresh
+        // Full reload for refresh events
         router.reload()
         break
     }
   })
-
+  
   return (
-    <div>
-      {posts.map(post => <PostCard key={post.id} post={post} />)}
-    </div>
+    <>
+      {flash.success && <div className="alert-success">{flash.success}</div>}
+      <PostsList posts={posts} />
+    </>
   )
 }
 ```
 
-## Message Events
+**Note:** This example shows optimistic UI updates using local state. Alternatively, you can use `router.reload({ only: ['posts'] })` for all events to fetch fresh data from the server, which ensures consistency but may feel less responsive.
+
+**Why useVisibilityRefresh?** When users switch tabs or minimize their browser, WebSocket connections can be suspended and messages may be lost. The `useVisibilityRefresh` hook detects when users return to your app and automatically refreshes the data if they've been away for more than the specified threshold (30 seconds in this example). This ensures users always see up-to-date information without manual refreshing.
+
+## Broadcasting Events
 
 Pulse broadcasts four types of events:
 
@@ -112,7 +144,7 @@ Pulse broadcasts four types of events:
 ```json
 {
   "event": "created",
-  "payload": { "id": 123, "content": "New post", ... },
+  "payload": { "id": 123, "content": "New post" },
   "requestId": "uuid-123",
   "at": 1234567890.123
 }
@@ -122,7 +154,7 @@ Pulse broadcasts four types of events:
 ```json
 {
   "event": "updated",
-  "payload": { "id": 123, "content": "Updated post", ... },
+  "payload": { "id": 123, "content": "Updated post" },
   "requestId": "uuid-456",
   "at": 1234567891.456
 }
@@ -148,90 +180,155 @@ Pulse broadcasts four types of events:
 }
 ```
 
-## Common Patterns
-
-### Scoped Broadcasting
+## Advanced Usage
 
-Always scope broadcasts to prevent users from seeing each other's data:
+### Manual Broadcasting
 
 ```ruby
-class Comment < ApplicationRecord
-  include Pulse::Broadcastable
+# Broadcast with custom payload
+post.broadcast_updated_to(
+  [Current.account, "posts"],
+  payload: { id: post.id, featured: true }
+)
+
+# Async broadcasting
+post.broadcast_updated_later_to([Current.account, "posts"])
+```
 
-  belongs_to :post
-  belongs_to :user
+### Suppress Broadcasts During Bulk Operations
 
-  # Scope to the post's account and specific post
-  broadcasts_to ->(comment) { [comment.post.account, "posts", comment.post_id, "comments"] }
+```ruby
+Post.suppressing_pulse_broadcasts do
+  Post.where(account: account).update_all(featured: true)
 end
+
+# Then send one refresh broadcast
+Post.new.broadcast_refresh_to([account, "posts"])
 ```
 
-### Manual Broadcasting
+### Custom Serialization
+
+```ruby
+# config/initializers/pulse.rb
+Rails.application.configure do
+  config.pulse.serializer = ->(record) {
+    case record
+    when Post
+      record.as_json(only: [:id, :title, :state])
+    else
+      record.as_json
+    end
+  }
+end
+```
 
-Sometimes you need to broadcast manually:
+## Configuration
 
 ```ruby
-class PostsController < ApplicationController
-  def approve
-    @post = Post.find(params[:id])
-    @post.approve!
-
-    # Manual broadcast with custom payload
-    @post.broadcast_updated_to(
-      [Current.account, "posts"],
-      payload: { id: @post.id, approved: true }
-    )
-  end
+# config/initializers/pulse.rb
+Rails.application.configure do
+  # Debounce window in milliseconds (default: 300)
+  config.pulse.debounce_ms = 300
+  
+  # Background job queue (default: :default)
+  config.pulse.queue_name = :low
+  
+  # Custom serializer
+  config.pulse.serializer = ->(record) { record.as_json }
 end
 ```
 
-### Bulk Operations
+## Browser Tab Handling
+
+Pulse includes sophisticated handling for browser tab suspension:
+
+- **Quick switches (<30s)**: Just ensures connection is alive
+- **Medium absence (30s-5min)**: Reconnects and syncs data
+- **Long absence (>5min)**: Full page refresh for consistency
 
-Suppress broadcasts during bulk operations to avoid flooding:
+Platform-aware thresholds:
+- Desktop Chrome/Firefox: 30 seconds
+- Safari/Mobile: 15 seconds (more aggressive)
+
+## Testing
 
 ```ruby
-# Bad - sends 1000 broadcasts
-Post.where(account: account).update_all(featured: true)
+# In your test files
+test "broadcasts on update" do
+  post = posts(:one)
+  
+  assert_broadcast_on([post.account, "posts"]) do
+    post.update!(title: "New Title")
+  end
+end
 
-# Good - suppresses broadcasts
+# Suppress broadcasts in tests
 Post.suppressing_pulse_broadcasts do
-  Post.where(account: account).update_all(featured: true)
+  # Your test code
 end
+```
 
-# Then send one refresh broadcast
-Post.new.broadcast_refresh_to([account, "posts"])
+## Debugging
+
+Enable debug logging:
+
+```javascript
+// In browser console
+localStorage.setItem('PULSE_DEBUG', 'true')
 ```
 
-### Async Broadcasting
+Check connection health:
 
-For non-critical updates or heavy operations, use async broadcasting:
+```javascript
+import { getPulseMonitorStats } from '@/lib/pulse-connection'
+
+const stats = getPulseMonitorStats()
+console.log(stats)
+```
+
+## Common Patterns
+
+### Scoped Broadcasting
+
+Always scope broadcasts to prevent users from seeing each other's data:
 
 ```ruby
-class ProcessHeavyDataJob < ApplicationJob
-  def perform(post)
-    # Do heavy processing...
-    result = process_data(post)
-
-    # Broadcast asynchronously (via job queue)
-    post.broadcast_updated_later_to(
-      [post.account, "posts"],
-      payload: { id: post.id, processing_complete: true, result: result }
-    )
-  end
+class Comment < ApplicationRecord
+  include Pulse::Broadcastable
+
+  belongs_to :post
+  belongs_to :user
+
+  # Scope to the post's account and specific post
+  broadcasts_to ->(comment) { [comment.post.account, "posts", comment.post_id, "comments"] }
 end
 ```
 
-## Frontend Patterns
+### Direct Broadcasting (More Control)
 
-### Simple Reload
+For more control over what gets broadcast:
 
-The simplest approach - just reload the data:
+```ruby
+class Post < ApplicationRecord
+  include Pulse::Broadcastable
 
-```tsx
-usePulse(pulseStream, (message) => {
-  // Reload posts array from server
-  router.reload({ only: ['posts'] })
-})
+  # Direct broadcasts with custom payloads
+  after_create_commit  -> { broadcast_created_later_to([account, "posts"], payload: to_inertia_json) }
+  after_update_commit  -> { broadcast_updated_later_to([account, "posts"], payload: to_inertia_json) }
+  after_destroy_commit -> { broadcast_deleted_to([account, "posts"], payload: { id: id.to_s }) }
+
+  private
+
+  def to_inertia_json
+    {
+      id: id,
+      title: title,
+      content: content,
+      state: state,
+      created_at: created_at.iso8601
+    }
+  end
+end
 ```
 
 ### Optimistic Updates
@@ -247,7 +344,7 @@ export default function PostsList({ posts: initialPosts, pulseStream }) {
   usePulse(pulseStream, (message) => {
     switch (message.event) {
       case 'created':
-        setPosts(prev => [...prev, message.payload])
+        setPosts(prev => [message.payload, ...prev])
         break
       case 'updated':
         setPosts(prev => prev.map(post =>
@@ -291,160 +388,6 @@ usePulse(pulseStream, (message) => {
 })
 ```
 
-## Browser Tab Handling
-
-Pulse includes sophisticated handling for browser tab suspension. Modern browsers suspend WebSocket connections in background tabs to save battery.
-
-### Automatic Recovery
-
-Use the `useVisibilityRefresh` hook to handle tab suspension:
-
-```tsx
-// Default: refresh after 30 seconds hidden
-useVisibilityRefresh(30, () => {
-  router.reload({ only: ['posts'] })
-})
-
-// Aggressive: refresh after 15 seconds (for critical data)
-useVisibilityRefresh(15, () => {
-  router.reload()
-})
-
-// Relaxed: refresh after 2 minutes
-useVisibilityRefresh(120, () => {
-  router.reload({ only: ['posts'] })
-})
-```
-
-### Platform-Specific Behavior
-
-- **Desktop Chrome/Firefox**: 30 second default threshold
-- **Safari/Mobile**: 15 second default (more aggressive suspension)
-
-## Configuration
-
-### Debounce Window
-
-Adjust how long Pulse waits to coalesce rapid updates:
-
-```ruby
-# config/initializers/pulse.rb
-Rails.application.configure do
-  # Default is 300ms
-  config.pulse.debounce_ms = 500
-end
-```
-
-### Job Queue
-
-Configure which queue processes async broadcasts:
-
-```ruby
-Rails.application.configure do
-  # Use low priority queue for broadcasts
-  config.pulse.queue_name = :low
-end
-```
-
-### Custom Serialization
-
-Control what data is sent in broadcasts:
-
-```ruby
-# config/initializers/pulse.rb
-Rails.application.configure do
-  config.pulse.serializer = ->(record) {
-    case record
-    when Post
-      {
-        id: record.id,
-        title: record.title,
-        state: record.state,
-        author: record.user.name,
-        updatedAt: record.updated_at.iso8601
-      }
-    when Comment
-      {
-        id: record.id,
-        content: record.content.truncate(100),
-        authorAvatar: record.user.avatar_url
-      }
-    else
-      record.as_json
-    end
-  }
-end
-```
-
-## Testing
-
-### Testing Model Broadcasts
-
-```ruby
-class PostTest < ActiveSupport::TestCase
-  test "broadcasts when published" do
-    post = posts(:draft)
-    account = accounts(:one)
-
-    # Create the expected stream name
-    stream = Pulse::Streams::StreamName.signed_stream_name([account, "posts"])
-
-    # Assert broadcast happens
-    assert_broadcast_on(stream) do
-      post.publish!
-    end
-  end
-
-  test "suppresses broadcasts in bulk operations" do
-    Post.suppressing_pulse_broadcasts do
-      # No broadcasts should happen here
-      Post.import(large_dataset)
-    end
-  end
-end
-```
-
-### Disable in Tests
-
-Broadcasts are automatically disabled in the test environment via:
-
-```ruby
-# config/initializers/pulse.rb
-if Rails.env.test?
-  ENV["PULSE_DISABLED"] = "true"
-end
-```
-
-## Debugging
-
-Enable debug logging:
-
-```javascript
-// In browser console
-localStorage.setItem('PULSE_DEBUG', 'true')
-
-// Now you'll see logs like:
-// [Pulse] Subscription connected: posts:123
-// [Pulse] Message received: {event: "updated", ...}
-// [Pulse] Connection lost, retrying in 2s...
-```
-
-Check connection health:
-
-```javascript
-import { getPulseMonitorStats } from '@/lib/pulse/pulse-connection'
-
-const stats = getPulseMonitorStats()
-console.log(stats)
-// {
-//   isRunning: true,
-//   isConnecting: false,
-//   reconnectAttempts: 0,
-//   secondsSinceActivity: 2.5,
-//   secondsSinceMessage: 5.1
-// }
-```
-
 ## Security Notes
 
 1. **Always use scoped streams** - Never broadcast to global channels
@@ -453,24 +396,6 @@ console.log(stats)
 4. **Sanitize payloads** - Don't include sensitive data in broadcasts
 5. **Use SSL in production** - WebSockets should run over WSS
 
-## Common Issues
-
-### Not receiving updates
-- Check WebSocket connection in Network tab
-- Verify stream name matches between backend and frontend
-- Ensure ActionCable is mounted in routes.rb
-- Check for authorization failures in Rails logs
-
-### Too many updates
-- Use debouncing (automatic within 300ms)
-- Implement conditional broadcasting
-- Use `suppressing_pulse_broadcasts` for bulk operations
-
-### Connection drops
-- Pulse automatically reconnects with exponential backoff
-- Check for SSL/proxy issues in production
-- Monitor server logs for WebSocket errors
-
 ## Authentication Setup
 
 By default, Pulse accepts all WebSocket connections in development. You need to configure authentication based on your setup:
@@ -523,10 +448,38 @@ rescue JWT::DecodeError
 end
 ```
 
+## Common Issues
+
+### Not receiving updates
+- Check WebSocket connection in Network tab
+- Verify stream name matches between backend and frontend
+- Ensure ActionCable is mounted in routes.rb
+- Check for authorization failures in Rails logs
+
+### Too many updates
+- Use debouncing (automatic within 300ms)
+- Implement conditional broadcasting
+- Use `suppressing_pulse_broadcasts` for bulk operations
+
+### Connection drops
+- Pulse automatically reconnects with exponential backoff
+- Check for SSL/proxy issues in production
+- Monitor server logs for WebSocket errors
+
+## Philosophy
+
+Pulse Zero follows the same philosophy as [authentication-zero](https://github.com/lazaronixon/authentication-zero), and is heavily inspired by [Turbo Rails](https://github.com/hotwired/turbo-rails). The API design closely mirrors Turbo Rails patterns, making it intuitive for developers already familiar with the Hotwire ecosystem.
+
+- **Own your code**: All code is generated into your project
+- **No runtime dependencies**: The gem is only needed during generation
+- **Customizable**: Modify any generated code to fit your needs
+- **Production-ready**: Includes battle-tested patterns from real applications
+- **Familiar API**: Inspired by Turbo Rails, uses similar broadcasting patterns and conventions
+
 ## Next Steps
 
 - Configure authentication in `app/channels/application_cable/connection.rb`
 - Try the example in a model: `include Pulse::Broadcastable`
 - Set up your first broadcast stream
 - Customize the serializer for your needs
-- Read about advanced patterns in the main documentation
+- Read about advanced patterns in the main documentation

data/lib/pulse_zero/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PulseZero
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pulse_zero
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - darkamenosa