mikser-io-live 6.1.0 → 6.1.2

package/README.md

@@ -58,7 +58,9 @@ any of those.
 
 ## How the page gets the script
 
-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.
+A small snippet is injected before `</body>`, falling back to `</head>` for a document with no closing body tag. A page with neither is warned about once, because a page that silently never reloads looks exactly like a reload that is broken.
+
+**`.html` and `.htm` only.** Nothing else is touched — in particular not SVG. An SVG served as `image/svg+xml` is parsed as XML, where the snippet's `&&` starts an entity reference and `<` starts a tag, so injecting there is not a no-op but a fatal parse error: the browser draws nothing. [alive-server](https://www.npmjs.com/package/alive-server) does inject into SVG and gets away with it by wrapping its script in `<![CDATA[ ]]>`; this one does not, and excluding the format outright is the version that cannot be got subtly wrong later.
 
 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.
 

package/index.js

@@ -27,15 +27,27 @@ import { existsSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 
 import { clientScript } from './lib/client.js'
+export { samePage } from './lib/paths.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]
+// Where the snippet goes, in preference order. `</head>` is the fallback for
+// a document with no closing body tag.
+const INJECT_BEFORE = [/<\/body>/i, /<\/head>/i]
 
-// Only files that can carry a script tag.
-const INJECTABLE = new Set(['.html', '.htm', '.xhtml', '.svg'])
+// HTML only, and this is a correctness limit rather than a scope decision.
+//
+// `.svg` and `.xhtml` were here, taken from alive-server, which does inject
+// into SVG — and gets away with it because its snippet is wrapped in
+// `// <![CDATA[ ... // ]]>`. Mine is not, and an SVG served as image/svg+xml
+// is parsed as XML: `&&` starts an entity reference and `<` starts a tag, so
+// the script is not merely ignored, it is a FATAL parse error and the browser
+// renders nothing at all.
+//
+// Wrapping in CDATA would make SVG work again. Not doing it: a standalone SVG
+// page that live-reloads is a rare thing to want, breaking one outright is
+// not, and a rule that reads "html and htm" cannot be got subtly wrong the way
+// a rule that reads "html, and also XML dialects if the payload is escaped
+// correctly" can.
+const INJECTABLE = new Set(['.html', '.htm'])
 
 // Where the snippet goes in a given document, or null if there is nowhere.
 //
@@ -171,7 +183,7 @@ export function live(options = {}) {
                         return next()
                     }
                     const body = injectInto(html, clientScript(streamPath))
-                    res.type(path.extname(file) === '.svg' ? 'image/svg+xml' : 'html')
+                    res.type('html')
                     res.set('Cache-Control', 'no-store')
                     res.send(body)
                 }).catch(() => next())
@@ -233,6 +245,6 @@ 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 '
+        'Could not inject the live-reload snippet into %s — it has no </body> or </head>. That page '
         + 'will not reload on its own; every other page still will.', file)
 }

package/lib/client.js

@@ -7,8 +7,11 @@
 // 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.
+import { samePage } from './paths.js'
+
 export function clientScript(path) {
     return `<script data-mikser-live>(() => {
+  const samePage = ${samePage.toString()}
   const source = new EventSource(${JSON.stringify(path)})
   let boot = null
 
@@ -49,9 +52,12 @@ export function clientScript(path) {
     // 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()
+    //
+    // Compared after normalising both sides, because one page has three URLs.
+    // /about, /about/ and /about/index.html are all served, and the watcher
+    // only ever reports the third — so a plain comparison reloaded two of them
+    // and silently never reloaded the one people actually type or link to.
+    if (paths.some((p) => samePage(p, location.pathname))) location.reload()
   })
 })()</script>`
 }

package/lib/paths.js

