From 355e8cad4c4bd13babc530376fbe8d3f487fa1dc Mon Sep 17 00:00:00 2001
From: Sergey Arkhangelskiy <mc.vertix@gmail.com>
Date: Tue, 10 Mar 2026 08:02:16 +0200
Subject: [PATCH 1/2] Add SPA episode navigation to avoid rerun WASM reload

Use rerun viewer's `add_receiver`/`remove_receiver` API to swap RRD
data without reloading the iframe. Adds Service Worker to cache WASM
assets and `/api/episode/{id}` endpoint for client-side navigation.
---
 positronic/server/positronic_server.py   |  43 +++--
 positronic/server/static/sw.js           |  31 ++++
 positronic/server/templates/base.html    |   1 +
 positronic/server/templates/episode.html | 202 +++++++++++++++++------
 4 files changed, 215 insertions(+), 62 deletions(-)
 create mode 100644 positronic/server/static/sw.js

diff --git a/positronic/server/positronic_server.py b/positronic/server/positronic_server.py
index e71d9a77..0e1bf0f6 100644
--- a/positronic/server/positronic_server.py
+++ b/positronic/server/positronic_server.py
@@ -103,6 +103,17 @@ async def cache_rerun_assets(request: Request, call_next):
     return response
 
 
+def _make_serializable(obj):
+    """Ensure obj is JSON serializable (e.g. convert datetime)."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, dict):
+        return {k: _make_serializable(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_make_serializable(v) for v in obj]
+    return obj
+
+
 def _iter_file_chunks(path: str, *, chunk_size: int = 128 * 1024):
     with open(path, 'rb') as source:
         while True:
@@ -188,16 +199,6 @@ async def episode_viewer(request: Request, episode_id: int):
     size_mb = meta.get('size_mb')
     size_mb_display = f'{size_mb:.2f}' if isinstance(size_mb, int | float) else None
 
-    # Ensure static_data is JSON serializable (e.g. handle datetime)
-    def _make_serializable(obj):
-        if isinstance(obj, datetime):
-            return obj.isoformat()
-        if isinstance(obj, dict):
-            return {k: _make_serializable(v) for k, v in obj.items()}
-        if isinstance(obj, list):
-            return [_make_serializable(v) for v in obj]
-        return obj
-
     return templates.TemplateResponse(
         'episode.html',
         {
@@ -428,6 +429,28 @@ async def api_dataset_status():
     }
 
 
+@app.get('/api/episode/{episode_id}')
+@require_dataset
+async def api_episode(episode_id: int):
+    ds = app_state.get('dataset')
+    try:
+        episode = ds[episode_id]
+    except IndexError as e:
+        raise HTTPException(status_code=404, detail='Episode not found') from e
+
+    meta = episode.meta
+    size_mb = meta.get('size_mb')
+
+    return {
+        'episode_id': episode_id,
+        'num_episodes': len(ds),
+        'task': episode.static.get('task', None),
+        'episode_path': meta.get('path'),
+        'episode_size_mb': f'{size_mb:.2f}' if isinstance(size_mb, int | float) else None,
+        'static_data': _make_serializable(episode.static),
+    }
+
+
 @app.get('/api/episode_rrd/{episode_id}')
 @require_dataset
 async def api_episode_rrd(episode_id: int):
diff --git a/positronic/server/static/sw.js b/positronic/server/static/sw.js
new file mode 100644
index 00000000..3f204a03
--- /dev/null
+++ b/positronic/server/static/sw.js
@@ -0,0 +1,31 @@
+// Service Worker to cache rerun WASM and JS assets.
+// These files are large (~35MB WASM) and don't change between episodes.
+
+const CACHE_NAME = 'rerun-assets-v1';
+const RERUN_PATH_PREFIX = '/static/rerun/';
+
+self.addEventListener('install', () => self.skipWaiting());
+self.addEventListener('activate', (event) => {
+    event.waitUntil(
+        caches.keys().then((names) =>
+            Promise.all(names.filter((n) => n !== CACHE_NAME).map((n) => caches.delete(n)))
+        ).then(() => self.clients.claim())
+    );
+});
+
+self.addEventListener('fetch', (event) => {
+    const url = new URL(event.request.url);
+    if (!url.pathname.startsWith(RERUN_PATH_PREFIX)) return;
+
+    event.respondWith(
+        caches.open(CACHE_NAME).then((cache) =>
+            cache.match(event.request).then((cached) => {
+                if (cached) return cached;
+                return fetch(event.request).then((response) => {
+                    if (response.ok) cache.put(event.request, response.clone());
+                    return response;
+                });
+            })
+        )
+    );
+});
diff --git a/positronic/server/templates/base.html b/positronic/server/templates/base.html
index 5995fbb9..a2f3427b 100644
--- a/positronic/server/templates/base.html
+++ b/positronic/server/templates/base.html
@@ -28,6 +28,7 @@
     </div>
 
     <script src="/static/app.js"></script>
+    <script>if ('serviceWorker' in navigator) navigator.serviceWorker.register('/static/sw.js', {scope: '/static/'});</script>
     {% block scripts %}{% endblock %}
 </body>
 </html>
diff --git a/positronic/server/templates/episode.html b/positronic/server/templates/episode.html
index a642f8e8..60ea7a0e 100644
--- a/positronic/server/templates/episode.html
+++ b/positronic/server/templates/episode.html
@@ -7,48 +7,159 @@
 {% endblock %}
 
 {% block scripts %}
+<script>
+    const RERUN_VERSION = '{{ rerun_version }}';
+    let currentEpisodeId = {{ episode_id }};
+    let maxEpisodes = {{ num_episodes }};
+    let filteredIds = null;
+    let currentRrdUrl = null;
+    let viewerReady = false;
+
+    // SPA navigation: swap RRD data in the running rerun viewer via its JS API.
+    // This keeps the WASM alive — no 35MB re-download/recompile on each episode.
+    async function navigateToEpisode(episodeId) {
+        const resp = await fetch(`/api/episode/${episodeId}`);
+        if (!resp.ok) return;
+        const data = await resp.json();
+
+        currentEpisodeId = data.episode_id;
+        maxEpisodes = data.num_episodes;
+
+        const viewerIframe = document.getElementById('viewer-iframe');
+        const newRrdUrl = `${window.location.origin}/api/episode_rrd/${currentEpisodeId}`;
+
+        // Try to swap data in the live viewer via its handle API
+        let swapped = false;
+        if (viewerReady) {
+            try {
+                const handle = viewerIframe.contentWindow._handle;
+                if (handle && currentRrdUrl) {
+                    handle.remove_receiver(currentRrdUrl);
+                    handle.add_receiver(newRrdUrl, true);
+                    currentRrdUrl = newRrdUrl;
+                    swapped = true;
+                }
+            } catch (e) {
+                // Cross-origin or handle not available — fall back to iframe reload
+            }
+        }
+
+        if (!swapped) {
+            // Fallback: reload the iframe (first load or if handle unavailable)
+            const viewerUrl = new URL(`/static/rerun/${RERUN_VERSION}/index.html`, window.location.origin);
+            viewerUrl.searchParams.set('url', newRrdUrl);
+            viewerUrl.searchParams.set('hide_welcome_screen', '');
+            viewerIframe.src = viewerUrl;
+            currentRrdUrl = newRrdUrl;
+        }
+
+        // Update browser URL
+        history.pushState({episodeId: currentEpisodeId}, '', `/episode/${currentEpisodeId}`);
+        document.title = `Episode ${currentEpisodeId} / ${maxEpisodes}`;
+
+        // Update nav controls
+        updateNavControls();
+
+        // Update task
+        const taskEl = document.getElementById('task-description');
+        if (taskEl) taskEl.textContent = data.task ? ` : ${data.task}` : '';
+
+        // Update episode path/size
+        const pathEl = document.getElementById('episode-path-section');
+        if (pathEl) {
+            if (data.episode_path || data.episode_size_mb) {
+                pathEl.style.display = '';
+                const pathValue = pathEl.querySelector('.episode-path-value');
+                const pathLabel = pathEl.querySelector('.episode-path-label');
+                const sizeEl = pathEl.querySelector('.episode-size');
+                if (pathValue && pathLabel) {
+                    if (data.episode_path) { pathValue.textContent = data.episode_path; pathValue.style.display = ''; pathLabel.style.display = ''; }
+                    else { pathValue.style.display = 'none'; pathLabel.style.display = 'none'; }
+                }
+                if (sizeEl) {
+                    if (data.episode_size_mb) { sizeEl.textContent = `(${data.episode_size_mb} MB)`; sizeEl.style.display = ''; }
+                    else { sizeEl.style.display = 'none'; }
+                }
+            } else {
+                pathEl.style.display = 'none';
+            }
+        }
+
+        // Update sidebar
+        initializeSidebar(data.static_data);
+    }
+
+    function updateNavControls() {
+        const input = document.getElementById('episode-input');
+        if (filteredIds) {
+            const idx = filteredIds.indexOf(currentEpisodeId);
+            input.value = idx + 1;
+            input.dataset.original = idx + 1;
+            document.getElementById('episode-count').textContent = ` / ${filteredIds.length}`;
+        } else {
+            input.value = currentEpisodeId;
+            input.dataset.original = currentEpisodeId;
+            document.getElementById('episode-count').textContent = ` / ${maxEpisodes}`;
+        }
+    }
+
+    function getPrevEpisodeId() {
+        if (filteredIds) {
+            const idx = filteredIds.indexOf(currentEpisodeId);
+            return filteredIds[(idx - 1 + filteredIds.length) % filteredIds.length];
+        }
+        return (currentEpisodeId - 1 + maxEpisodes) % maxEpisodes;
+    }
+
+    function getNextEpisodeId() {
+        if (filteredIds) {
+            const idx = filteredIds.indexOf(currentEpisodeId);
+            return filteredIds[(idx + 1) % filteredIds.length];
+        }
+        return (currentEpisodeId + 1) % maxEpisodes;
+    }
+
+    // Listen for "READY" from the rerun viewer iframe
+    window.addEventListener('message', (e) => {
+        if (e.data === 'READY') viewerReady = true;
+    });
+
+    // Handle browser back/forward
+    window.addEventListener('popstate', (e) => {
+        if (e.state && e.state.episodeId !== undefined) {
+            navigateToEpisode(e.state.episodeId);
+        }
+    });
+</script>
+
 <script async>
     document.addEventListener('DOMContentLoaded', () => {
         initializeSidebar({{ static_data| tojson | safe }});
     });
 </script>
 
-<!-- Filtered episode navigation via sessionStorage.
-     When users arrive from the episodes table, the table stores the current filtered
-     episode ID list and referrer URL in sessionStorage. This lets prev/next cycle through
-     only the filtered subset. This state is ephemeral — it doesn't survive a page refresh
-     or a shared/bookmarked link, which is acceptable for transient filter UI state. The
-     "proper" alternative would be server-side: the /episode/{id} endpoint accepts filter
-     query params (reusing the existing matches() helper from /api/episodes), computes the
-     filtered list, and passes prev_episode_id/next_episode_id/filtered_count/filtered_index
-     in the template context. That gives stable URLs but requires server and template changes. -->
+<!-- Filtered episode navigation via sessionStorage. -->
 <script>
-    let filteredIds = (function() {
+    (function() {
         const raw = sessionStorage.getItem('filteredEpisodeIds');
-        if (!raw) return null;
+        if (!raw) return;
 
         let ids;
-        try { ids = JSON.parse(raw); } catch { return null; }
-        const currentId = {{ episode_id }};
-        if (!Array.isArray(ids) || ids.indexOf(currentId) === -1) return null;
+        try { ids = JSON.parse(raw); } catch { return; }
+        if (!Array.isArray(ids) || ids.indexOf(currentEpisodeId) === -1) return;
+
+        filteredIds = ids;
 
         const nav = document.getElementById('episode-nav');
         const input = document.getElementById('episode-input');
-        const currentIndex = ids.indexOf(currentId);
+        const currentIndex = ids.indexOf(currentEpisodeId);
 
-        // Switch to filtered mode: input shows 1-based position, not episode ID
         nav.classList.add('episode-nav--filtered');
         input.value = currentIndex + 1;
         input.dataset.original = currentIndex + 1;
         input.maxLength = String(ids.length).length;
-
-        const prevId = ids[(currentIndex - 1 + ids.length) % ids.length];
-        const nextId = ids[(currentIndex + 1) % ids.length];
-        document.getElementById('prev-btn').onclick = () => { window.location.href = `/episode/${prevId}`; };
-        document.getElementById('next-btn').onclick = () => { window.location.href = `/episode/${nextId}`; };
         document.getElementById('episode-count').textContent = ` / ${ids.length}`;
 
-        // Add dismiss × and "Filtered" badge inside the nav bar, before "Ep."
         const badge = document.createElement('span');
         badge.className = 'filter-label';
         badge.textContent = 'Filtered';
@@ -60,14 +171,9 @@
             sessionStorage.removeItem('filteredEpisodeIds');
             sessionStorage.removeItem('episodesReferrerUrl');
             nav.classList.remove('episode-nav--filtered');
-            input.value = currentId;
-            input.dataset.original = currentId;
-            input.maxLength = String({{ num_episodes }}).length;
-            document.getElementById('episode-count').textContent = ' / {{ num_episodes }}';
-            document.getElementById('prev-btn').onclick = () => { window.location.href = `/episode/{{ (episode_id - 1) % num_episodes }}`; };
-            document.getElementById('next-btn').onclick = () => { window.location.href = `/episode/{{ (episode_id + 1) % num_episodes }}`; };
-            document.getElementById('breadcrumb-root').href = '/';
             filteredIds = null;
+            updateNavControls();
+            document.getElementById('breadcrumb-root').href = '/';
             dismiss.remove();
             badge.remove();
         };
@@ -78,15 +184,12 @@
         if (referrerUrl) {
             document.getElementById('breadcrumb-root').href = referrerUrl;
         }
-
-        return ids;
     })();
 </script>
 
 <script>
     const episodeForm = document.getElementById('episode-form');
     const episodeInput = document.getElementById('episode-input');
-    const maxEpisodes = {{ num_episodes }};
 
     const maxEpisodeLength = String(maxEpisodes - 1).length;
     episodeInput.style.width = `${maxEpisodeLength + 1.5}ch`;
@@ -95,18 +198,17 @@
         e.preventDefault();
         const value = parseInt(episodeInput.value);
         if (filteredIds) {
-            // In filtered mode, input is 1-based position
             if (isNaN(value) || value < 1 || value > filteredIds.length) {
                 episodeInput.value = episodeInput.dataset.original;
                 return;
             }
-            window.location.href = `/episode/${filteredIds[value - 1]}`;
+            navigateToEpisode(filteredIds[value - 1]);
         } else {
             if (isNaN(value) || value < 0 || value >= maxEpisodes) {
                 episodeInput.value = episodeInput.dataset.original;
                 return;
             }
-            window.location.href = `/episode/${value}`;
+            navigateToEpisode(value);
         }
     });
 
@@ -127,17 +229,19 @@
         episodeInput.select();
     });
 
-    // URL params: ?t=<seconds_from_start> or ?ts_ns=<absolute_nanoseconds> to seek on load
+    // Initial load: set iframe src
     window.addEventListener('load', () => {
         const viewerIframe = document.getElementById('viewer-iframe');
-        const rrdUrl = `${window.location.origin}/api/episode_rrd/{{ episode_id }}`;
-        const viewerUrl = new URL(`/static/rerun/{{ rerun_version }}/index.html`, window.location.origin);
-        viewerUrl.searchParams.set('url', rrdUrl);
+        currentRrdUrl = `${window.location.origin}/api/episode_rrd/${currentEpisodeId}`;
+        const viewerUrl = new URL(`/static/rerun/${RERUN_VERSION}/index.html`, window.location.origin);
+        viewerUrl.searchParams.set('url', currentRrdUrl);
         viewerUrl.searchParams.set('hide_welcome_screen', '');
         const params = new URLSearchParams(window.location.search);
         if (params.has('ts_ns')) viewerUrl.searchParams.set('seek_ts_ns', params.get('ts_ns'));
         else if (params.has('t')) viewerUrl.searchParams.set('seek_t', params.get('t'));
         viewerIframe.src = viewerUrl;
+        // Replace initial history entry so popstate works
+        history.replaceState({episodeId: currentEpisodeId}, '');
     });
 </script>
 {% endblock %}
@@ -150,31 +254,25 @@
             <span class="breadcrumb-separator">›</span>
             <span id="episode-nav" class="episode-nav">
                 <span class="breadcrumb-text">Ep. </span>
-                <button id="prev-btn" onclick="window.location.href='/episode/{{ (episode_id - 1) % num_episodes }}'"
+                <button id="prev-btn" onclick="navigateToEpisode(getPrevEpisodeId())"
                     class="btn btn-ghost" title="Previous episode">&lt;</button>
                 <form id="episode-form" class="episode-form" style="display: inline; margin: 0;">
                     <input type="text" id="episode-input" class="episode-input" value="{{ episode_id }}"
                         data-original="{{ episode_id }}" maxlength="{{ num_episodes|string|length }}">
                 </form>
-                <button id="next-btn" onclick="window.location.href='/episode/{{ (episode_id + 1) % num_episodes }}'"
+                <button id="next-btn" onclick="navigateToEpisode(getNextEpisodeId())"
                     class="btn btn-ghost" title="Next episode">&gt;</button>
                 <span class="breadcrumb-text" id="episode-count"> / {{ num_episodes }}</span>
             </span>
-            {% if task %}<span class="task-description"> : {{ task }}</span>{% endif %}
+            <span class="task-description" id="task-description">{% if task %} : {{ task }}{% endif %}</span>
         </div>
     </div>
     <div class="episode-info-header">
-        {% if episode_path or episode_size_mb %}
-        <div class="episode-path">
-            {% if episode_path %}
-            <span class="episode-path-label">Episode path:</span>
-            <code class="episode-path-value">{{ episode_path }}</code>
-            {% endif %}
-            {% if episode_size_mb %}
-            <span class="episode-size">({{ episode_size_mb }} MB)</span>
-            {% endif %}
+        <div class="episode-path" id="episode-path-section" {% if not episode_path and not episode_size_mb %}style="display:none"{% endif %}>
+            <span class="episode-path-label" {% if not episode_path %}style="display:none"{% endif %}>Episode path:</span>
+            <code class="episode-path-value" {% if not episode_path %}style="display:none"{% endif %}>{{ episode_path or '' }}</code>
+            <span class="episode-size" {% if not episode_size_mb %}style="display:none"{% endif %}>{% if episode_size_mb %}({{ episode_size_mb }} MB){% endif %}</span>
         </div>
-        {% endif %}
 
         <button class="sidebar-toggler btn btn-primary">☰ Static Data</button>
     </div>

From 81d93dc390e9e1942f7d5acd39ec72aa019520b5 Mon Sep 17 00:00:00 2001
From: Sergey Arkhangelskiy <mc.vertix@gmail.com>
Date: Fri, 13 Mar 2026 15:52:15 +0200
Subject: [PATCH 2/2] Fix SPA viewer issues: sidebar accumulation, input
 maxLength, jinja2 dep

- Reset `viewerReady` on iframe fallback reload
- Use `replaceState` in popstate handler to avoid double history entries
- Clear sidebar content before re-rendering on SPA navigation
- Restore `input.maxLength` in `updateNavControls()` for both modes
- Add `jinja2` to dependencies (required by starlette's Jinja2Templates)
---
 positronic/server/static/app.js          |  1 +
 positronic/server/templates/episode.html | 12 +++++++++---
 pyproject.toml                           |  1 +
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/positronic/server/static/app.js b/positronic/server/static/app.js
index 8ce011dc..fdad6438 100644
--- a/positronic/server/static/app.js
+++ b/positronic/server/static/app.js
@@ -615,6 +615,7 @@ function loadSidebarState() {
 
 function initializeSidebar(staticData) {
   const tbody = document.querySelector('.sidebar-content-wrapper tbody');
+  tbody.innerHTML = '';
 
   tbody.insertAdjacentHTML('beforeend', renderLevel('', staticData));
   document.querySelectorAll('.expand-button').forEach((button) => {
diff --git a/positronic/server/templates/episode.html b/positronic/server/templates/episode.html
index 60ea7a0e..8f7f4cb2 100644
--- a/positronic/server/templates/episode.html
+++ b/positronic/server/templates/episode.html
@@ -17,7 +17,7 @@
 
     // SPA navigation: swap RRD data in the running rerun viewer via its JS API.
     // This keeps the WASM alive — no 35MB re-download/recompile on each episode.
-    async function navigateToEpisode(episodeId) {
+    async function navigateToEpisode(episodeId, {replace = false} = {}) {
         const resp = await fetch(`/api/episode/${episodeId}`);
         if (!resp.ok) return;
         const data = await resp.json();
@@ -46,6 +46,7 @@
 
         if (!swapped) {
             // Fallback: reload the iframe (first load or if handle unavailable)
+            viewerReady = false;
             const viewerUrl = new URL(`/static/rerun/${RERUN_VERSION}/index.html`, window.location.origin);
             viewerUrl.searchParams.set('url', newRrdUrl);
             viewerUrl.searchParams.set('hide_welcome_screen', '');
@@ -54,7 +55,10 @@
         }
 
         // Update browser URL
-        history.pushState({episodeId: currentEpisodeId}, '', `/episode/${currentEpisodeId}`);
+        const historyState = {episodeId: currentEpisodeId};
+        const url = `/episode/${currentEpisodeId}`;
+        if (replace) history.replaceState(historyState, '', url);
+        else history.pushState(historyState, '', url);
         document.title = `Episode ${currentEpisodeId} / ${maxEpisodes}`;
 
         // Update nav controls
@@ -95,10 +99,12 @@
             const idx = filteredIds.indexOf(currentEpisodeId);
             input.value = idx + 1;
             input.dataset.original = idx + 1;
+            input.maxLength = String(filteredIds.length).length;
             document.getElementById('episode-count').textContent = ` / ${filteredIds.length}`;
         } else {
             input.value = currentEpisodeId;
             input.dataset.original = currentEpisodeId;
+            input.maxLength = String(maxEpisodes - 1).length;
             document.getElementById('episode-count').textContent = ` / ${maxEpisodes}`;
         }
     }
@@ -127,7 +133,7 @@
     // Handle browser back/forward
     window.addEventListener('popstate', (e) => {
         if (e.state && e.state.episodeId !== undefined) {
-            navigateToEpisode(e.state.episodeId);
+            navigateToEpisode(e.state.episodeId, {replace: true});
         }
     });
 </script>
diff --git a/pyproject.toml b/pyproject.toml
index fb43baba..f7cdd7db 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -22,6 +22,7 @@ dependencies = [
     "dearpygui",
     "dm_control",
     "fastapi",
+    "jinja2",  # Required by starlette's Jinja2Templates (optional dep of fastapi)
     "fire",
     "httpx",
     "msgpack",