mikser-io-live 5.0.0 → 6.0.0

package/README.md

@@ -1,8 +1,8 @@
 # mikser-io-live
 
-Live-reload dev server for [Mikser](https://github.com/almero-digital-marketing/mikser-io). Wraps [alive-server](https://www.npmjs.com/package/alive-server) and serves the configured `outputFolder`, auto-refreshing browsers as Mikser regenerates files.
+Live reload for [mikser](https://github.com/almero-digital-marketing/mikser-io), mounted on mikser's own HTTP server.
 
-The lighter alternative to `mikser --server` when all you want is "save a file → browser refreshes." Pair with `mikser --watch` for the classic SSG dev loop. If you also need API endpoints, an admin UI, or other plugins that need a shared Express app, use `mikser --server` instead.
+Save a file, the browser updates. Edit a stylesheet and it swaps in place — no reload, so scroll position, open menus and form state survive.
 
 ## Install
 
@@ -17,22 +17,43 @@ npm install mikser-io-live
 import { live } from 'mikser-io-live'
 
 export default {
-  plugins: [
-    live({
-      port: 8080,
-      open: true
-    })
-  ]
+  plugins: [ /* … */, live() ],
 }
 ```
 
-The options object is passed straight through to `alive-server.start(...)`. Defaults applied by the plugin:
+```bash
+mikser --server --watch
+```
+
+That's the whole setup. `--watch` rebuilds on change, `--server` serves the output, and this plugin connects the two to the browser.
+
+| option | default | |
+| --- | --- | --- |
+| `path` | `/__mikser_live` | where the event stream is mounted |
+
+## What it does
+
+Watches the output folder and tells connected browsers what changed. That folder **is** the bytes the browser gets — a page arrives there by being rendered, a stylesheet by being copied, an image by being symlinked — so watching it catches all three. Deriving the list from what the engine rendered was tried and misses everything that was not rendered, which includes the most common reason to want live reload.
+
+What the engine is asked for is the timing and the verdict: changes are flushed at the end of a build, so one build produces one reload rather than forty, and a build that **failed** produces none. A failed render leaves the previous good output on disk, so reloading would show the same page and hide the failure — you get a console warning instead.
+
+Three behaviours worth knowing:
+
+- **Stylesheets swap, pages reload.** If everything that changed was CSS, the `<link>` href is refreshed and nothing else happens.
+- **Only the page you are looking at reloads.** A build that rerendered forty other pages does not interrupt this one.
+- **A mikser restart reloads.** The client notices the server it was talking to has been replaced and reloads rather than trusting a page the previous process rendered.
+
+## Requires `--server`
+
+There is no second server and no second port. Without a shared Express app there is nothing to mount on, and the plugin says so rather than starting one of its own.
+
+This is a change from 5.x, which wrapped [alive-server](https://www.npmjs.com/package/alive-server) and ran its own server on its own port. If you were using it as the lighter alternative to `mikser --server`, you now want `mikser --server --watch` instead — one port, one process, and it composes with every other plugin that mounts on the same app.
+
+## How the page gets the script
 
-- `wait: 1000`
-- `root: runtime.options.outputFolder`
-- `open: false`
+A small snippet is injected before `</body>`, falling back to `</svg>` then `</head>` — the same order [alive-server](https://www.npmjs.com/package/alive-server) uses, and right for the same reasons: a standalone SVG served as a page has no body, and some documents have no closing body tag at all. A page with none of the three is warned about once, because a page that silently never reloads looks exactly like a reload that is broken.
 
-Pair with Mikser's watch mode to get a live-reloading dev loop.
+Requests carrying an `Origin` header are left alone. Those are `fetch`/XHR — script asking for the same HTML as data — and injecting there corrupts what the caller parses.
 
 ## License
 

package/index.js

@@ -1,16 +1,235 @@
-import liveServer from 'alive-server'
+// Live reload on mikser's own server.
+//
+// This used to start a second HTTP server on a second port (alive-server),
+// which watched the output folder and guessed, from a one-second debounce,
+// that a build had probably finished. That works, and it costs a port, a
+// separate process lifecycle, and a dependency — and it cannot answer the one
+// question that matters, which is what actually changed.
+//
+// Mounted on the shared Express app instead. It still watches the output
+// folder, because that folder IS the bytes the browser gets: a page arrives
+// there by being rendered, a stylesheet by being copied, an image by being
+// symlinked, and only one of those three produces anything in the build
+// report. Deriving the served paths from what the engine rendered was tried
+// and is wrong twice over — it misses every file that was not rendered, and
+// it turns one observation into three inferences.
+//
+// What the engine IS asked for is the timing and the verdict: flush at the end
+// of a cycle so a build produces one reload rather than forty, and do not
+// reload at all when the build failed.
+//
+// Requires `mikser --server`. Without a shared app there is nothing to mount
+// on, and the plugin says so rather than starting a server of its own — one
+// port and one lifecycle is the point.
+
+import path from 'node:path'
+import { existsSync, statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+
+import { clientScript } from './lib/client.js'
+
+// Where the snippet goes, in preference order — borrowed from alive-server,
+// which is right about this: `</svg>` matters because a standalone SVG served
+// as a page has no body, and `</head>` is the fallback for a document with no
+// closing body tag at all.
+const INJECT_BEFORE = [/<\/body>/i, /<\/svg>/i, /<\/head>/i]
+
+// Only files that can carry a script tag.
+const INJECTABLE = new Set(['.html', '.htm', '.xhtml', '.svg'])
+
+// Where the snippet goes in a given document, or null if there is nowhere.
+//
+// Exported because it is the only part of the injection with a decision in it,
+// and a closure inside an express handler is not a thing a test can reach.
+export function injectionPoint(html) {
+    for (const candidate of INJECT_BEFORE) {
+        const match = candidate.exec(html)
+        if (match) return match[0]
+    }
+    return null
+}
+
+// Before the closing tag, never after: a script appended past </body> is
+// outside the document and browsers put it back inside anyway, which makes the
+// bytes on the wire disagree with the DOM.
+export function injectInto(html, script) {
+    const tag = injectionPoint(html)
+    if (!tag) return html
+    return html.replace(tag, script + tag)
+}
 
 export function live(options = {}) {
-    return ({ onLoaded, runtime, useLogger }) => {
+    const streamPath = options.path ?? '/__mikser_live'
+    // Changes every start. A client that reconnects and sees a different one
+    // knows mikser restarted — new code, possibly a different site — and
+    // reloads rather than trusting a page the previous process rendered.
+    const boot = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
+    return (core) => {
+        const {
+            runtime, onLoaded, onFinalized, useLogger,
+            registerRoute, requestReport, buildReport, watchFolder,
+        } = core
+
+        // Per-cycle recording is opt-in, and this plugin is a reader — see
+        // report.js requestReport. Asked for at registration, before any cycle
+        // has run, or the first build reports nothing to reload from.
+        requestReport()
+
+        const clients = new Set()
+
+        function broadcast(event, data) {
+            const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
+            for (const res of clients) {
+                try { res.write(frame) } catch { clients.delete(res) }
+            }
+        }
+
+        // Resolve a request path the way express.static will, so the middleware
+        // injects into exactly the file that is about to be served.
+        function resolveFile(pathname) {
+            const root = runtime.options.outputFolder
+            if (!root) return null
+            const decoded = decodeURIComponent(pathname)
+            let file = path.join(root, decoded)
+            // Containment: a decoded `..` must not reach outside the folder
+            // being served. express.static guards its own reads; this one is
+            // ours and needs its own.
+            if (path.relative(root, file).startsWith('..')) return null
+            if (existsSync(file) && statSync(file).isDirectory()) file = path.join(file, 'index.html')
+            if (!existsSync(file)) return null
+            return INJECTABLE.has(path.extname(file).toLowerCase()) ? file : null
+        }
+
         onLoaded(async () => {
             const logger = useLogger()
-            logger.info('Starting live server')
-            liveServer.start({
-                wait: 1000,
-                root: runtime.options.outputFolder,
-                open: false,
-                ...options,
+            const app = runtime.options.app
+            if (!app) {
+                logger.warn({ code: 'live-no-server' },
+                    'live() needs the shared HTTP server and there is none — run `mikser --server`. Nothing is '
+                    + 'mounted, so pages will not reload; the build itself is unaffected.')
+                return
+            }
+
+            // The event stream. `streaming` so a reverse-proxy generator knows
+            // never to buffer it — a buffered SSE stream delivers every event
+            // at once when the connection closes, which is indistinguishable
+            // from live reload not working.
+            registerRoute({
+                path: streamPath,
+                plugin: 'live',
+                reachability: 'public',
+                streaming: true,
+                label: 'Live reload',
+                detail: 'reload events for pages served from the output folder',
+            })
+
+            app.get(streamPath, (req, res) => {
+                res.writeHead(200, {
+                    'Content-Type': 'text/event-stream',
+                    'Cache-Control': 'no-cache, no-transform',
+                    Connection: 'keep-alive',
+                    // Nginx buffers proxied responses by default and that is
+                    // fatal to an event stream; this is the header it honours.
+                    'X-Accel-Buffering': 'no',
+                })
+                res.write(`event: hello\ndata: ${JSON.stringify({ boot })}\n\n`)
+                clients.add(res)
+                req.on('close', () => clients.delete(res))
+            })
+
+            // Injection, ahead of the static mount.
+            //
+            // The engine registers its static handler from an inner onLoaded
+            // so it runs last, after every plugin has had its turn. That is
+            // what lets this sit in front of it and hand back an HTML document
+            // with the snippet in it; anything this does not answer falls
+            // through and is served normally.
+            app.use((req, res, next) => {
+                if (req.method !== 'GET' && req.method !== 'HEAD') return next()
+                // No Origin means a top-level navigation. A request WITH one
+                // is fetch/XHR — script asking for the same HTML as data — and
+                // injecting there corrupts what the caller parses. Borrowed
+                // from alive-server, and it is the subtle half of doing this
+                // correctly.
+                if (req.headers.origin) return next()
+
+                const file = resolveFile(req.path)
+                if (!file) return next()
+
+                readFile(file, 'utf8').then((html) => {
+                    const tag = injectionPoint(html)
+                    if (!tag) {
+                        // Said out loud, once per file. A page that silently
+                        // never receives the snippet looks exactly like a page
+                        // whose reload is broken, and the difference is a
+                        // missing closing tag nobody would think to look for.
+                        warnOnce(logger, file)
+                        return next()
+                    }
+                    const body = injectInto(html, clientScript(streamPath))
+                    res.type(path.extname(file) === '.svg' ? 'image/svg+xml' : 'html')
+                    res.set('Cache-Control', 'no-store')
+                    res.send(body)
+                }).catch(() => next())
+            })
+
+            logger.info('Live reload mounted: %s', streamPath)
+        })
+
+        // Served paths that changed, straight from the folder they are served
+        // from. Accumulated rather than sent per event: one build writes many
+        // files, and a reload per file is a browser that never settles.
+        const pending = new Set()
+        let flushTimer = null
+
+        function flush() {
+            clearTimeout(flushTimer)
+            flushTimer = null
+            if (!pending.size || !clients.size) return pending.clear()
+            const paths = [...pending]
+            pending.clear()
+            // The one thing the folder cannot tell us: whether the build that
+            // wrote it succeeded. A failed render leaves the previous good
+            // bytes in place, so the page would reload to look identical and
+            // the failure would pass unnoticed.
+            const errors = buildReport().summary?.errors ?? 0
+            broadcast('build', { errors, paths })
+        }
+
+        onLoaded(async () => {
+            const outputFolder = runtime.options.outputFolder
+            if (!runtime.options.app || !outputFolder) return
+
+            // The engine's own watcher primitive, not a second chokidar.
+            // It carries mikser's junk filter and — load-bearing here — it
+            // follows symlinks: the files plugin serves a file by linking it
+            // from the source folder into the output folder, so a watcher that
+            // stopped at the link would see it created once and never hear
+            // about a stylesheet edit again.
+            watchFolder(outputFolder, (_event, fullPath) => {
+                const rel = path.relative(outputFolder, fullPath)
+                if (!rel || rel.startsWith('..')) return
+                pending.add('/' + rel.split(path.sep).join('/'))
+                // Fallback only. A change that arrives outside a build —
+                // something else writing into the folder — still reaches the
+                // browser, just without a verdict to go with it.
+                clearTimeout(flushTimer)
+                flushTimer = setTimeout(flush, 250)
             })
         })
+
+        // The primary flush. One event per build, with an accurate error
+        // count, rather than whenever the debounce happens to expire.
+        onFinalized(async () => flush())
     }
 }
+
+const warned = new Set()
+function warnOnce(logger, file) {
+    if (warned.has(file)) return
+    warned.add(file)
+    logger?.warn?.({ code: 'live-no-inject-point' },
+        'Could not inject the live-reload snippet into %s — it has no </body>, </svg> or </head>. That page '
+        + 'will not reload on its own; every other page still will.', file)
+}

package/lib/client.js

@@ -0,0 +1,57 @@
+// The snippet injected into every served HTML page.
+//
+// Deliberately dependency-free and tiny: it is added to every page in dev, so
+// anything it drags in is something the developer is looking at that will not
+// be there in production.
+//
+// EventSource rather than a WebSocket. It reconnects on its own, survives a
+// mikser restart without any retry logic here, needs no upgrade handshake, and
+// mikser already has a `streaming: true` route kind for exactly this.
+export function clientScript(path) {
+    return `<script data-mikser-live>(() => {
+  const source = new EventSource(${JSON.stringify(path)})
+  let boot = null
+
+  // A different boot id means mikser restarted — new code, new config,
+  // possibly a different site. Reload rather than trusting a page rendered by
+  // the process that just went away.
+  source.addEventListener('hello', (event) => {
+    const id = JSON.parse(event.data).boot
+    if (boot !== null && boot !== id) return location.reload()
+    boot = id
+  })
+
+  source.addEventListener('build', (event) => {
+    const { paths = [], errors = 0 } = JSON.parse(event.data)
+
+    // A failed build leaves the previous good output on disk, so reloading
+    // shows the same page and hides the failure. Say so instead.
+    if (errors) return console.warn('[mikser] build failed —', errors, 'render error(s); page not reloaded')
+    if (!paths.length) return
+
+    // Stylesheets swap in place. Reloading would work and would also throw
+    // away scroll position, open menus, form state and whatever you were
+    // looking at — which for a CSS edit is the entire cost of the change.
+    const css = paths.filter((p) => p.endsWith('.css'))
+    if (css.length === paths.length) {
+      for (const link of document.querySelectorAll('link[rel=stylesheet]')) {
+        const url = new URL(link.href, location.href)
+        if (!css.includes(url.pathname)) continue
+        // set(), not append: repeated edits must not accumulate a query
+        // string, which is what makes the browser treat it as a new resource
+        // every time and never reuse the connection.
+        url.searchParams.set('mikser', Date.now())
+        link.href = url.href
+      }
+      return
+    }
+
+    // Anything else: reload, but only if this page is among what changed. A
+    // build that rerendered forty other pages is not a reason to interrupt
+    // the one being looked at.
+    const here = location.pathname
+    const asIndex = here.endsWith('/') ? here + 'index.html' : here
+    if (paths.includes(here) || paths.includes(asIndex)) location.reload()
+  })
+})()</script>`
+}

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "mikser-io-live",
-  "version": "5.0.0",
-  "description": "",
+  "version": "6.0.0",
+  "description": "Live reload for mikser-io, mounted on mikser's own HTTP server. Reloads from the build report rather than by watching files, so a CSS edit swaps the stylesheet in place and a build that touched other pages does not interrupt the one you are looking at.",
   "main": "index.js",
   "type": "module",
-  "scripts": {},
+  "scripts": {
+    "test": "node --test --test-reporter=spec 'test/**/*.test.js'"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/almero-digital-marketing/mikser-io-live.git"
@@ -16,9 +18,6 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-live#readme",
   "peerDependencies": {
-    "mikser-io": "^9.0.0"
-  },
-  "dependencies": {
-    "alive-server": "^1.3.0"
+    "mikser-io": "^9.62.0"
   }
 }

package/test/inject.test.js

@@ -0,0 +1,77 @@
+// Where the live-reload snippet goes, and what the browser does with it.
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { injectionPoint, injectInto } from '../index.js'
+import { clientScript } from '../lib/client.js'
+
+describe('finding somewhere to put the snippet', () => {
+    it('prefers the end of the body', () => {
+        assert.equal(injectionPoint('<html><head></head><body>hi</body></html>'), '</body>')
+    })
+
+    it('falls back to a closing svg', () => {
+        // A standalone SVG served as a page has no body at all, and is a thing
+        // mikser renders. Borrowed from alive-server, which is right about it.
+        assert.equal(injectionPoint('<svg xmlns="http://www.w3.org/2000/svg"><rect/></svg>'), '</svg>')
+    })
+
+    it('falls back to the head for a document with no closing body', () => {
+        assert.equal(injectionPoint('<html><head><title>t</title></head><p>loose'), '</head>')
+    })
+
+    it('reports nowhere rather than guessing', () => {
+        // A fragment with no closing tag gets no snippet, and the plugin warns
+        // — a page that silently never reloads looks exactly like a page whose
+        // reload is broken.
+        assert.equal(injectionPoint('<p>just a fragment</p>'), null)
+    })
+
+    it('matches case-insensitively, because HTML does', () => {
+        assert.equal(injectionPoint('<BODY>hi</BODY>'), '</BODY>')
+    })
+})
+
+describe('injecting', () => {
+    it('puts the script BEFORE the closing tag, not after', () => {
+        // Past </body> is outside the document; browsers move it back inside,
+        // so the bytes on the wire stop agreeing with the DOM.
+        const out = injectInto('<body>hi</body>', '<script>x</script>')
+        assert.match(out, /<script>x<\/script><\/body>/)
+    })
+
+    it('leaves a document it cannot inject into byte-identical', () => {
+        const html = '<p>fragment</p>'
+        assert.equal(injectInto(html, '<script>x</script>'), html)
+    })
+
+    it('injects once, at the first candidate only', () => {
+        const out = injectInto('<body>a</body><body>b</body>', '<script>x</script>')
+        assert.equal(out.split('<script>x</script>').length - 1, 1)
+    })
+})
+
+describe('the client snippet', () => {
+    it('connects to the path it was mounted at', () => {
+        assert.match(clientScript('/__custom'), /EventSource\("\/__custom"\)/)
+    })
+
+    it('is marked, so a reader can tell what put it there', () => {
+        assert.match(clientScript('/x'), /data-mikser-live/)
+    })
+
+    it('does not reload on a failed build', () => {
+        // The previous good output is still on disk, so a reload shows the
+        // same page and hides the failure.
+        assert.match(clientScript('/x'), /if \(errors\) return console\.warn/)
+    })
+
+    it('swaps stylesheets instead of reloading', () => {
+        assert.match(clientScript('/x'), /link\[rel=stylesheet\]/)
+    })
+
+    it('reloads when mikser restarts under it', () => {
+        assert.match(clientScript('/x'), /boot !== id/)
+    })
+})