@@ -0,0 +1,15 @@
+// Is a changed path the page a browser is looking at?
+//
+// One page has three URLs. /about, /about/ and /about/index.html are all
+// served, and the watcher only ever reports the third — so comparing them
+// literally reloads two of them and silently never reloads the one people
+// actually type or link to.
+//
+// Lives here, alone, because it is needed on both sides: the browser decides
+// with it, and the tests check it. The snippet inlines THIS function's source
+// rather than carrying its own copy, so the two cannot drift into disagreeing
+// about which page you are on.
+export function samePage(a, b) {
+    const norm = (p) => String(p).replace(/\/index\.html$/, '/').replace(/(.)\/$/, '$1')
+    return norm(a) === norm(b)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-live",
-  "version": "6.1.0",
+  "version": "6.1.2",
   "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",

package/test/inject.test.js

@@ -3,7 +3,7 @@
 import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { injectionPoint, injectInto } from '../index.js'
+import { injectionPoint, injectInto, samePage } from '../index.js'
 import { clientScript } from '../lib/client.js'
 
 describe('finding somewhere to put the snippet', () => {
@@ -11,10 +11,13 @@ describe('finding somewhere to put the snippet', () => {
         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('does NOT treat a closing svg as an injection point', () => {
+        // An SVG served as image/svg+xml is parsed as XML, where the script's
+        // `&&` starts an entity reference and `<` starts a tag. The snippet is
+        // not ignored there — it is a fatal parse error and the browser draws
+        // nothing. alive-server injects into SVG and gets away with it because
+        // its snippet is CDATA-wrapped; this one is not.
+        assert.equal(injectionPoint('<svg xmlns="http://www.w3.org/2000/svg"><rect/></svg>'), null)
     })
 
     it('falls back to the head for a document with no closing body', () => {
@@ -75,3 +78,56 @@ describe('the client snippet', () => {
         assert.match(clientScript('/x'), /boot !== id/)
     })
 })
+
+describe('what it will and will not touch', () => {
+    // The rule is html and htm. Anything XML-parsed is excluded outright
+    // rather than escaped into working, because a rule that says "HTML" cannot
+    // be got subtly wrong the way "HTML, plus XML dialects if the payload is
+    // escaped correctly" can.
+    it('leaves an svg document alone entirely', () => {
+        const svg = '<svg xmlns="http://www.w3.org/2000/svg"><rect/></svg>'
+        assert.equal(injectInto(svg, '<script>a && b</script>'), svg)
+    })
+
+    it('keeps the payload that would break XML, so the exclusion is load-bearing', () => {
+        // If the snippet ever became XML-safe this test says so, and the
+        // exclusion could be revisited deliberately rather than by accident.
+        assert.match(clientScript('/live'), /&&/)
+    })
+})
+
+describe('deciding whether a change is THIS page', () => {
+    // One page, three URLs. The watcher reports the file it saw —
+    // /about/index.html — and a browser may be sitting on any of the three.
+    it('treats every spelling of a page as the same page', () => {
+        for (const here of ['/about', '/about/', '/about/index.html']) {
+            assert.equal(samePage(here, '/about/index.html'), true, here)
+        }
+    })
+
+    it('treats the root the same way', () => {
+        for (const here of ['/', '/index.html']) {
+            assert.equal(samePage(here, '/index.html'), true, here)
+        }
+    })
+
+    it('still says no to a different page', () => {
+        // Over-matching would reload every browser on every build, which is
+        // the behaviour this whole comparison exists to avoid.
+        assert.equal(samePage('/contact/', '/about/index.html'), false)
+        assert.equal(samePage('/', '/about/index.html'), false)
+        assert.equal(samePage('/aboutus/', '/about/index.html'), false)
+    })
+})
+
+describe('the browser and the tests agree', () => {
+    it('the snippet uses the same comparison, not a copy of it', () => {
+        // Two implementations of "is this my page" is the shape that produced
+        // the bug: the tests would keep passing while the browser used
+        // something subtly different. The snippet inlines this function's
+        // own source.
+        const script = clientScript('/live')
+        assert.ok(script.includes(samePage.toString()),
+            'the client must carry THIS function, not a second version of it')
+    })
+})