livereload-morph 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,27 @@
 # livereload-morph
 
-A livereload-js replacement that uses **idiomorph** for intelligent DOM morphing. Instead of full page reloads, livereload-morph preserves page state by morphing HTML changes directly into the DOM.
+A drop-in replacement for [livereload-js](https://github.com/livereload/livereload-js) that uses **idiomorph** for intelligent DOM morphing. Instead of full page reloads, livereload-morph preserves page state by morphing HTML changes directly into the DOM.
+
+## What is LiveReload?
+
+LiveReload watches your files and automatically refreshes your browser when you save changes. To use it, you need:
+
+1. A **LiveReload server** running on your development machine (see list below)
+2. A **client script** (this library) loaded in your browser
+
+This library implements an enhanced client that morphs HTML changes instead of doing full page reloads.
+
+## Compatible Servers
+
+livereload-morph works with any LiveReload Protocol 7 compatible server:
+- [html-compose](https://github.com/jealouscloud/html-comose) (Python)
+- [guard-livereload](https://github.com/guard/guard-livereload) (Ruby)
+- [python-livereload](https://github.com/lepture/python-livereload)
+- [livereload](https://www.npmjs.com/package/livereload) (Node.js)
+- [browser-sync](https://browsersync.io/)
+- [grunt-contrib-watch](https://github.com/gruntjs/grunt-contrib-watch)
+- [LiveReload app for Mac](http://livereload.com/)
+- Any server implementing the [LiveReload protocol](http://livereload.com/api/protocol/)
 
 ## Features
 
@@ -12,46 +33,31 @@ A livereload-js replacement that uses **idiomorph** for intelligent DOM morphing
 
 - **CSS Live Reload**: CSS changes update without flash using clone-and-replace strategy
 
-- **LiveReload Protocol 7 Compatible**: Works with existing LiveReload servers (guard-livereload, browser-sync, etc.)
-
 - **Minimal & Fast**: Small bundle (includes idiomorph), vanilla JavaScript, no dependencies
 
-## Quick Start
+## Usage
 
-### Installation
+Add to your HTML page:
 
-```bash
-bun install
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/livereload-morph@latest/dist/livereload-morph.min.js?host=localhost"></script>
 ```
 
-### Build
+You can also download and serve the script locally, or install via npm:
 
 ```bash
-bun run build
+npm install livereload-morph
 ```
 
-### Testing
+### Configuration
 
-Start the test server with LiveReload:
+Configure via query string parameters:
 
-```bash
-bun run test
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/livereload-morph@latest/dist/livereload-morph.min.js?host=localhost&verbose=true"></script>
 ```
 
-Then open http://localhost:3000/test/ in your browser.
-
-**Test HTML Morphing:**
-1. Type in the input field
-2. Edit `test/index.html` (change text, add elements, etc.)
-3. Watch the page update without losing your input!
-
-**Test CSS Reload:**
-1. Edit `test/styles.css` (change `.color-box` background color)
-2. Watch styles update with no flash
-
-## Usage
-
-Add to your HTML page:
+Or via global options:
 
 ```html
 <script type="module">
@@ -62,16 +68,39 @@ Add to your HTML page:
     morphHTML: true     // Enable HTML morphing (default: true)
   };
 </script>
-<script type="module" src="http://localhost:35729/livereload-morph.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/livereload-morph@latest/dist/livereload-morph.min.js"></script>
 ```
 
-Or use query string parameters:
+## vs livereload-js
 
-```html
-<script type="module" src="http://localhost:35729/livereload-morph.js?host=localhost&verbose=true"></script>
-```
+| Feature | livereload-morph | livereload-js |
+|---------|------------------|---------------|
+| HTML updates | Morph (preserves state) | Full reload |
+| CSS updates | Clone-replace | Clone-replace |
+| Input state | Preserved | Lost on reload |
+| Scroll position | Preserved | Lost on reload |
+| Focus state | Preserved | Lost on reload |
 
-## Configuration Options
+## How It Works
+
+When a file changes:
+
+- **CSS files** → Clone-and-replace for `<link>` tags, CSSOM rule replacement for `@import`
+- **Images** → Cache-bust `<img>` src and CSS backgrounds
+- **JavaScript** → Full page reload (no safe hot-reload)
+- **Everything else** → Re-fetch page HTML and morph with idiomorph
+
+### State Preservation
+
+The following is preserved automatically during HTML morphs:
+- Input values (text, textarea, select)
+- Checkbox/radio checked state
+- `<details>` open/closed state
+- Scroll position
+
+For best results, add IDs to form elements. Without IDs, idiomorph may recreate elements instead of morphing them.
+
+## All Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
@@ -81,80 +110,32 @@ Or use query string parameters:
 | `https` | boolean | false | Use secure WebSocket (wss://) |
 | `morphHTML` | boolean | true | Enable HTML morphing |
 | `verbose` | boolean | false | Enable console logging |
-| `importCacheWaitPeriod` | number | 200 | Enable legacy WebKit @import workaround. Set to any value > 0 to enable, 0 to disable |
+| `importCacheWaitPeriod` | number | 200 | Legacy WebKit @import workaround delay. Set to 0 to disable |
 | `mindelay` | number | 1000 | Min reconnection delay (ms) |
 | `maxdelay` | number | 60000 | Max reconnection delay (ms) |
 | `handshake_timeout` | number | 5000 | Handshake timeout (ms) |
 
-## How It Works
-
-1. **WebSocket Connection**: Connects to LiveReload server on port 35729
-2. **File Change Detection**: Server sends `reload` command with changed file path
-3. **Smart Routing**:
-   - `.css` / `.css.map` files → Clone-and-replace for `<link>` tags, CSSOM rule replacement for `@import`
-   - Images (`.jpg`, `.png`, `.gif`, `.svg`, `.webp`, `.ico`) → Cache-bust `<img>` src and CSS backgrounds
-   - `.js` / `.mjs` files → Full page reload (no safe hot-reload)
-   - Everything else → Morph with idiomorph (re-fetches page HTML)
-4. **State Preservation**: idiomorph intelligently merges changes while preserving DOM state
-
-### CSS Reload Details
-
-Live-morph supports both `<link>` tags and `@import` rules:
+## Browser Support
 
-- **`<link>` tags**: Clone with cache-busted URL, wait for load, remove original (prevents FOUC)
-- **`@import` rules**: Replace rule in CSSOM with cache-busted URL
-  - By default uses legacy WebKit workaround (pre-cache with temp `<link>` tag to trigger browser fetch)
-  - Prevents flicker when updating `@import` rules (still needed in modern browsers!)
-  - Set `importCacheWaitPeriod: 0` to disable workaround (will cause brief flicker)
-- **Cross-origin CSS**: CORS-protected stylesheets are handled gracefully (can't inspect `@import` rules)
+Modern browsers with ES6+ support (Chrome/Edge 60+, Firefox 60+, Safari 12+).
 
-## State Preservation
+## License
 
-**What's preserved automatically:**
-- Input values (text, textarea, select)
-- Checkbox/radio checked state
-- `<details>` open/closed state
+MIT
 
-**For best results, add IDs to form elements.** Without IDs, idiomorph may recreate elements instead of morphing them, which can lose state in edge cases.
+## Credits
 
-## vs livereload-js
+- [idiomorph](https://github.com/bigskysoftware/idiomorph) for DOM morphing
+- [LiveReload Protocol 7](https://github.com/livereload/livereload-js)
 
-| Feature | livereload-morph | livereload-js |
-|---------|------------------|---------------|
-| HTML updates | ✅ Morph (preserves state) | ❌ Full reload |
-| CSS updates | ✅ Clone-replace | ✅ Clone-replace |
-| Input state | ✅ Preserved | ❌ Lost on reload |
-| Scroll position | ✅ Preserved | ❌ Lost on reload |
-| Focus state | ✅ Preserved | ❌ Lost on reload |
+---
 
-## Development
+## Contributing
 
 ```bash
-# Build once
-bun run build
-
-# Build and watch for changes
-bun run build:watch
-
-# Run test server (builds + starts server)
-bun run test
-
-# Development mode (watch build + server)
-bun run dev
+bun install        # Install dependencies
+bun run build      # Build once
+bun run dev        # Watch mode + test server
+bun run test       # Run test server
+bun run test:e2e   # Run playwright tests
 ```
-
-## Browser Support
-
-Modern browsers with ES6+ support:
-- Chrome/Edge 60+
-- Firefox 60+
-- Safari 12+
-
-## License
-
-MIT
-
-## Credits
-
-- Built with [idiomorph](https://github.com/bigskysoftware/idiomorph) for DOM morphing
-- Compatible with [LiveReload Protocol 7](github.com/livereload/livereload-js)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livereload-morph",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A livereload-js replacement using idiomorph for intelligent DOM morphing",
   "author": "Noah A.",
   "license": "MIT",
@@ -24,6 +24,12 @@
   "module": "dist/livereload-morph.js",
   "main": "dist/livereload-morph.cjs",
   "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/livereload-morph.js",
+      "require": "./dist/livereload-morph.cjs"
+    }
+  },
   "files": ["dist", "LICENSE"],
   "scripts": {
     "build": "bun build src/index.js --outfile dist/livereload-morph.js --target browser --format esm && bun build src/index.js --outfile dist/livereload-morph.min.js --target browser --format esm --minify && bun build src/index.js --outfile dist/livereload-morph.cjs --target browser --format cjs",