@invisibleloop/pulse 0.21.2 → 0.21.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.21.2",
+  "version": "0.21.4",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -76,7 +76,7 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/cli/feedback.test.js && node src/cli/update.test.js && node src/cli/dev-host.test.js && node src/cli/dev-reload.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node scripts/release-version.test.js && node src/mcp/mcp.test.js && node src/mcp/guards.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/cli/feedback.test.js && node src/cli/update.test.js && node src/cli/dev-host.test.js && node src/cli/dev-reload.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node scripts/bootstrap.test.js && node scripts/release-version.test.js && node src/mcp/mcp.test.js && node src/mcp/guards.test.js",
     "typecheck": "tsc --noEmit",
     "docs": "node --watch src/cli/dev.js --root ../../docs --port 4000",
     "docs:start": "node ../../docs/server.js"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.21.2
+0.21.4

package/scripts/bootstrap.js

@@ -0,0 +1,25 @@
+/**
+ * Source of the production boot bundle entry generated for each hydrated page by
+ * scripts/build.js. Its own module (build.js runs the whole build when imported) so the
+ * generated code can be unit-tested.
+ *
+ * The first page's mount() instance is handed to initNavigation so the first client
+ * navigation destroys it; without that its listeners outlive the page (#168).
+ */
+export function buildBootstrapSource({ relSpec, relRuntime, relNavigate, storeImport = '', mountOpts = '{ ssr: true }' }) {
+  return `\
+import spec from '${relSpec}'
+import { mount } from '${relRuntime}'
+import { initNavigation } from '${relNavigate}'${storeImport}
+
+const root = document.getElementById('pulse-root')
+if (root && !root.dataset.pulseMounted) {
+  root.dataset.pulseMounted = '1'
+  const instance = mount(spec, root, window.__PULSE_SERVER__ || {}, ${mountOpts})
+  // Register the first page's instance so the first client navigation destroys it
+  initNavigation(root, mount).setMount(instance)
+}
+
+export default spec
+`
+}

package/scripts/build.js

@@ -21,6 +21,7 @@ import { discoverPages } from '../src/cli/discover.js'
 import { renderToString } from '../src/runtime/ssr.js'
 import { c, header, table, ok, fail, info, warn, elapsed, icon } from '../src/cli/fmt.js'
 import { extractUsedClasses, purgeCss, minifyCss } from './css-purge.js'
+import { buildBootstrapSource } from './bootstrap.js'
 
 // ---------------------------------------------------------------------------
 // Server-only property stripping
@@ -499,20 +500,7 @@ const bootstrapFiles = pages.flatMap(({ filePath }) => {
   const storeImport = STORE_PATH ? `\nimport store from '${path.relative(TMP_DIR, STORE_PATH)}'` : ''
   const mountOpts   = STORE_PATH ? `{ ssr: true, store }` : `{ ssr: true }`
 
-  fs.writeFileSync(bootstrapPath, `\
-import spec from '${relSpec}'
-import { mount } from '${relRuntime}'
-import { initNavigation } from '${relNavigate}'${storeImport}
-
-const root = document.getElementById('pulse-root')
-if (root && !root.dataset.pulseMounted) {
-  root.dataset.pulseMounted = '1'
-  mount(spec, root, window.__PULSE_SERVER__ || {}, ${mountOpts})
-  initNavigation(root, mount)
-}
-
-export default spec
-`)
+  fs.writeFileSync(bootstrapPath, buildBootstrapSource({ relSpec, relRuntime, relNavigate, storeImport, mountOpts }))
 
   return [{ filePath, bootstrapPath, name }]
 })

package/src/runtime/index.js

