lively 0.12.0 → 0.13.1

data/public/_components/@socketry/live/readme.md

@@ -1,58 +1,174 @@
-# Live (JavaScript)
+# Live.js
 
-This is the JavaScript library for implementing the Ruby gem of the same name.
+A JavaScript client library for building interactive web applications with Ruby Live framework.
 
-## Document Manipulation
+[![Development Status](https://github.com/socketry/live-js/workflows/Test/badge.svg)](https://github.com/socketry/live-js/actions?workflow=Test)
 
-### `live.update(id, html, options)`
+## Features
 
-Updates the content of the element with the given `id` with the given `html`. The `options` parameter is optional and can be used to pass additional options to the update method.
+- **Real-time Communication**: WebSocket-based client-server communication.
+- **DOM Manipulation**: Efficient updating, replacing, and modifying HTML elements.
+- **Event Forwarding**: Forward client events to server for processing.
+- **Controller Loading**: Declarative JavaScript controller loading with `data-live-controller`.
+- **Automatic Cleanup**: Proper lifecycle management and memory cleanup.
+- **Live Elements**: Automatic binding and unbinding of live elements.
 
-- `options.reply` - If truthy, the server will reply with `{reply: options.reply}`.
+## Usage
 
-### `live.replace(selector, html, options)`
+### Installation
 
-Replaces the element(s) selected by the given `selector` with the given `html`. The `options` parameter is optional and can be used to pass additional options to the replace method.
+```bash
+npm install @socketry/live
+```
 
-- `options.reply` - If truthy, the server will reply with `{reply: options.reply}`.
+### Basic Setup
 
-### `live.prepend(selector, html, options)`
+```javascript
+import { Live } from '@socketry/live';
 
-Prepends the given `html` to the element(s) selected by the given `selector`. The `options` parameter is optional and can be used to pass additional options to the prepend method.
+// Start the live connection
+const live = Live.start({
+  path: 'live',  // WebSocket endpoint
+  base: window.location.href
+});
+```
 
-- `options.reply` - If truthy, the server will reply with `{reply: options.reply}`.
+### Controller Loading
 
-### `live.append(selector, html, options)`
+Live.js supports declarative controller loading using the `data-live-controller` attribute:
 
-Appends the given `html` to the element(s) selected by the given `selector`. The `options` parameter is optional and can be used to pass additional options to the append method.
+```html
+<div class="live" id="game" data-live-controller="/static/game_controller.mjs">
+  <!-- Game content -->
+</div>
+```
 
-- `options.reply` - If truthy, the server will reply with `{reply: options.reply}`.
+```javascript
+// game_controller.mjs
+export default function(element) {
+  console.log('Controller loaded for:', element);
+  
+  // Setup your controller logic
+  element.addEventListener('click', handleClick);
+  
+  // Return a controller object with cleanup
+  return {
+    dispose() {
+      element.removeEventListener('click', handleClick);
+    }
+  };
+}
+```
 
-### `live.remove(selector, options)`
+## API Reference
 
-Removes the element(s) selected by the given `selector`. The `options` parameter is optional and can be used to pass additional options to the remove method.
+### Live Class
 
-- `options.reply` - If truthy, the server will reply with `{reply: options.reply}`.
+#### Static Methods
 
-### `live.dispatchEvent(selector, type, options)`
+- `Live.start(options)` - Create and start a new Live instance
+  - `options.window` - Window object (defaults to globalThis)
+  - `options.path` - WebSocket path (defaults to 'live')
+  - `options.base` - Base URL (defaults to window.location.href)
 
-Dispatches an event of the given `type` on the element(s) selected by the given `selector`. The `options` parameter is optional and can be used to pass additional options to the dispatchEvent method.
+#### Instance Methods
 
-- `options.detail` - The detail object to pass to the event.
-- `options.bubbles` - A boolean indicating whether the event should bubble up through the DOM.
-- `options.cancelable` - A boolean indicating whether the event can be canceled.
-- `options.composed` - A boolean indicating whether the event will trigger listeners outside of a shadow root.
+##### Connection Management
+- `connect()` - Establish WebSocket connection
+- `disconnect()` - Close WebSocket connection
 
-## Event Handling
+##### DOM Manipulation
+- `update(id, html, options)` - Update element content
+- `replace(selector, html, options)` - Replace elements
+- `prepend(selector, html, options)` - Prepend content
+- `append(selector, html, options)` - Append content  
+- `remove(selector, options)` - Remove elements
 
-### `live.forward(id, event)`
+##### Event Handling
+- `forward(id, event)` - Forward event to server
+- `forwardEvent(id, event, detail, preventDefault)` - Forward DOM event
+- `forwardFormEvent(id, event, detail, preventDefault)` - Forward form event
 
-Connect and forward an event on the element with the given `id`. If the connection can't be established, the event will be buffered.
+##### Script Execution
+- `script(id, code, options)` - Execute JavaScript code
+- `loadController(id, path, options)` - Load JavaScript controller
 
-### `live.forwardEvent(id, event, details)`
+##### Event Dispatching
+- `dispatchEvent(selector, type, options)` - Dispatch custom events
 
-Forward a HTML DOM event to the server. The `details` parameter is optional and can be used to pass additional details to the server.
+### Options Parameter
 
-### `live.forwardFormEvent(id, event, details)`
+Most methods accept an `options` parameter with:
+- `options.reply` - If truthy, server will reply with `{reply: options.reply}`
 
-Forward an event which has form data to the server. The `details` parameter is optional and can be used to pass additional details to the server.
+### Controller Pattern
+
+Controllers are JavaScript modules that manage view-specific behavior:
+
+```javascript
+// Simple controller
+export default function(element) {
+  // Setup code
+  return {
+    dispose() {
+      // Cleanup code
+    }
+  };
+}
+
+// With options
+export default function(element, options) {
+  const config = options.config || {};
+  // Use config...
+}
+```
+
+## Live Elements
+
+Elements with the `live` CSS class are automatically managed:
+
+```html
+<div class="live" id="my-element">
+  Content that can be updated
+</div>
+```
+
+## Event Examples
+
+### Basic Event Forwarding
+
+```javascript
+// Forward click events
+element.addEventListener('click', (event) => {
+  live.forwardEvent('my-element', event, { button: 'clicked' });
+});
+
+// Forward form submissions
+form.addEventListener('submit', (event) => {
+  live.forwardFormEvent('my-form', event, { action: 'submit' });
+});
+```
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
+
+## See Also
+
+  - [lively](https://github.com/socketry/lively) — Ruby framework for building interactive web applications.
+  - [live](https://github.com/socketry/live) — Provides client-server communication using websockets.
+  - [live-audio-js](https://github.com/socketry/live-audio-js) — Web Audio API-based game audio synthesis library.

data/public/_components/@socketry/live-audio/Live/Audio/Controller.js

@@ -0,0 +1,168 @@
+// Audio Controller - manages sound instances and provides unified API
+import { Output } from './Output.js';
+import { Sound } from './Sound.js';
+
+// Get or create shared AudioContext (keyed by window)
+async function getSharedAudioContext(window = globalThis) {
+	const contextKey = '_liveAudioContext';
+	
+	let audioContext = window[contextKey];
+	
+	if (!audioContext || audioContext.state === 'closed') {
+		audioContext = new (window.AudioContext || window.webkitAudioContext)({
+			latencyHint: 'interactive',
+		});
+		
+		if (audioContext.state === 'suspended') {
+			await audioContext.resume();
+		}
+		
+		window[contextKey] = audioContext;
+		
+		console.log(`Live Audio Context created - Sample rate: ${audioContext.sampleRate}Hz, State: ${audioContext.state}`);
+	}
+	
+	return audioContext;
+}
+
+export class Controller {
+	#window = null;
+	#audioContext = null;
+	#output = null;
+	#sounds = {};
+	#volume = 1.0;
+	
+	// Callbacks:
+	#onOutputCreated = null;
+	#onOutputDisposed = null;
+	
+	constructor(window = globalThis, options = {}) {
+		this.#window = window;
+		this.#onOutputCreated = options.onOutputCreated || null;
+		this.#onOutputDisposed = options.onOutputDisposed || null;
+	}
+	
+	// Acquire output with AudioContext ready - returns null if not available.
+	async acquireOutput() {
+		let output = this.#output;
+		
+		if (!output) {
+			// First get the AudioContext at Controller level
+			const audioContext = await getSharedAudioContext(this.#window);
+			if (!audioContext) return null;
+			
+			// Then create Output instance with AudioContext:
+			this.#output = output = new Output(audioContext);
+			
+			// Apply the controller's volume to the new output
+			output.setVolume(this.#volume);
+			
+			// Call the output created callback if provided
+			if (this.#onOutputCreated) {
+				this.#onOutputCreated(this, output);
+			}
+		}
+		
+		return output;
+	}
+	
+	// Add a sound to this controller instance
+	addSound(name, value) {
+		this.#sounds[name] = value;
+		return value;
+	}
+	
+	// Play a sound by name
+	async playSound(name) {
+		// Return early if volume is zero (muted)
+		if (this.#volume <= 0) return;
+		
+		const sound = this.#sounds[name];
+		if (sound) {
+			const output = await this.acquireOutput();
+			if (!output) return;
+			sound.play(output);
+		} else {
+			console.warn(`Sound '${name}' not found`);
+		}
+	}
+	
+	// Stop a sound by name
+	stopSound(name) {
+		const sound = this.#sounds[name];
+		if (sound) {
+			sound.stop();
+		} else {
+			console.warn(`Sound '${name}' not found`);
+		}
+	}
+	
+	// Stop all sounds
+	stopAllSounds() {
+		if (this.#sounds) {
+			Object.values(this.#sounds).forEach(sound => sound.stop());
+		}
+	}
+	
+	// Get a sound instance for direct access
+	getSound(name) {
+		return this.#sounds[name];
+	}
+	
+	// List all available sound names
+	listSounds() {
+		return Object.keys(this.#sounds);
+	}
+	
+	// Remove a sound
+	removeSound(name) {
+		if (this.#sounds[name]) {
+			delete this.#sounds[name];
+			return true;
+		}
+		return false;
+	}
+	
+	// Set master volume
+	async setVolume(volume) {
+		this.#volume = volume;
+		
+		// Apply to output if it exists, or acquire it
+		const output = await this.acquireOutput();
+		if (output) {
+			output.setVolume(volume);
+		}
+	}
+	
+	// Get current volume
+	get volume() {
+		return this.#volume;
+	}
+	
+	// Get sounds object (for testing)
+	get sounds() {
+		return this.#sounds;
+	}
+	
+	// Get window object (for testing)
+	get window() {
+		return this.#window;
+	}
+	
+	// Dispose of the controller and clean up resources
+	dispose() {
+		if (this.#output) {
+			const output = this.#output;
+			
+			// Call the disposal callback if provided
+			if (this.#onOutputDisposed) {
+				this.#onOutputDisposed(this, output);
+			}
+			
+			output.dispose();
+			this.#output = null;
+		}
+		
+		this.#sounds = {};
+	}
+}