@shardworks/spider-apparatus 0.1.279 → 0.1.281

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/spider-apparatus",
-  "version": "0.1.279",
+  "version": "0.1.281",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -22,17 +22,17 @@
     "hono": "^4.7.11",
     "yaml": "^2.0.0",
     "zod": "4.3.6",
-    "@shardworks/fabricator-apparatus": "0.1.279",
-    "@shardworks/tools-apparatus": "0.1.279",
-    "@shardworks/clerk-apparatus": "0.1.279",
-    "@shardworks/codexes-apparatus": "0.1.279",
-    "@shardworks/stacks-apparatus": "0.1.279",
-    "@shardworks/loom-apparatus": "0.1.279",
-    "@shardworks/animator-apparatus": "0.1.279"
+    "@shardworks/fabricator-apparatus": "0.1.281",
+    "@shardworks/stacks-apparatus": "0.1.281",
+    "@shardworks/tools-apparatus": "0.1.281",
+    "@shardworks/animator-apparatus": "0.1.281",
+    "@shardworks/codexes-apparatus": "0.1.281",
+    "@shardworks/loom-apparatus": "0.1.281",
+    "@shardworks/clerk-apparatus": "0.1.281"
   },
   "devDependencies": {
     "@types/node": "25.5.0",
-    "@shardworks/nexus-core": "0.1.279"
+    "@shardworks/nexus-core": "0.1.281"
   },
   "files": [
     "dist",

package/src/static/feedback/feedback-ui.test.ts

@@ -316,16 +316,25 @@ describe('feedback.js tag filter toolbar', () => {
 // ── Deep-link URL state (?feedback=ID) ──────────────────────────────────
 
 describe('feedback.js — deep-link URL state', () => {
-  it('exposes currentUrlParams + updateUrl helpers (D9 — Ratchet pattern)', () => {
+  it('routes URL reads/writes through window.NexusUrl (no inline helpers)', () => {
+    // Inline currentUrlParams / updateUrl are gone (commission moix23w5).
+    assert.ok(
+      !/function\s+currentUrlParams\s*\(/.test(feedbackJs),
+      'inline currentUrlParams must not be redeclared',
+    );
+    assert.ok(
+      !/function\s+updateUrl\s*\(/.test(feedbackJs),
+      'inline updateUrl must not be redeclared',
+    );
     assert.match(
       feedbackJs,
-      /function currentUrlParams\(\)\s*\{[\s\S]*?new URLSearchParams\(window\.location\.search\)/,
-      'currentUrlParams reads window.location.search live',
+      /window\.NexusUrl\.read\(\)/,
+      'feedback.js should read URL state via window.NexusUrl.read',
     );
     assert.match(
       feedbackJs,
-      /function updateUrl\(changes\)\s*\{[\s\S]*?window\.history\.pushState/,
-      'updateUrl pushes via history.pushState',
+      /window\.NexusUrl\.update\(/,
+      'feedback.js should write URL state via window.NexusUrl.update',
     );
   });
 
@@ -336,21 +345,29 @@ describe('feedback.js — deep-link URL state', () => {
     assert.ok(block, 'should find showDetail body');
     assert.match(
       block[0],
-      /updateUrl\(\{\s*feedback:\s*currentRequest\.id\s*\}\)/,
-      'showDetail pushes ?feedback=<currentRequest.id> — keyed on the id, not the index',
+      /window\.NexusUrl\.update\(\{\s*feedback:\s*currentRequest\.id\s*\}\s*,\s*\{\s*push:\s*true\s*\}\)/,
+      'showDetail pushes ?feedback=<currentRequest.id> via NexusUrl.update with push: true',
     );
     assert.match(block[0], /skipUrlPush/, 'showDetail accepts a skipUrlPush opt');
   });
 
-  it('navigateToList clears ?feedback via updateUrl({feedback: null}) — never pops history (D11)', () => {
+  it('navigateToList clears ?feedback (and ?tag=) via NexusUrl with push: true (D11/D12)', () => {
     const block = feedbackJs.match(
       /function navigateToList\((?:opts)?\)[\s\S]*?fetchList\(\);[\s\S]*?startPoll\(\);\s*\}/,
     );
     assert.ok(block, 'should find navigateToList body');
     assert.match(
       block[0],
-      /updateUrl\(\{\s*feedback:\s*null\s*\}\)/,
-      'navigateToList should push a clean URL via updateUrl({feedback: null})',
+      /window\.NexusUrl\.update\(\{[^}]*feedback:\s*null[^}]*\}\s*,\s*\{\s*push:\s*true\s*\}\)/,
+      'navigateToList must push a clean URL with feedback: null',
+    );
+    // D12 — closing the detail also clears any per-detail ?tag= keys
+    // via the omit-defaults rule. The same NexusUrl.update call drops
+    // both keys at once.
+    assert.match(
+      block[0],
+      /tag:\s*null/,
+      'navigateToList must also drop ?tag= keys when the detail closes (D12)',
     );
     assert.ok(
       !/window\.history\.back\s*\(/.test(block[0]),
@@ -370,8 +387,8 @@ describe('feedback.js — deep-link URL state', () => {
     assert.ok(block, 'should find popstate handler body');
     assert.match(
       block[0],
-      /currentUrlParams\(\)\.get\(['"]feedback['"]\)/,
-      'popstate handler reads ?feedback from the new URL',
+      /readUrlState\(\)/,
+      'popstate handler reads URL state via the central readUrlState helper',
     );
     assert.match(
       block[0],
@@ -380,11 +397,11 @@ describe('feedback.js — deep-link URL state', () => {
     );
   });
 
-  it('init reads ?feedback=ID and resolves it via showDetailById', () => {
+  it('init reads URL state and resolves the deep-link via showDetailById', () => {
     assert.match(
       feedbackJs,
-      /var initialFeedbackId\s*=\s*currentUrlParams\(\)\.get\(['"]feedback['"]\)/,
-      'init reads ?feedback from the URL',
+      /var initialFeedbackId\s*=\s*readUrlState\(\)/,
+      'init calls readUrlState before fetching the list',
     );
     assert.match(
       feedbackJs,
@@ -399,7 +416,7 @@ describe('feedback.js — deep-link URL state', () => {
     );
     assert.ok(block, 'should find renderFeedbackNotFound body');
     assert.ok(
-      !/updateUrl/.test(block[0]),
+      !/NexusUrl\.update/.test(block[0]),
       'renderFeedbackNotFound must not rewrite the URL',
     );
     assert.match(
@@ -408,4 +425,63 @@ describe('feedback.js — deep-link URL state', () => {
       'renderFeedbackNotFound surfaces a "not found" message',
     );
   });
+
+  it('list-page status filter writes through NexusUrl.update (replace, no push: true)', () => {
+    const writer = feedbackJs.match(
+      /function writeStatusFilterToUrl\(\)[\s\S]*?(?=\n  function )/,
+    );
+    assert.ok(writer, 'writeStatusFilterToUrl should be defined');
+    assert.match(
+      writer[0],
+      /window\.NexusUrl\.update\(\{\s*status:[\s\S]*?\}\s*\)/,
+      'status filter must call NexusUrl.update without { push: true }',
+    );
+    assert.ok(
+      !/push:\s*true/.test(writer[0]),
+      'status filter writes must use replaceState (D5 default)',
+    );
+  });
+
+  it('per-detail tag filter writes ?tag= via repeated keys (D12 + D3)', () => {
+    const writer = feedbackJs.match(
+      /function writeTagFilterToUrl\(\)[\s\S]*?(?=\n  function )/,
+    );
+    assert.ok(writer, 'writeTagFilterToUrl should be defined');
+    assert.match(
+      writer[0],
+      /Object\.keys\(activeTagFilters\)/,
+      'tag filter writer reads from activeTagFilters',
+    );
+    assert.match(
+      writer[0],
+      /window\.NexusUrl\.update\(\{\s*tag:[\s\S]*?\}\s*\)/,
+      'tag filter writer calls NexusUrl.update with the tag key (no push: true)',
+    );
+    assert.ok(
+      !/push:\s*true/.test(writer[0]),
+      'tag filter changes must use replaceState (D5 default)',
+    );
+  });
+
+  it('readUrlState validates ?status= against STATUS_VALUES and surfaces fail-loud errors (D6)', () => {
+    const reader = feedbackJs.match(
+      /function readUrlState\(\)[\s\S]*?(?=\n  function )/,
+    );
+    assert.ok(reader, 'readUrlState should be defined');
+    assert.match(
+      reader[0],
+      /STATUS_VALUES\.indexOf/,
+      'readUrlState must validate ?status= against STATUS_VALUES',
+    );
+    assert.match(
+      reader[0],
+      /showUrlError\(/,
+      'readUrlState must surface invalid values via showUrlError',
+    );
+    assert.match(
+      reader[0],
+      /params\.getAll\(['"]tag['"]\)/,
+      'readUrlState must read ?tag= as a repeated-key array',
+    );
+  });
 });

package/src/static/feedback/feedback.js

@@ -35,35 +35,80 @@
   var successToast       = document.getElementById('success-toast');
 
   // ── URL handling ───────────────────────────────────────────────────────
+  //
+  // All deep-linkable view state for this page rides on
+  // `window.NexusUrl` — the shared helper auto-injected by oculus's
+  // chrome pass. The earlier inline `currentUrlParams` / `updateUrl`
+  // copies are gone (commission moix23w5).
+  //
+  // URL keys:
+  //   ?status=        pending | completed | rejected
+  //                   List-page status filter. Default 'pending'.
+  //   ?feedback=ID    Detail deep-link; pushes (D5).
+  //   ?tag=A&tag=B    Per-detail tag filter (D12). Repeated keys; clears
+  //                   itself when the detail closes via the omit-defaults
+  //                   rule.
+
+  var STATUS_VALUES = ['pending', 'completed', 'rejected'];
+  var DEFAULT_STATUS = 'pending';
+
+  function showUrlError(msg) {
+    var el = document.getElementById('url-error-banner');
+    if (!el) return;
+    var line = document.createElement('div');
+    line.textContent = msg;
+    el.appendChild(line);
+    el.style.display = 'block';
+  }
+
+  function clearUrlErrors() {
+    var el = document.getElementById('url-error-banner');
+    if (!el) return;
+    el.innerHTML = '';
+    el.style.display = 'none';
+  }
+
+  /** Persist the list-page status filter to the URL (replace, D5). */
+  function writeStatusFilterToUrl() {
+    var status = statusFilterEl ? statusFilterEl.value : DEFAULT_STATUS;
+    window.NexusUrl.update({
+      status: status === DEFAULT_STATUS ? null : status,
+    });
+  }
 
-  /**
-   * Read the current querystring as a `URLSearchParams`. Live snapshot.
-   */
-  function currentUrlParams() {
-    return new URLSearchParams(window.location.search);
+  /** Persist the per-detail tag filter to the URL (replace, D5). */
+  function writeTagFilterToUrl() {
+    var keys = Object.keys(activeTagFilters);
+    window.NexusUrl.update({
+      tag: keys.length === 0 ? null : keys,
+    });
   }
 
   /**
-   * Apply the given key/value changes to the current querystring and
-   * `pushState` the result. Null/undefined/empty value deletes the key.
-   * Mirrors Ratchet's `updateUrl` (D9). The feedback param shape is
-   * `?feedback=ID` (D10) — keyed on the request id (req.id), which is
-   * stable across the list reorderings the 12 s polling loop can
-   * trigger. The legacy index-based showDetail path now translates
-   * index → id at the click site.
+   * Read URL state into the page. Validates the status filter and any
+   * tag values; unknowns fail loud (D6). Returns the deep-link
+   * feedback id, if any.
    */
-  function updateUrl(changes) {
-    var params = currentUrlParams();
-    var keys = Object.keys(changes);
-    for (var i = 0; i < keys.length; i++) {
-      var key = keys[i];
-      var value = changes[key];
-      if (value === null || value === undefined || value === '') params.delete(key);
-      else params.set(key, value);
+  function readUrlState() {
+    clearUrlErrors();
+    var params = window.NexusUrl.read();
+
+    var status = params.get('status');
+    if (status !== null) {
+      if (STATUS_VALUES.indexOf(status) !== -1) {
+        if (statusFilterEl) statusFilterEl.value = status;
+      } else {
+        showUrlError('Unknown feedback status "' + status + '". Expected one of: ' + STATUS_VALUES.join(', ') + '.');
+      }
+    }
+
+    var tags = params.getAll('tag');
+    activeTagFilters = {};
+    for (var i = 0; i < tags.length; i++) {
+      activeTagFilters[tags[i]] = true;
     }
-    var qs = params.toString();
-    var next = window.location.pathname + (qs ? '?' + qs : '');
-    window.history.pushState({}, '', next);
+
+    return params.get('feedback');
   }
 
   // ── Helpers ────────────────────────────────────────────────────────────
@@ -180,8 +225,9 @@
 
     // Centralised URL push (D12) — keyed on the request id so the URL
     // survives list reorderings between the 12 s polls. Translation
-    // index → id happens here, not at the click site.
-    if (!skipUrlPush) updateUrl({ feedback: currentRequest.id });
+    // index → id happens here, not at the click site. Detail open is
+    // a navigation event (push: true).
+    if (!skipUrlPush) window.NexusUrl.update({ feedback: currentRequest.id }, { push: true });
 
     // Initialize local answers from server state
     localAnswers = {};
@@ -231,7 +277,7 @@
       })
       .then(function (req) {
         if (!req || !req.id) {
-          if (!skipUrlPush) updateUrl({ feedback: id });
+          if (!skipUrlPush) window.NexusUrl.update({ feedback: id }, { push: true });
           renderFeedbackNotFound(id);
           return;
         }
@@ -242,7 +288,7 @@
         showDetail(requests.length - 1, { skipUrlPush: skipUrlPush });
       })
       .catch(function () {
-        if (!skipUrlPush) updateUrl({ feedback: id });
+        if (!skipUrlPush) window.NexusUrl.update({ feedback: id }, { push: true });
         renderFeedbackNotFound(id);
       });
   }
@@ -332,6 +378,7 @@
             activeTagFilters[tag] = true;
             e.target.classList.add('active');
           }
+          writeTagFilterToUrl();
           applyTagFilters();
         } else if (e.target.matches('.tag-filter-clear')) {
           activeTagFilters = {};
@@ -339,6 +386,7 @@
           for (var j = 0; j < btns.length; j++) {
             btns[j].classList.remove('active');
           }
+          writeTagFilterToUrl();
           applyTagFilters();
         }
       });
@@ -604,8 +652,9 @@
     listView.style.display = '';
     // D11: push a clean URL so deep-link entries survive the Back
     // button. Never pop history — the operator may have arrived
-    // directly at ?feedback=ID.
-    if (!skipUrlPush) updateUrl({ feedback: null });
+    // directly at ?feedback=ID. Closing the detail also drops the
+    // per-detail tag filter via the omit-defaults rule (D12).
+    if (!skipUrlPush) window.NexusUrl.update({ feedback: null, tag: null }, { push: true });
     fetchList();
     startPoll();
   }
@@ -683,6 +732,7 @@
   });
 
   statusFilterEl.addEventListener('change', function () {
+    writeStatusFilterToUrl();
     requests = [];
     renderList();
     fetchList();
@@ -853,11 +903,12 @@
 
   // ── Browser navigation (popstate) ──────────────────────────────────────
 
-  // Read ?feedback=ID from the new URL and either re-open the matching
-  // detail (skipUrlPush=true) or return to the list. Pairs with the
-  // central push inside showDetail (D11/D12).
+  // Restore the full URL state on Back / Forward — ?status=,
+  // ?feedback=, and ?tag= each round-trip independently. The
+  // popstate-driven path uses skipUrlPush so it never re-pushes the
+  // URL the browser already updated.
   window.addEventListener('popstate', function () {
-    var feedbackId = currentUrlParams().get('feedback');
+    var feedbackId = readUrlState();
     if (feedbackId) {
       showDetailById(feedbackId, { skipUrlPush: true });
     } else {
@@ -866,17 +917,19 @@
   });
 
   // ── Init ───────────────────────────────────────────────────────────────
-
+  //
+  // Read URL state on first paint so the status filter, tag filter,
+  // and ?feedback= deep-link survive refresh and copy-paste. The list
+  // fetch already reads statusFilterEl.value, so updating that input
+  // before fetchList() is enough to apply the URL-restored status.
+  var initialFeedbackId = readUrlState();
   fetchList();
   startPoll();
 
   // Deep-link: ?feedback=ID — open that request's detail after the
-  // first list fetch lands. The list-fetch is async so we wait for it
-  // by polling `requests.length` once via a microtask; on a miss, the
-  // /api/input/request-show fallback inside showDetailById handles it.
-  // A missing/deleted/mistyped id renders a "not found" state without
-  // rewriting the URL (D16).
-  var initialFeedbackId = currentUrlParams().get('feedback');
+  // first list fetch lands. On a miss, the /api/input/request-show
+  // fallback inside showDetailById handles it. A missing/deleted/
+  // mistyped id renders a "not found" state without rewriting the URL.
   if (initialFeedbackId) {
     showDetailById(initialFeedbackId, { skipUrlPush: true });
   }

package/src/static/feedback/index.html

@@ -10,6 +10,14 @@
 <main style="padding: 24px;">
   <h1>Feedback</h1>
 
+  <!--
+    URL-state validation banner (D6 fail-loud). Shown when the page is
+    loaded with an invalid filter value (e.g. ?status=bogus). The banner
+    appends one line per invalid value; pages do not silently fall back
+    to a default.
+  -->
+  <div id="url-error-banner" class="error-msg" style="display:none;margin-bottom:12px;padding:0.6rem 0.8rem;background:var(--bg2,#1a1b26);border:1px solid var(--red,#f7768e);border-radius:6px;font-size:0.9rem;color:var(--red,#f7768e)"></div>
+
   <!-- List view -->
   <div id="list-view">
     <div class="toolbar">

package/src/static/index.html

@@ -24,6 +24,14 @@
 
   <h1>Spider</h1>
 
+  <!--
+    URL-state validation banner (D6 fail-loud). Shown when the page is
+    loaded with an invalid filter value (e.g. ?status=bogus). The banner
+    appends one line per invalid value; pages do not silently fall back
+    to a default.
+  -->
+  <div id="url-error-banner" class="error-msg" style="display:none;margin-bottom:12px;padding:0.6rem 0.8rem;background:var(--bg2,#1a1b26);border:1px solid var(--red,#f7768e);border-radius:6px;font-size:0.9rem;color:var(--red,#f7768e)"></div>
+
   <div class="tab-bar">
     <button class="tab active" data-tab="rigs">Rigs</button>
     <button class="tab" data-tab="config">Config</button>

package/src/static/spider-ui.test.ts

@@ -1917,33 +1917,37 @@ describe('spider.js engine-detail attempt-history details', () => {
 // ── Deep-link URL state (?rig=ID) ──────────────────────────────────────
 
 describe('spider.js — deep-link URL state', () => {
-  it('exposes currentUrlParams + updateUrl helpers (D9 — Ratchet pattern)', () => {
-    assert.match(
-      spiderJs,
-      /function currentUrlParams\(\)\s*\{[\s\S]*?new URLSearchParams\(window\.location\.search\)/,
-      'currentUrlParams reads window.location.search live',
+  it('routes URL reads/writes through window.NexusUrl (no inline helpers)', () => {
+    // Inline currentUrlParams / updateUrl are gone (commission moix23w5).
+    assert.ok(
+      !/function\s+currentUrlParams\s*\(/.test(spiderJs),
+      'inline currentUrlParams must not be redeclared',
+    );
+    assert.ok(
+      !/function\s+updateUrl\s*\(/.test(spiderJs),
+      'inline updateUrl must not be redeclared',
     );
     assert.match(
       spiderJs,
-      /function updateUrl\(changes\)\s*\{[\s\S]*?window\.history\.pushState/,
-      'updateUrl pushes via history.pushState',
+      /window\.NexusUrl\.read\(\)/,
+      'spider.js should read URL state via window.NexusUrl.read',
     );
     assert.match(
       spiderJs,
-      /function updateUrl\(changes\)[\s\S]*?params\.delete\(key\)/,
-      'updateUrl deletes the key when value is null/undefined/empty',
+      /window\.NexusUrl\.update\(/,
+      'spider.js should write URL state via window.NexusUrl.update',
     );
   });
 
-  it('showRigDetail pushes ?rig=ID via the central updateUrl call (D12)', () => {
+  it('showRigDetail pushes ?rig=ID via NexusUrl with push: true (D12)', () => {
     const block = spiderJs.match(
       /function showRigDetail\(rig(?:, opts)?\)[\s\S]*?(?=\n  function )/,
     );
     assert.ok(block, 'should find showRigDetail body');
     assert.match(
       block[0],
-      /updateUrl\(\{\s*rig:\s*rig\.id\s*\}\)/,
-      'showRigDetail should push ?rig=<rig.id> when not skipUrlPush',
+      /window\.NexusUrl\.update\(\{\s*rig:\s*rig\.id\s*\}\s*,\s*\{\s*push:\s*true\s*\}\)/,
+      'showRigDetail must push ?rig=<rig.id> when not skipUrlPush',
     );
     assert.match(
       block[0],
@@ -1952,15 +1956,15 @@ describe('spider.js — deep-link URL state', () => {
     );
   });
 
-  it('backToList clears ?rig via updateUrl({rig: null}) — never history.back (D11)', () => {
+  it('backToList clears ?rig via NexusUrl with push: true — never history.back (D11)', () => {
     const block = spiderJs.match(
       /function backToList\((?:opts)?\)[\s\S]*?(?=\n  function )/,
     );
     assert.ok(block, 'should find backToList body');
     assert.match(
       block[0],
-      /updateUrl\(\{\s*rig:\s*null\s*\}\)/,
-      'backToList should push a clean URL via updateUrl({rig: null})',
+      /window\.NexusUrl\.update\(\{\s*rig:\s*null\s*\}\s*,\s*\{\s*push:\s*true\s*\}\)/,
+      'backToList must push a clean URL via NexusUrl.update({rig: null}, {push: true})',
     );
     assert.ok(
       !/history\.back\(/.test(block[0]),
@@ -1980,8 +1984,8 @@ describe('spider.js — deep-link URL state', () => {
     assert.ok(block, 'should find popstate handler body');
     assert.match(
       block[0],
-      /currentUrlParams\(\)\.get\(['"]rig['"]\)/,
-      'popstate handler reads ?rig from the new URL',
+      /readUrlState\(\)/,
+      'popstate handler should restore filter state via readUrlState',
     );
     assert.match(
       block[0],
@@ -1990,15 +1994,15 @@ describe('spider.js — deep-link URL state', () => {
     );
   });
 
-  it('init reads ?rig=ID and opens the matching detail after the rig list lands', () => {
+  it('init reads URL state and opens the deep-linked rig after the list lands', () => {
     assert.match(
       spiderJs,
-      /currentUrlParams\(\)\.get\(['"]rig['"]\)/,
-      'init reads ?rig from the URL',
+      /var\s+initialState\s*=\s*readUrlState\(\)/,
+      'init should call readUrlState before fetching rigs',
     );
     assert.match(
       spiderJs,
-      /showRigDetailById\(\s*initialRigId\s*,\s*\{\s*skipUrlPush:\s*true\s*\}\s*\)/,
+      /showRigDetailById\(\s*initialState\.rigId\s*,\s*\{\s*skipUrlPush:\s*true\s*\}\s*\)/,
       'init opens the detail via showRigDetailById with skipUrlPush=true',
     );
   });
@@ -2008,10 +2012,10 @@ describe('spider.js — deep-link URL state', () => {
       /function renderRigDetailNotFound\([\s\S]*?(?=\n  function )/,
     );
     assert.ok(block, 'should find renderRigDetailNotFound body');
-    // The function itself must not call updateUrl — the URL is left
-    // alone so the operator can recover by editing the address bar.
+    // The function itself must not call NexusUrl.update — the URL is
+    // left alone so the operator can recover by editing the address bar.
     assert.ok(
-      !/updateUrl/.test(block[0]),
+      !/NexusUrl\.update/.test(block[0]),
       'renderRigDetailNotFound must not rewrite the URL',
     );
     assert.match(
@@ -2022,14 +2026,76 @@ describe('spider.js — deep-link URL state', () => {
   });
 
   it('does not push a tab=… or engine=… URL param (D13/D14 explicit out-of-scope)', () => {
+    // Filter-shaped only (D13 narrow reading): the rigs page must
+    // never write ?tab= or ?engine= to the URL. These assertions stay
+    // in place verbatim from the pre-migration test suite.
     assert.ok(
-      !/updateUrl\(\{\s*tab:/.test(spiderJs),
+      !/NexusUrl\.update\(\{\s*tab:/.test(spiderJs),
       'tab state must remain client-only (D14)',
     );
     assert.ok(
-      !/updateUrl\(\{\s*engine:/.test(spiderJs),
+      !/NexusUrl\.update\(\{\s*engine:/.test(spiderJs),
       'engine selection must remain client state (D13)',
     );
+    // Defensive — also forbid the legacy updateUrl shape (which the
+    // page no longer carries, but which a future regression could
+    // reintroduce).
+    assert.ok(
+      !/updateUrl\(\{\s*tab:/.test(spiderJs),
+      'tab state must remain client-only (D14) — legacy form too',
+    );
+    assert.ok(
+      !/updateUrl\(\{\s*engine:/.test(spiderJs),
+      'engine selection must remain client state (D13) — legacy form too',
+    );
+  });
+
+  it('rigs filter state writes through NexusUrl.update (replace, no push: true)', () => {
+    const writer = spiderJs.match(
+      /function writeRigFiltersToUrl\(\)[\s\S]*?(?=\n  function )/,
+    );
+    assert.ok(writer, 'writeRigFiltersToUrl should be defined');
+    assert.match(
+      writer[0],
+      /window\.NexusUrl\.update\(\{[\s\S]*?status:[\s\S]*?\}\s*\)/,
+      'rig filter writer must call NexusUrl.update without { push: true }',
+    );
+    assert.ok(
+      !/push:\s*true/.test(writer[0]),
+      'rig filter writes must use replaceState (D5 default) — no push: true',
+    );
+    // Each filter key the rigs page tracks must appear in the writer.
+    for (const key of ['status', "'writ-filter'", 'from', 'to', 'sort', 'dir']) {
+      assert.match(
+        writer[0],
+        new RegExp(`${key.replace(/'/g, "\\'")}\\s*:`),
+        `rig filter writer must include the ${key} key`,
+      );
+    }
+  });
+
+  it('readUrlState validates filter values and surfaces fail-loud errors (D6)', () => {
+    const reader = spiderJs.match(
+      /function readUrlState\(\)[\s\S]*?(?=\n  function )/,
+    );
+    assert.ok(reader, 'readUrlState should be defined');
+    // The reader must call showUrlError when validation fails.
+    assert.match(
+      reader[0],
+      /showUrlError\(/,
+      'readUrlState must surface validation errors via showUrlError',
+    );
+    // It must validate ?status= against the known status set.
+    assert.match(
+      reader[0],
+      /STATUS_VALUES\.indexOf/,
+      'readUrlState must validate ?status= against STATUS_VALUES',
+    );
+    assert.match(
+      reader[0],
+      /SORT_FIELDS\.indexOf/,
+      'readUrlState must validate ?sort= against SORT_FIELDS',
+    );
   });
 });
 

package/src/static/spider.js

@@ -77,33 +77,115 @@
   }
 
   // ── URL handling ───────────────────────────────────────────────────────
+  //
+  // All deep-linkable view state for this page rides on
+  // `window.NexusUrl` — the shared helper auto-injected by oculus's
+  // chrome pass. The earlier inline `currentUrlParams` / `updateUrl`
+  // copies are gone (commission moix23w5).
+  //
+  // URL keys for the rigs tab:
+  //   ?status=        running | completed | failed | cancelled
+  //                   (matches the server-side ?status= already sent
+  //                   to /api/rig/list per D8). Default '' (All).
+  //   ?writ-filter=   Substring filter against rig.writTitle / writId.
+  //                   Default ''.
+  //   ?from=          ISO date (yyyy-mm-dd). Inclusive lower bound.
+  //   ?to=            ISO date. Inclusive upper bound (compared with
+  //                   T23:59:59 suffix).
+  //   ?sort=          status | id | writId | createdAt
+  //                   Default 'createdAt'; omitted when default.
+  //   ?dir=           asc | desc.    Default 'desc'.
+  //   ?rig=ID         Detail deep-link; pushes (D5).
+  //
+  // Tab state (?tab=) and engine selection (?engine=) are deliberately
+  // NOT URL-tracked (D13 — narrow reading). The spider-ui tests assert
+  // those keys never appear; do not introduce them.
+
+  var SORT_FIELDS = ['status', 'id', 'writId', 'createdAt'];
+  var SORT_DIRS = ['asc', 'desc'];
+  var STATUS_VALUES = ['', 'running', 'completed', 'failed', 'cancelled'];
+
+  /** Append a fail-loud message to the URL-error banner (D6). */
+  function showUrlError(msg) {
+    var el = document.getElementById('url-error-banner');
+    if (!el) return;
+    var line = document.createElement('div');
+    line.textContent = msg;
+    el.appendChild(line);
+    el.style.display = 'block';
+  }
 
-  /**
-   * Read the current querystring as a `URLSearchParams`. Live snapshot —
-   * read at call time, never cached, so reasoning stays local.
-   */
-  function currentUrlParams() {
-    return new URLSearchParams(window.location.search);
+  function clearUrlErrors() {
+    var el = document.getElementById('url-error-banner');
+    if (!el) return;
+    el.innerHTML = '';
+    el.style.display = 'none';
+  }
+
+  /** Persist the current rigs-list filter state to the URL (replace, D5). */
+  function writeRigFiltersToUrl() {
+    var writFilter = (document.getElementById('writ-filter') || {}).value || '';
+    var dateFrom = (document.getElementById('date-from') || {}).value || '';
+    var dateTo = (document.getElementById('date-to') || {}).value || '';
+    window.NexusUrl.update({
+      status: currentStatusFilter === '' ? null : currentStatusFilter,
+      'writ-filter': writFilter === '' ? null : writFilter,
+      from: dateFrom === '' ? null : dateFrom,
+      to: dateTo === '' ? null : dateTo,
+      sort: sortField === 'createdAt' ? null : sortField,
+      dir: sortDir === 'desc' ? null : sortDir,
+    });
   }
 
   /**
-   * Apply the given key/value changes to the current querystring and
-   * `pushState` the result. Null/undefined/empty value deletes the key.
-   * Mirrors Ratchet's `updateUrl` (D9). Tab state and engine selection
-   * are deliberately NOT round-tripped through this helper (D13/D14).
+   * Read the URL filter state into module-level variables and return
+   * the deep-link rig id (if any). Validates each value against its
+   * known set; unknowns surface a fail-loud banner per D6 without
+   * applying the value.
    */
-  function updateUrl(changes) {
-    var params = currentUrlParams();
-    var keys = Object.keys(changes);
-    for (var i = 0; i < keys.length; i++) {
-      var key = keys[i];
-      var value = changes[key];
-      if (value === null || value === undefined || value === '') params.delete(key);
-      else params.set(key, value);
-    }
-    var qs = params.toString();
-    var next = window.location.pathname + (qs ? '?' + qs : '');
-    window.history.pushState({}, '', next);
+  function readUrlState() {
+    clearUrlErrors();
+    var params = window.NexusUrl.read();
+
+    var status = params.get('status');
+    if (status !== null) {
+      if (STATUS_VALUES.indexOf(status) !== -1) {
+        currentStatusFilter = status;
+      } else {
+        showUrlError('Unknown rig status "' + status + '". Expected one of: running, completed, failed, cancelled.');
+      }
+    }
+
+    var sort = params.get('sort');
+    if (sort !== null) {
+      if (SORT_FIELDS.indexOf(sort) !== -1) sortField = sort;
+      else showUrlError('Unknown sort column "' + sort + '". Expected one of: ' + SORT_FIELDS.join(', ') + '.');
+    }
+    var dir = params.get('dir');
+    if (dir !== null) {
+      if (SORT_DIRS.indexOf(dir) !== -1) sortDir = dir;
+      else showUrlError('Unknown sort direction "' + dir + '". Expected "asc" or "desc".');
+    }
+
+    return {
+      rigId: params.get('rig'),
+      writFilter: params.get('writ-filter'),
+      dateFrom: params.get('from'),
+      dateTo: params.get('to'),
+    };
+  }
+
+  /** Sync the toolbar UI to current filter state. */
+  function syncRigFilterUiFromState() {
+    var statusEl = document.getElementById('status-filter');
+    if (statusEl) statusEl.value = currentStatusFilter;
+    var params = window.NexusUrl.read();
+    var writEl = document.getElementById('writ-filter');
+    if (writEl) writEl.value = params.get('writ-filter') || '';
+    var fromEl = document.getElementById('date-from');
+    if (fromEl) fromEl.value = params.get('from') || '';
+    var toEl = document.getElementById('date-to');
+    if (toEl) toEl.value = params.get('to') || '';
   }
 
   // ── Utility ────────────────────────────────────────────────────────────
@@ -918,12 +1000,12 @@
         if (rig && rig.id) {
           showRigDetail(rig, { skipUrlPush: skipUrlPush });
         } else {
-          if (!skipUrlPush) updateUrl({ rig: id });
+          if (!skipUrlPush) window.NexusUrl.update({ rig: id }, { push: true });
           renderRigDetailNotFound(id);
         }
       })
       .catch(function () {
-        if (!skipUrlPush) updateUrl({ rig: id });
+        if (!skipUrlPush) window.NexusUrl.update({ rig: id }, { push: true });
         renderRigDetailNotFound(id);
       });
   }
@@ -937,8 +1019,8 @@
     // (writ-title anchor, rig-id anchor, future entry points, deep-link
     // init) emits ?rig=ID for free. The popstate-driven path passes
     // skipUrlPush=true to avoid double-pushing the URL the browser
-    // already updated.
-    if (!skipUrlPush) updateUrl({ rig: rig.id });
+    // already updated. Detail open is a navigation event (push: true).
+    if (!skipUrlPush) window.NexusUrl.update({ rig: rig.id }, { push: true });
 
     // Reset the session-log surface BEFORE any render (T7): hides the
     // section, clears the textarea, and nulls transcript state.
@@ -1618,7 +1700,7 @@
     // doing what they expect. We deliberately push instead of popping
     // history — the operator may have arrived directly at ?rig=ID with
     // no prior list-view entry to pop back to.
-    if (!skipUrlPush) updateUrl({ rig: null });
+    if (!skipUrlPush) window.NexusUrl.update({ rig: null }, { push: true });
   }
 
   // ── Config tab ─────────────────────────────────────────────────────────
@@ -1893,6 +1975,8 @@
     var statusFilter = document.getElementById('status-filter');
     if (statusFilter) {
       statusFilter.addEventListener('change', function () {
+        currentStatusFilter = statusFilter.value;
+        writeRigFiltersToUrl();
         fetchRigs(statusFilter.value);
       });
     }
@@ -1901,6 +1985,7 @@
     var writFilter = document.getElementById('writ-filter');
     if (writFilter) {
       writFilter.addEventListener('input', function () {
+        writeRigFiltersToUrl();
         renderRigList();
       });
     }
@@ -1909,10 +1994,16 @@
     var dateFrom = document.getElementById('date-from');
     var dateTo = document.getElementById('date-to');
     if (dateFrom) {
-      dateFrom.addEventListener('change', function () { renderRigList(); });
+      dateFrom.addEventListener('change', function () {
+        writeRigFiltersToUrl();
+        renderRigList();
+      });
     }
     if (dateTo) {
-      dateTo.addEventListener('change', function () { renderRigList(); });
+      dateTo.addEventListener('change', function () {
+        writeRigFiltersToUrl();
+        renderRigList();
+      });
     }
 
     // Refresh button
@@ -1937,6 +2028,7 @@
             sortField = field;
             sortDir = 'asc';
           }
+          writeRigFiltersToUrl();
           renderRigList();
         });
       })(headers[k]);
@@ -1948,29 +2040,33 @@
       backBtn.addEventListener('click', backToList);
     }
 
-    // Browser navigation (Back / Forward) — read ?rig=ID from the new
-    // URL and either open the matching detail (skipUrlPush=true so we
-    // don't push the URL the browser already updated) or return to the
-    // list. Pairs with the central push inside showRigDetail (D11/D12).
+    // Browser navigation (Back / Forward) — restore the FULL filter
+    // state and the ?rig= deep-link. Pairs with the central push
+    // inside showRigDetail (D11/D12). The popstate-driven path uses
+    // skipUrlPush so it never re-pushes the URL the browser already
+    // updated.
     window.addEventListener('popstate', function () {
-      var rigId = currentUrlParams().get('rig');
-      if (rigId) {
-        showRigDetailById(rigId, { skipUrlPush: true });
+      var state = readUrlState();
+      syncRigFilterUiFromState();
+      if (state.rigId) {
+        showRigDetailById(state.rigId, { skipUrlPush: true });
       } else {
         backToList({ skipUrlPush: true });
+        // Refresh the list with the restored filter set.
+        fetchRigs(currentStatusFilter);
       }
     });
 
-    // Initial load. Deep-link: ?rig=ID. The init path waits for the
-    // first rig list to land (so showRigDetailById can find the live
-    // rig in `rigs`) before opening the detail. A missing/deleted id
-    // falls through to renderRigDetailNotFound (D16) — the URL is
-    // preserved.
-    var initialRigId = currentUrlParams().get('rig');
-    fetchRigs('', {
+    // Initial load. Read the URL filter state and ?rig= deep-link
+    // BEFORE fetching the rig list so the server query already carries
+    // the correct ?status= filter. A missing/deleted ?rig= id falls
+    // through to renderRigDetailNotFound (D16) — the URL is preserved.
+    var initialState = readUrlState();
+    syncRigFilterUiFromState();
+    fetchRigs(currentStatusFilter, {
       onLoaded: function () {
-        if (initialRigId) {
-          showRigDetailById(initialRigId, { skipUrlPush: true });
+        if (initialState.rigId) {
+          showRigDetailById(initialState.rigId, { skipUrlPush: true });
         }
       },
     });