@@ -169,7 +169,9 @@ export function mount(spec, el, serverState = {}, options = {}) {
   // ---------------------------------------------------------------------------
 
   function persist() {
-    if (!persistKey) return
+    // The key is per route, not per instance: once destroyed, a late write (an action resolving
+    // after navigation) could overwrite what the next page, on the same route, has persisted.
+    if (!persistKey || _destroyed) return
     try {
       const snapshot = {}
       spec.persist.forEach(k => { snapshot[k] = state[k] })
@@ -184,6 +186,11 @@ export function mount(spec, el, serverState = {}, options = {}) {
   let lastHtml = null
 
   function render() {
+    // A destroyed instance never touches the DOM again. el now belongs to the page that replaced
+    // it, and an action that resolves late or a debounce timer that fires late would otherwise
+    // morph this page's view into that one (#172). State updates, toasts and store pushes from
+    // late work still go through; only the render (and persist(), below) is dropped.
+    if (_destroyed) return
     let html
     try {
       html = resolveView(spec, state, getEffectiveServerState())
@@ -303,8 +310,9 @@ export function mount(spec, el, serverState = {}, options = {}) {
     /** Force a re-render — useful after external state changes */
     refresh: render,
 
-    /** Tear down — remove event listeners, unsubscribe from store, clear element */
-    destroy: () => { _destroyed = true; _unsubStore?.(); _eventAbort.abort(); el.innerHTML = trustedHTML('') }
+    /** Tear down — remove event listeners, unsubscribe from store, clear element
+     *  (pass { keepDom: true } to leave the element's content in place) */
+    destroy: (opts) => { _destroyed = true; _unsubStore?.(); _eventAbort.abort(); if (!opts?.keepDom) el.innerHTML = trustedHTML('') }
   }
 }
 

package/src/runtime/navigate.js

@@ -26,6 +26,17 @@ export function initNavigation(root, mountFn) {
   let currentMount = null
   let currentNavController = null
 
+  // The target page has no client bundle (a purely server-rendered page), so nothing will mount
+  // over the previous page's instance. Release it, or its listeners keep firing on the new DOM
+  // and a store change re-renders the old view into it (#171). Call it immediately before the
+  // new HTML replaces the old (never earlier: if the response is cut off first, the visitor
+  // keeps a working page). keepDom: the caller swaps the root's content itself.
+  function releaseCurrentMount() {
+    const mount = currentMount
+    currentMount = null            // cleared first, so a throwing destroy() cannot leave a stale reference
+    mount?.destroy({ keepDom: true })
+  }
+
   async function navigate(path, push) {
     // Cancel any in-flight navigation before starting a new one
     currentNavController?.abort()
@@ -63,6 +74,10 @@ export function initNavigation(root, mountFn) {
             await applyScripts(msg.scripts)
 
           } else if (msg.type === 'html') {
+            if (!hydratePath) {
+              if (controller.signal.aborted) return   // superseded: leave the old page alone
+              releaseCurrentMount()
+            }
             root.innerHTML = trustedHTML(msg.html)
             // Index <pulse-deferred> placeholders so deferred chunks land in the right spot
             for (const id of (msg.deferred || [])) {
@@ -126,6 +141,7 @@ export function initNavigation(root, mountFn) {
           window.__updatePulseStore__(storeState)
         }
 
+        if (!hydrate) releaseCurrentMount()
         root.innerHTML = trustedHTML(html)
         document.title = title || document.title
         applyStyles(styles)

package/src/runtime/ssr.js

@@ -298,8 +298,9 @@ export function buildHydrateScript(spec, storeDef, nonce) {
   import { mount } from '/@pulse/runtime/index.js'
   import { initNavigation } from '/@pulse/runtime/navigate.js'${storeImport}
   const root = document.getElementById('pulse-root')
-  mount(spec, root, window.__PULSE_SERVER__ || {}${storeArg})
-  initNavigation(root, mount)
+  const instance = mount(spec, root, window.__PULSE_SERVER__ || {}${storeArg})
+  // Register the first page's instance so the first client navigation destroys it
+  initNavigation(root, mount).setMount(instance)
 </script>`
 }
 

package/types/navigate.d.ts

@@ -14,7 +14,9 @@ import type { PulseSpec } from './schema.js'
  * swaps #pulse-root, and re-mounts the new spec without a full page reload.
  * Falls back to location.href on any fetch or import error.
  *
- * Call once after the initial mount().
+ * Call once after the initial mount(), and pass that instance to the returned
+ * `setMount` so the first navigation destroys it. Without it the first page's
+ * listeners stay alive and every handler present on both pages runs twice.
  *
  * @param root    The #pulse-root element
  * @param mountFn The mount() function from @invisibleloop/pulse/runtime
@@ -24,8 +26,8 @@ import type { PulseSpec } from './schema.js'
  * import { initNavigation } from '@invisibleloop/pulse/navigate'
  *
  * const root = document.getElementById('pulse-root')
- * const m = mount(spec, root, window.__PULSE_SERVER__ ?? {}, { ssr: true })
- * initNavigation(root, mount)
+ * const instance = mount(spec, root, window.__PULSE_SERVER__ ?? {}, { ssr: true })
+ * initNavigation(root, mount).setMount(instance)
  */
 export function initNavigation(
   root:    HTMLElement,
@@ -35,4 +37,7 @@ export function initNavigation(
     serverState?: Record<string, unknown>,
     options?:    { ssr?: boolean; store?: unknown }
   ) => MountResult
-): void
+): {
+  /** Register the first page's mount so the first navigation destroys it. */
+  setMount(instance: MountResult | null | undefined): void
+}

package/types/runtime.d.ts

@@ -27,8 +27,9 @@ export interface MountOptions {
 }
 
 export interface MountResult {
-  /** Destroy this mount, remove event listeners, and unsubscribe from the store. */
-  destroy(): void
+  /** Remove listeners and unsubscribe from the store, then clear the element.
+   *  Pass `{ keepDom: true }` to leave the element's content in place. */
+  destroy(options?: { keepDom?: boolean }): void
 }
 
 /**