livereload-morph 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +77 -96
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,27 @@
1
1
  # livereload-morph
2
2
 
3
- 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.
3
+ 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.
4
+
5
+ ## What is LiveReload?
6
+
7
+ LiveReload watches your files and automatically refreshes your browser when you save changes. To use it, you need:
8
+
9
+ 1. A **LiveReload server** running on your development machine (see list below)
10
+ 2. A **client script** (this library) loaded in your browser
11
+
12
+ This library implements an enhanced client that morphs HTML changes instead of doing full page reloads.
13
+
14
+ ## Compatible Servers
15
+
16
+ livereload-morph works with any LiveReload Protocol 7 compatible server:
17
+ - [html-compose](https://github.com/jealouscloud/html-comose) (Python)
18
+ - [guard-livereload](https://github.com/guard/guard-livereload) (Ruby)
19
+ - [python-livereload](https://github.com/lepture/python-livereload)
20
+ - [livereload](https://www.npmjs.com/package/livereload) (Node.js)
21
+ - [browser-sync](https://browsersync.io/)
22
+ - [grunt-contrib-watch](https://github.com/gruntjs/grunt-contrib-watch)
23
+ - [LiveReload app for Mac](http://livereload.com/)
24
+ - Any server implementing the [LiveReload protocol](http://livereload.com/api/protocol/)
4
25
 
5
26
  ## Features
6
27
 
@@ -12,46 +33,31 @@ A livereload-js replacement that uses **idiomorph** for intelligent DOM morphing
12
33
 
13
34
  - **CSS Live Reload**: CSS changes update without flash using clone-and-replace strategy
14
35
 
15
- - **LiveReload Protocol 7 Compatible**: Works with existing LiveReload servers (guard-livereload, browser-sync, etc.)
16
-
17
36
  - **Minimal & Fast**: Small bundle (includes idiomorph), vanilla JavaScript, no dependencies
18
37
 
19
- ## Quick Start
38
+ ## Usage
20
39
 
21
- ### Installation
40
+ Add to your HTML page:
22
41
 
23
- ```bash
24
- bun install
42
+ ```html
43
+ <script type="module" src="https://cdn.jsdelivr.net/npm/livereload-morph@latest/dist/livereload-morph.min.js?host=localhost"></script>
25
44
  ```
26
45
 
27
- ### Build
46
+ You can also download and serve the script locally, or install via npm:
28
47
 
29
48
  ```bash
30
- bun run build
49
+ npm install livereload-morph
31
50
  ```
32
51
 
33
- ### Testing
52
+ ### Configuration
34
53
 
35
- Start the test server with LiveReload:
54
+ Configure via query string parameters:
36
55
 
37
- ```bash
38
- bun run test
56
+ ```html
57
+ <script type="module" src="https://cdn.jsdelivr.net/npm/livereload-morph@latest/dist/livereload-morph.min.js?host=localhost&verbose=true"></script>
39
58
  ```
40
59
 
41
- Then open http://localhost:3000/test/ in your browser.
42
-
43
- **Test HTML Morphing:**
44
- 1. Type in the input field
45
- 2. Edit `test/index.html` (change text, add elements, etc.)
46
- 3. Watch the page update without losing your input!
47
-
48
- **Test CSS Reload:**
49
- 1. Edit `test/styles.css` (change `.color-box` background color)
50
- 2. Watch styles update with no flash
51
-
52
- ## Usage
53
-
54
- Add to your HTML page:
60
+ Or via global options:
55
61
 
56
62
  ```html
57
63
  <script type="module">
@@ -62,16 +68,39 @@ Add to your HTML page:
62
68
  morphHTML: true // Enable HTML morphing (default: true)
63
69
  };
64
70
  </script>
65
- <script type="module" src="http://localhost:35729/livereload-morph.js"></script>
71
+ <script type="module" src="https://cdn.jsdelivr.net/npm/livereload-morph@latest/dist/livereload-morph.min.js"></script>
66
72
  ```
67
73
 
68
- Or use query string parameters:
74
+ ## vs livereload-js
69
75
 
70
- ```html
71
- <script type="module" src="http://localhost:35729/livereload-morph.js?host=localhost&verbose=true"></script>
72
- ```
76
+ | Feature | livereload-morph | livereload-js |
77
+ |---------|------------------|---------------|
78
+ | HTML updates | Morph (preserves state) | Full reload |
79
+ | CSS updates | Clone-replace | Clone-replace |
80
+ | Input state | Preserved | Lost on reload |
81
+ | Scroll position | Preserved | Lost on reload |
82
+ | Focus state | Preserved | Lost on reload |
73
83
 
74
- ## Configuration Options
84
+ ## How It Works
85
+
86
+ When a file changes:
87
+
88
+ - **CSS files** → Clone-and-replace for `<link>` tags, CSSOM rule replacement for `@import`
89
+ - **Images** → Cache-bust `<img>` src and CSS backgrounds
90
+ - **JavaScript** → Full page reload (no safe hot-reload)
91
+ - **Everything else** → Re-fetch page HTML and morph with idiomorph
92
+
93
+ ### State Preservation
94
+
95
+ The following is preserved automatically during HTML morphs:
96
+ - Input values (text, textarea, select)
97
+ - Checkbox/radio checked state
98
+ - `<details>` open/closed state
99
+ - Scroll position
100
+
101
+ For best results, add IDs to form elements. Without IDs, idiomorph may recreate elements instead of morphing them.
102
+
103
+ ## All Options
75
104
 
76
105
  | Option | Type | Default | Description |
77
106
  |--------|------|---------|-------------|
@@ -81,80 +110,32 @@ Or use query string parameters:
81
110
  | `https` | boolean | false | Use secure WebSocket (wss://) |
82
111
  | `morphHTML` | boolean | true | Enable HTML morphing |
83
112
  | `verbose` | boolean | false | Enable console logging |
84
- | `importCacheWaitPeriod` | number | 200 | Enable legacy WebKit @import workaround. Set to any value > 0 to enable, 0 to disable |
113
+ | `importCacheWaitPeriod` | number | 200 | Legacy WebKit @import workaround delay. Set to 0 to disable |
85
114
  | `mindelay` | number | 1000 | Min reconnection delay (ms) |
86
115
  | `maxdelay` | number | 60000 | Max reconnection delay (ms) |
87
116
  | `handshake_timeout` | number | 5000 | Handshake timeout (ms) |
88
117
 
89
- ## How It Works
90
-
91
- 1. **WebSocket Connection**: Connects to LiveReload server on port 35729
92
- 2. **File Change Detection**: Server sends `reload` command with changed file path
93
- 3. **Smart Routing**:
94
- - `.css` / `.css.map` files → Clone-and-replace for `<link>` tags, CSSOM rule replacement for `@import`
95
- - Images (`.jpg`, `.png`, `.gif`, `.svg`, `.webp`, `.ico`) → Cache-bust `<img>` src and CSS backgrounds
96
- - `.js` / `.mjs` files → Full page reload (no safe hot-reload)
97
- - Everything else → Morph with idiomorph (re-fetches page HTML)
98
- 4. **State Preservation**: idiomorph intelligently merges changes while preserving DOM state
99
-
100
- ### CSS Reload Details
101
-
102
- Live-morph supports both `<link>` tags and `@import` rules:
118
+ ## Browser Support
103
119
 
104
- - **`<link>` tags**: Clone with cache-busted URL, wait for load, remove original (prevents FOUC)
105
- - **`@import` rules**: Replace rule in CSSOM with cache-busted URL
106
- - By default uses legacy WebKit workaround (pre-cache with temp `<link>` tag to trigger browser fetch)
107
- - Prevents flicker when updating `@import` rules (still needed in modern browsers!)
108
- - Set `importCacheWaitPeriod: 0` to disable workaround (will cause brief flicker)
109
- - **Cross-origin CSS**: CORS-protected stylesheets are handled gracefully (can't inspect `@import` rules)
120
+ Modern browsers with ES6+ support (Chrome/Edge 60+, Firefox 60+, Safari 12+).
110
121
 
111
- ## State Preservation
122
+ ## License
112
123
 
113
- **What's preserved automatically:**
114
- - Input values (text, textarea, select)
115
- - Checkbox/radio checked state
116
- - `<details>` open/closed state
124
+ MIT
117
125
 
118
- **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.
126
+ ## Credits
119
127
 
120
- ## vs livereload-js
128
+ - [idiomorph](https://github.com/bigskysoftware/idiomorph) for DOM morphing
129
+ - [LiveReload Protocol 7](https://github.com/livereload/livereload-js)
121
130
 
122
- | Feature | livereload-morph | livereload-js |
123
- |---------|------------------|---------------|
124
- | HTML updates | ✅ Morph (preserves state) | ❌ Full reload |
125
- | CSS updates | ✅ Clone-replace | ✅ Clone-replace |
126
- | Input state | ✅ Preserved | ❌ Lost on reload |
127
- | Scroll position | ✅ Preserved | ❌ Lost on reload |
128
- | Focus state | ✅ Preserved | ❌ Lost on reload |
131
+ ---
129
132
 
130
- ## Development
133
+ ## Contributing
131
134
 
132
135
  ```bash
133
- # Build once
134
- bun run build
135
-
136
- # Build and watch for changes
137
- bun run build:watch
138
-
139
- # Run test server (builds + starts server)
140
- bun run test
141
-
142
- # Development mode (watch build + server)
143
- bun run dev
136
+ bun install # Install dependencies
137
+ bun run build # Build once
138
+ bun run dev # Watch mode + test server
139
+ bun run test # Run test server
140
+ bun run test:e2e # Run playwright tests
144
141
  ```
145
-
146
- ## Browser Support
147
-
148
- Modern browsers with ES6+ support:
149
- - Chrome/Edge 60+
150
- - Firefox 60+
151
- - Safari 12+
152
-
153
- ## License
154
-
155
- MIT
156
-
157
- ## Credits
158
-
159
- - Built with [idiomorph](https://github.com/bigskysoftware/idiomorph) for DOM morphing
160
- - Compatible with [LiveReload Protocol 7](github.com/livereload/livereload-js)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "livereload-morph",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "A livereload-js replacement using idiomorph for intelligent DOM morphing",
5
5
  "author": "Noah A.",
6
6
  "license": "MIT",