@shardworks/clerk-apparatus 0.1.279 → 0.1.281

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/clerk-apparatus",
-  "version": "0.1.279",
+  "version": "0.1.281",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -24,12 +24,12 @@
   },
   "dependencies": {
     "zod": "4.3.6",
-    "@shardworks/stacks-apparatus": "0.1.279",
-    "@shardworks/tools-apparatus": "0.1.279"
+    "@shardworks/stacks-apparatus": "0.1.281",
+    "@shardworks/tools-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/pages/writs/index.html

@@ -77,6 +77,14 @@
   <h1>Writs</h1>
 
   <div id="writ-list-view">
+  <!--
+    URL-state validation banner. Surfaced when the page is loaded with a
+    URL filter value that does not match any known classification, type,
+    sort column, or sort direction (D6 fail-loud). Pages must not
+    silently fall back to a default — the operator copy-pasting a URL
+    needs honest feedback so they can recover.
+  -->
+  <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="card" style="margin-bottom: 16px;">
   <div class="toolbar" id="toolbar">
     <button class="btn btn--primary" id="btn-new-writ">New Writ</button>
@@ -221,33 +229,188 @@
     const DEPTH_CAP = 8;
 
     // ── 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, all client-side except `?writ=`, `?classification=`,
+    // and `?type=` which are also accepted by /api/writ/* endpoints:
+    //   ?classification= one of '' | 'initial' | 'active' | 'terminal'.
+    //                    Default '' (All); omitted when default (D4).
+    //   ?type=A&type=B   Repeated keys (D3). Omitted when every known
+    //                    type is selected (the default). Subset → emit
+    //                    each currently-selected type. The empty-set
+    //                    edge case collapses to default on round-trip
+    //                    (operators don't share empty list states).
+    //   ?q=              Search text. Omitted when empty.
+    //   ?sort=           One of phase | title | type | id | createdAt.
+    //                    Default 'createdAt'; omitted when default.
+    //   ?dir=            'asc' | 'desc'. Default 'desc'; omitted when
+    //                    default.
+    //   ?children=       'true' | 'false' (D7). Default true; omitted
+    //                    when default.
+    //   ?cancelled=      'true' | 'false'. Default false; omitted when
+    //                    default.
+    //   ?writ=ID         Detail deep-link; opening pushes (D5).
+
+    const SORT_COLS = new Set(['phase', 'title', 'type', 'id', 'createdAt']);
+    const SORT_DIRS = new Set(['asc', 'desc']);
+    const CLASSIFICATIONS = new Set(['', 'initial', 'active', 'terminal']);
+
+    /** Append a fail-loud message to the URL-error banner (D6). */
+    function showUrlError(msg) {
+      const el = document.getElementById('url-error-banner');
+      if (!el) return;
+      // Append rather than replace so multiple invalid params each get
+      // their own line — operators see every recovery hint at once.
+      const line = document.createElement('div');
+      line.textContent = msg;
+      el.appendChild(line);
+      el.style.display = 'block';
+    }
+
+    /** Clear the URL-error banner — used before a fresh validation pass. */
+    function clearUrlErrors() {
+      const el = document.getElementById('url-error-banner');
+      if (!el) return;
+      el.innerHTML = '';
+      el.style.display = 'none';
+    }
+
+    /**
+     * Apply current filter state to the URL via NexusUrl.update. Always
+     * a replace (D5 default) — filter changes do not push history
+     * entries. When a filter is at its declared default the
+     * corresponding key is omitted (D4). Type[] is omitted when every
+     * known type is selected (the operator-default).
+     */
+    function writeFiltersToUrl() {
+      const allKnown = knownTypes.length > 0 && knownTypes.every(t => currentType.has(t));
+      const noneSelected = currentType.size === 0;
+      const typeArray = (allKnown || noneSelected) ? null : [...currentType];
+      window.NexusUrl.update({
+        classification: currentClassification === '' ? null : currentClassification,
+        type: typeArray,
+        q: searchText === '' ? null : searchText,
+        sort: sortCol === 'createdAt' ? null : sortCol,
+        dir: sortDir === 'desc' ? null : sortDir,
+        children: showChildren === true ? null : false,
+        cancelled: showCancelled === false ? null : true,
+      });
+    }
 
     /**
-     * Read the current querystring as a `URLSearchParams`. A live snapshot —
-     * always read at call time, never cached, so reasoning stays local.
+     * Read the URL filter state into module-level variables. Validates
+     * each value against its known set and surfaces an error banner
+     * for any unknown value (D6 fail-loud). Returns the writ id, if
+     * any, so the caller can route into the detail view.
+     *
+     * Must be called after loadWritTypes() so knownTypes is populated
+     * and the type[] validation can fire.
      */
-    function currentUrlParams() {
-      return new URLSearchParams(window.location.search);
+    function readFiltersFromUrl() {
+      clearUrlErrors();
+      const params = window.NexusUrl.read();
+
+      // ── classification ────────────────────────────────────────────
+      const classification = params.get('classification');
+      if (classification !== null) {
+        if (CLASSIFICATIONS.has(classification)) {
+          currentClassification = classification;
+        } else {
+          showUrlError(`Unknown classification "${classification}". Expected one of: initial, active, terminal.`);
+        }
+      }
+
+      // ── type[] ─────────────────────────────────────────────────────
+      const typeValues = params.getAll('type');
+      if (typeValues.length > 0) {
+        const knownSet = new Set(knownTypes);
+        const unknown = typeValues.filter(t => !knownSet.has(t));
+        if (unknown.length > 0) {
+          for (const u of unknown) {
+            showUrlError(`Unknown writ type "${u}". The current type registry does not declare this name.`);
+          }
+        } else {
+          currentType = new Set(typeValues);
+        }
+      }
+      // Otherwise leave currentType at its default (set by buildTypeFilterBar to all known types).
+
+      // ── search text ────────────────────────────────────────────────
+      const q = params.get('q');
+      if (q !== null) searchText = q;
+
+      // ── sort ───────────────────────────────────────────────────────
+      const sort = params.get('sort');
+      if (sort !== null) {
+        if (SORT_COLS.has(sort)) {
+          sortCol = sort;
+        } else {
+          showUrlError(`Unknown sort column "${sort}". Expected one of: ${[...SORT_COLS].join(', ')}.`);
+        }
+      }
+      const dir = params.get('dir');
+      if (dir !== null) {
+        if (SORT_DIRS.has(dir)) {
+          sortDir = dir;
+        } else {
+          showUrlError(`Unknown sort direction "${dir}". Expected "asc" or "desc".`);
+        }
+      }
+
+      // ── boolean toggles ───────────────────────────────────────────
+      const childrenRaw = params.get('children');
+      if (childrenRaw !== null) {
+        if (childrenRaw === 'true') showChildren = true;
+        else if (childrenRaw === 'false') showChildren = false;
+        else showUrlError(`Invalid children value "${childrenRaw}". Expected "true" or "false".`);
+      }
+      const cancelledRaw = params.get('cancelled');
+      if (cancelledRaw !== null) {
+        if (cancelledRaw === 'true') showCancelled = true;
+        else if (cancelledRaw === 'false') showCancelled = false;
+        else showUrlError(`Invalid cancelled value "${cancelledRaw}". Expected "true" or "false".`);
+      }
+
+      return params.get('writ');
     }
 
     /**
-     * Apply the given key/value changes to the current querystring and
-     * `pushState` the result, preserving any unrelated params already
-     * present. A null/undefined/empty value deletes the key. Mirrors
-     * Ratchet's `updateUrl` (D9). Always pushes — `back-to-list` does
-     * `updateUrl({writ: null})` so the operator's Back button returns to
-     * whatever page they came from rather than collapsing inside the
-     * page's own history (D11).
+     * Sync the toolbar UI to current filter state. Called after URL
+     * restore (init / popstate) so visible button fills, the search
+     * input, and the type-filter bar match what the URL describes.
      */
-    function updateUrl(changes) {
-      const params = currentUrlParams();
-      for (const [key, value] of Object.entries(changes)) {
-        if (value === null || value === undefined || value === '') params.delete(key);
-        else params.set(key, value);
-      }
-      const qs = params.toString();
-      const next = window.location.pathname + (qs ? '?' + qs : '');
-      window.history.pushState({}, '', next);
+    function syncFilterUiFromState() {
+      // Classification buttons
+      document.querySelectorAll('.filter-btn[data-classification]').forEach(btn => {
+        btn.classList.toggle('active-filter', btn.dataset.classification === currentClassification);
+      });
+
+      // Type-filter pills
+      const bar = document.getElementById('type-filter-bar');
+      if (bar) {
+        const allBtn = bar.querySelector('.type-filter-btn[data-type=""]');
+        const typeBtns = [...bar.querySelectorAll('.type-filter-btn:not([data-type=""])')];
+        const allTypeNames = typeBtns.map(b => b.dataset.type);
+        const allActive = allTypeNames.length > 0 && allTypeNames.every(t => currentType.has(t));
+        if (allBtn) allBtn.classList.toggle('active-filter', allActive);
+        typeBtns.forEach(btn => {
+          btn.classList.toggle('active-filter', currentType.has(btn.dataset.type));
+        });
+      }
+
+      // Search input
+      const searchInput = document.getElementById('search-input');
+      if (searchInput && searchInput.value !== searchText) searchInput.value = searchText;
+
+      // Toggles
+      const childrenBtn = document.getElementById('btn-toggle-children');
+      if (childrenBtn) childrenBtn.classList.toggle('active-filter', showChildren);
+      const cancelledBtn = document.getElementById('btn-toggle-cancelled');
+      if (cancelledBtn) cancelledBtn.classList.toggle('active-filter', showCancelled);
     }
 
     // ── Helpers ────────────────────────────────────────────────────────
@@ -1451,7 +1614,7 @@
         writ = await api('GET', '/api/writ/show?id=' + encodeURIComponent(id));
       } catch (e) {
         console.error('Failed to load writ detail:', e);
-        if (!skipUrlPush) updateUrl({ writ: id });
+        if (!skipUrlPush) window.NexusUrl.update({ writ: id }, { push: true });
         renderDetailNotFound(id);
         return;
       }
@@ -1472,8 +1635,9 @@
 
       // Centralised URL push — every callsite into showWritDetail emits
       // ?writ=ID for free, except the popstate-driven path which would
-      // otherwise re-push the current URL.
-      if (!skipUrlPush) updateUrl({ writ: id });
+      // otherwise re-push the current URL. Detail open is a navigation
+      // event (pushes), per the D5 push-vs-replace split.
+      if (!skipUrlPush) window.NexusUrl.update({ writ: id }, { push: true });
 
       // Toggle views
       document.getElementById('writ-list-view').style.display = 'none';
@@ -1505,15 +1669,15 @@
     }
 
     /** Switch back from the detail view to the list view. Centralised so
-     *  the URL clear (`updateUrl({writ: null})`) and the DOM toggle stay
-     *  paired. Per D11 we never call `history.back()` — clicking "Back to
-     *  list" pushes a clean URL so the operator's forward button keeps
-     *  doing what they expect. */
+     *  the URL clear (`{ writ: null }`) and the DOM toggle stay paired.
+     *  Per D11 we never call `history.back()` — clicking "Back to list"
+     *  pushes a clean URL so the operator's forward button keeps doing
+     *  what they expect. */
     function showWritList(opts) {
       const skipUrlPush = !!(opts && opts.skipUrlPush);
       document.getElementById('writ-detail-view').style.display = 'none';
       document.getElementById('writ-list-view').style.display = '';
-      if (!skipUrlPush) updateUrl({ writ: null });
+      if (!skipUrlPush) window.NexusUrl.update({ writ: null }, { push: true });
     }
 
     // ── Data loading ────────────────────────────────────────────────────
@@ -1848,6 +2012,7 @@
       document.querySelectorAll('.filter-btn[data-classification]').forEach(btn => {
         btn.classList.toggle('active-filter', btn.dataset.classification === classification);
       });
+      writeFiltersToUrl();
       loadWrits(true);
     }
 
@@ -1884,6 +2049,7 @@
         btn.classList.toggle('active-filter', currentType.has(btn.dataset.type));
       });
 
+      writeFiltersToUrl();
       loadWrits(true);
     }
 
@@ -1901,16 +2067,17 @@
     document.getElementById('btn-refresh').addEventListener('click', () => loadWrits(true));
 
     document.getElementById('back-btn').addEventListener('click', () => {
-      // D11: push a clean URL via showWritList → updateUrl, never call
-      // history.back(). Survives deep-link entries (the operator may have
-      // arrived directly at ?writ=ID with no prior list-view entry to
-      // pop back to), and keeps Forward navigation predictable.
+      // D11: push a clean URL via showWritList → NexusUrl.update, never
+      // call history.back(). Survives deep-link entries (the operator
+      // may have arrived directly at ?writ=ID with no prior list-view
+      // entry to pop back to), and keeps Forward navigation predictable.
       showWritList();
     });
 
     document.getElementById('btn-toggle-children').addEventListener('click', () => {
       showChildren = !showChildren;
       document.getElementById('btn-toggle-children').classList.toggle('active-filter', showChildren);
+      writeFiltersToUrl();
       renderTable();
     });
 
@@ -1920,6 +2087,7 @@
       // cancelled rows when the toggle is off.
       showCancelled = !showCancelled;
       document.getElementById('btn-toggle-cancelled').classList.toggle('active-filter', showCancelled);
+      writeFiltersToUrl();
       renderTable();
     });
 
@@ -1937,6 +2105,7 @@
 
     document.getElementById('search-input').addEventListener('input', e => {
       searchText = e.target.value;
+      writeFiltersToUrl();
       renderTable();
     });
 
@@ -1949,6 +2118,7 @@
           sortCol = col;
           sortDir = 'asc';
         }
+        writeFiltersToUrl();
         renderTable();
       });
     });
@@ -1957,18 +2127,25 @@
 
     /**
      * Reflect browser navigation (Back / Forward) into the page's view
-     * state. The popstate handler reads `?writ=` from the new URL and
-     * either shows the matching detail (without re-pushing the URL,
-     * which the browser has already done) or returns to the list. This
-     * pairs with the central push inside showWritDetail so the
-     * round-trip stays balanced (D11/D12).
+     * state. The popstate handler now restores the full filter state in
+     * addition to the detail-id state — Back from a deep-linked
+     * filtered URL must reproduce the original filtered view, not just
+     * its detail open/close axis (commission moix23w5).
+     *
+     * The browser has already updated the URL by the time popstate
+     * fires, so showWritDetail / showWritList run with skipUrlPush; the
+     * filter restore reads from `window.location.search` directly via
+     * readFiltersFromUrl and never writes back.
      */
     window.addEventListener('popstate', () => {
-      const writId = currentUrlParams().get('writ');
+      const writId = readFiltersFromUrl();
+      syncFilterUiFromState();
       if (writId) {
         showWritDetail(writId, { skipUrlPush: true });
       } else {
         showWritList({ skipUrlPush: true });
+        // Refresh the list with the restored filter state.
+        loadWrits(true);
       }
     });
 
@@ -1976,12 +2153,19 @@
     loadCodexes();
     loadLinkKinds();
 
-    // Deep-link: ?writ=ID
+    // Deep-link: ?writ=ID and filter state
     (async function () {
-      // Load writ types first so currentType default is set before fetching writs
+      // Load writ types first so currentType default is set and known
+      // type names are populated — the URL-restore step needs them to
+      // validate ?type= against the registry.
       await loadWritTypes();
 
-      var writId = currentUrlParams().get('writ');
+      // Read URL filter state AFTER buildTypeFilterBar (inside
+      // loadWritTypes) so default-fill does not clobber URL-restored
+      // selections. readFiltersFromUrl validates each value and routes
+      // unknowns to the fail-loud banner per D6.
+      var writId = readFiltersFromUrl();
+      syncFilterUiFromState();
 
       await loadWrits(true);
 

package/pages/writs/writs-hierarchy.test.js

@@ -1405,17 +1405,16 @@ describe('Deep descendant rendering in detail view', () => {
   });
 });
 
-describe('URL deep-link helpers (currentUrlParams + updateUrl + popstate cycle)', () => {
-  // Mirrors the URL helpers in index.html. The page IIFE reads from
-  // `window.location.search` and pushes via `window.history.pushState`;
-  // here we test the shape of those interactions by injecting a fake
-  // window. Keeping these tests beside the rest of the page logic locks
-  // in the contract that:
-  //   - showWritDetail pushes ?writ=ID
-  //   - showWritList clears ?writ
-  //   - skipUrlPush suppresses the push (the popstate-driven path)
-  //   - the popstate handler reads ?writ from the new URL and routes
-  //     into showWritDetail (skipUrlPush) or showWritList (skipUrlPush)
+describe('URL deep-link contract (window.NexusUrl + filter state + popstate cycle)', () => {
+  // The page now relies on the shared `window.NexusUrl` helper that
+  // oculus auto-injects. The inline `currentUrlParams` / `updateUrl`
+  // copies were removed in commission moix23w5; the source of truth
+  // for these tests is `packages/plugins/oculus/src/static/nexus-url.js`.
+  //
+  // We model the page's contract directly: detail open pushes a new
+  // history entry, filter changes replace, and the popstate-driven
+  // path uses skipUrlPush so it never re-pushes.
+
   function makeWindow(initialSearch) {
     const w = {
       location: {
@@ -1424,10 +1423,15 @@ describe('URL deep-link helpers (currentUrlParams + updateUrl + popstate cycle)'
       },
       history: {
         pushed: [],
-        pushState(state, _title, url) {
+        replaced: [],
+        pushState(_state, _title, url) {
           this.pushed.push(url);
-          // Reflect the push back into location so subsequent reads
-          // see the new querystring — matching real browser behaviour.
+          const idx = url.indexOf('?');
+          w.location.search = idx === -1 ? '' : url.slice(idx);
+          w.location.pathname = idx === -1 ? url : url.slice(0, idx);
+        },
+        replaceState(_state, _title, url) {
+          this.replaced.push(url);
           const idx = url.indexOf('?');
           w.location.search = idx === -1 ? '' : url.slice(idx);
           w.location.pathname = idx === -1 ? url : url.slice(0, idx);
@@ -1435,62 +1439,107 @@ describe('URL deep-link helpers (currentUrlParams + updateUrl + popstate cycle)'
       },
       _popstate: null,
       addEventListener(name, fn) { if (name === 'popstate') this._popstate = fn; },
+      removeEventListener() {},
     };
     return w;
   }
 
-  function makeUrlHelpers(w) {
-    function currentUrlParams() {
-      return new URLSearchParams(w.location.search);
+  /** Mount NexusUrl into a fake window by inlining its IIFE shape. */
+  function mountNexusUrl(w) {
+    function read() { return new URLSearchParams(w.location.search); }
+    function isEmpty(v) {
+      if (v === null || v === undefined) return true;
+      if (Array.isArray(v)) return v.length === 0;
+      if (v === '') return true;
+      return false;
     }
-    function updateUrl(changes) {
-      const params = currentUrlParams();
-      for (const [key, value] of Object.entries(changes)) {
-        if (value === null || value === undefined || value === '') params.delete(key);
-        else params.set(key, value);
+    function applyChange(p, k, v) {
+      if (isEmpty(v)) { p.delete(k); return; }
+      if (Array.isArray(v)) {
+        p.delete(k);
+        for (const x of v) {
+          if (x === null || x === undefined || x === '') continue;
+          p.append(k, String(x));
+        }
+        return;
       }
-      const qs = params.toString();
-      const next = w.location.pathname + (qs ? '?' + qs : '');
-      w.history.pushState({}, '', next);
+      if (typeof v === 'boolean') { p.set(k, v ? 'true' : 'false'); return; }
+      p.set(k, String(v));
     }
-    return { currentUrlParams, updateUrl };
+    w.NexusUrl = {
+      read,
+      update(changes, opts) {
+        const p = read();
+        for (const k of Object.keys(changes ?? {})) applyChange(p, k, changes[k]);
+        const qs = p.toString();
+        const next = w.location.pathname + (qs ? '?' + qs : '');
+        if (opts && opts.push) w.history.pushState({}, '', next);
+        else w.history.replaceState({}, '', next);
+        return p;
+      },
+    };
   }
 
-  it('updateUrl({writ: id}) pushes ?writ=ID onto a clean URL', () => {
+  it('detail open pushes ?writ=ID (push: true)', () => {
     const w = makeWindow();
-    const { updateUrl } = makeUrlHelpers(w);
-    updateUrl({ writ: 'w-abc' });
+    mountNexusUrl(w);
+    w.NexusUrl.update({ writ: 'w-abc' }, { push: true });
     assert.deepEqual(w.history.pushed, ['/pages/writs/?writ=w-abc']);
+    assert.equal(w.history.replaced.length, 0);
   });
 
-  it('updateUrl({writ: null}) clears the param while preserving others', () => {
+  it('back-to-list pushes a clean URL (writ: null clears the key)', () => {
     const w = makeWindow('?writ=w-old&keep=me');
-    const { updateUrl } = makeUrlHelpers(w);
-    updateUrl({ writ: null });
-    assert.equal(w.history.pushed.length, 1);
-    assert.equal(w.history.pushed[0], '/pages/writs/?keep=me');
+    mountNexusUrl(w);
+    w.NexusUrl.update({ writ: null }, { push: true });
+    assert.deepEqual(w.history.pushed, ['/pages/writs/?keep=me']);
+  });
+
+  it('filter changes replace, never push (D5)', () => {
+    const w = makeWindow();
+    mountNexusUrl(w);
+    w.NexusUrl.update({ classification: 'active' });
+    w.NexusUrl.update({ q: 'hello' });
+    w.NexusUrl.update({ children: false });
+    assert.equal(w.history.pushed.length, 0, 'filter changes must not push');
+    assert.equal(w.history.replaced.length, 3);
+    assert.equal(w.location.search, '?classification=active&q=hello&children=false');
+  });
+
+  it('omit-defaults clears keys when set to default (D4)', () => {
+    const w = makeWindow('?classification=active&q=hello&children=false');
+    mountNexusUrl(w);
+    w.NexusUrl.update({ classification: null, q: null, children: null });
+    assert.equal(w.location.search, '');
+  });
+
+  it('repeated-keys array encoding for type filter (D3)', () => {
+    const w = makeWindow();
+    mountNexusUrl(w);
+    w.NexusUrl.update({ type: ['mandate', 'bug'] });
+    const params = new URLSearchParams(w.location.search);
+    assert.deepEqual(params.getAll('type'), ['mandate', 'bug']);
   });
 
-  it('updateUrl percent-encodes ids that include special characters', () => {
+  it('boolean encoding uses true/false strings (D7)', () => {
     const w = makeWindow();
-    const { updateUrl } = makeUrlHelpers(w);
-    updateUrl({ writ: 'w with spaces' });
-    // URLSearchParams encodes spaces as `+`; either form is valid in a
-    // querystring, but the regex below pins what URLSearchParams
-    // actually emits so wording drift breaks the suite.
-    assert.equal(w.history.pushed[0], '/pages/writs/?writ=w+with+spaces');
+    mountNexusUrl(w);
+    w.NexusUrl.update({ children: false, cancelled: true });
+    const params = new URLSearchParams(w.location.search);
+    assert.equal(params.get('children'), 'false');
+    assert.equal(params.get('cancelled'), 'true');
   });
 
   it('a full select → back-to-list → select cycle pushes the right URL sequence', () => {
     const w = makeWindow();
-    const { updateUrl } = makeUrlHelpers(w);
+    mountNexusUrl(w);
 
     // Operator clicks into a writ → showWritDetail pushes ?writ=
-    updateUrl({ writ: 'w-1' });
+    w.NexusUrl.update({ writ: 'w-1' }, { push: true });
     // Back to list → showWritList clears ?writ=
-    updateUrl({ writ: null });
+    w.NexusUrl.update({ writ: null }, { push: true });
     // Operator opens another writ
-    updateUrl({ writ: 'w-2' });
+    w.NexusUrl.update({ writ: 'w-2' }, { push: true });
 
     assert.deepEqual(w.history.pushed, [
       '/pages/writs/?writ=w-1',
@@ -1501,18 +1550,13 @@ describe('URL deep-link helpers (currentUrlParams + updateUrl + popstate cycle)'
 
   it('popstate-driven path does not push (the browser already updated the URL)', () => {
     const w = makeWindow('?writ=w-1');
-    const { currentUrlParams, updateUrl } = makeUrlHelpers(w);
+    mountNexusUrl(w);
 
-    // Simulate the popstate dispatch: the page reads ?writ from the
-    // current URL and calls showWritDetail with skipUrlPush=true. We
-    // model showWritDetail's URL-push branch here as "if not
-    // skipUrlPush, updateUrl({writ: id})" — see the index.html
-    // implementation. The expected behaviour is zero pushes.
     function simulateShowWritDetail(id, skipUrlPush) {
-      if (!skipUrlPush) updateUrl({ writ: id });
+      if (!skipUrlPush) w.NexusUrl.update({ writ: id }, { push: true });
     }
     function simulateShowWritList(skipUrlPush) {
-      if (!skipUrlPush) updateUrl({ writ: null });
+      if (!skipUrlPush) w.NexusUrl.update({ writ: null }, { push: true });
     }
 
     // Forward to detail (programmatic, normal) — pushes once.
@@ -1533,25 +1577,33 @@ describe('URL deep-link helpers (currentUrlParams + updateUrl + popstate cycle)'
     assert.equal(w.history.pushed[1], '/pages/writs/');
   });
 
-  it('popstate handler reads ?writ from the new URL (round-trip simulation)', () => {
+  it('popstate handler reads ?writ from the new URL and restores filter state', () => {
     const w = makeWindow();
-    const { currentUrlParams, updateUrl } = makeUrlHelpers(w);
+    mountNexusUrl(w);
 
-    // Track which view the page would be showing.
+    // Track which view the page would be showing AND the filter state.
     let view = 'list';
     let detailId = null;
+    let appliedClassification = '';
+    let appliedSearch = '';
     function showWritDetail(id, opts) {
       view = 'detail';
       detailId = id;
-      if (!(opts && opts.skipUrlPush)) updateUrl({ writ: id });
+      if (!(opts && opts.skipUrlPush)) w.NexusUrl.update({ writ: id }, { push: true });
     }
     function showWritList(opts) {
       view = 'list';
       detailId = null;
-      if (!(opts && opts.skipUrlPush)) updateUrl({ writ: null });
+      if (!(opts && opts.skipUrlPush)) w.NexusUrl.update({ writ: null }, { push: true });
+    }
+    function readFilters() {
+      const p = w.NexusUrl.read();
+      appliedClassification = p.get('classification') ?? '';
+      appliedSearch = p.get('q') ?? '';
+      return p.get('writ');
     }
     function popstate() {
-      const id = currentUrlParams().get('writ');
+      const id = readFilters();
       if (id) showWritDetail(id, { skipUrlPush: true });
       else showWritList({ skipUrlPush: true });
     }
@@ -1563,21 +1615,158 @@ describe('URL deep-link helpers (currentUrlParams + updateUrl + popstate cycle)'
     assert.equal(detailId, 'w-1');
     assert.equal(w.location.search, '?writ=w-1');
 
-    // Browser Back → URL would revert; simulate the browser flipping
-    // the URL state back to the prior entry, then dispatching popstate.
-    w.location.search = '';
+    // Browser Back to a filtered list view (?classification=active&q=foo)
+    w.location.search = '?classification=active&q=foo';
     w._popstate({});
     assert.equal(view, 'list', 'popstate to list-view');
     assert.equal(detailId, null);
+    assert.equal(appliedClassification, 'active', 'classification filter restored from URL');
+    assert.equal(appliedSearch, 'foo', 'search text restored from URL');
     // No additional pushes from the popstate-driven render.
     assert.equal(w.history.pushed.length, 1);
+  });
+});
 
-    // Browser Forward → URL flips forward; popstate fires again.
-    w.location.search = '?writ=w-1';
-    w._popstate({});
-    assert.equal(view, 'detail');
-    assert.equal(detailId, 'w-1');
-    assert.equal(w.history.pushed.length, 1, 'forward popstate still does not push');
+describe('Clerk writs URL state — filter restore from initial URL', () => {
+  // Mirrors the page's readFiltersFromUrl logic. Asserts:
+  //   (a) changing a filter writes the expected URL key with the
+  //       expected value (covered by the URL-helper tests above),
+  //   (b) initial load with the URL key present applies the filter,
+  //   (c) popstate restoration re-applies the filter (covered above).
+  // This block focuses on the (b) case for each filter key.
+
+  /**
+   * Distilled mirror of readFiltersFromUrl in index.html. Returns the
+   * filter state derived from a query string. Validation errors (D6
+   * fail-loud) are returned as a `errors` list — the page surfaces
+   * them in a top-of-page banner, but here we just assert the shape.
+   */
+  function readFiltersFromUrl(search, knownTypes) {
+    const SORT_COLS = new Set(['phase', 'title', 'type', 'id', 'createdAt']);
+    const SORT_DIRS = new Set(['asc', 'desc']);
+    const CLASSIFICATIONS = new Set(['', 'initial', 'active', 'terminal']);
+    const params = new URLSearchParams(search);
+
+    const errors = [];
+    let classification = '';
+    let currentType = new Set(knownTypes);
+    let q = '';
+    let sortCol = 'createdAt';
+    let sortDir = 'desc';
+    let showChildren = true;
+    let showCancelled = false;
+
+    const c = params.get('classification');
+    if (c !== null) {
+      if (CLASSIFICATIONS.has(c)) classification = c;
+      else errors.push(`classification: "${c}"`);
+    }
+    const types = params.getAll('type');
+    if (types.length > 0) {
+      const known = new Set(knownTypes);
+      const unknown = types.filter(t => !known.has(t));
+      if (unknown.length > 0) errors.push(...unknown.map(u => `type: "${u}"`));
+      else currentType = new Set(types);
+    }
+    const queryText = params.get('q');
+    if (queryText !== null) q = queryText;
+    const sort = params.get('sort');
+    if (sort !== null) {
+      if (SORT_COLS.has(sort)) sortCol = sort;
+      else errors.push(`sort: "${sort}"`);
+    }
+    const dir = params.get('dir');
+    if (dir !== null) {
+      if (SORT_DIRS.has(dir)) sortDir = dir;
+      else errors.push(`dir: "${dir}"`);
+    }
+    const ch = params.get('children');
+    if (ch !== null) {
+      if (ch === 'true') showChildren = true;
+      else if (ch === 'false') showChildren = false;
+      else errors.push(`children: "${ch}"`);
+    }
+    const cn = params.get('cancelled');
+    if (cn !== null) {
+      if (cn === 'true') showCancelled = true;
+      else if (cn === 'false') showCancelled = false;
+      else errors.push(`cancelled: "${cn}"`);
+    }
+
+    return { classification, currentType, q, sortCol, sortDir, showChildren, showCancelled, errors };
+  }
+
+  it('initial load with ?classification=active applies the classification filter', () => {
+    const s = readFiltersFromUrl('?classification=active', ['mandate', 'bug']);
+    assert.equal(s.classification, 'active');
+    assert.equal(s.errors.length, 0);
+  });
+
+  it('initial load with ?type=mandate&type=bug applies the type filter', () => {
+    const s = readFiltersFromUrl('?type=mandate&type=bug', ['mandate', 'bug', 'task']);
+    assert.deepEqual(s.currentType, new Set(['mandate', 'bug']));
+    assert.equal(s.errors.length, 0);
+  });
+
+  it('initial load with ?q=hello applies the search text', () => {
+    const s = readFiltersFromUrl('?q=hello', ['mandate']);
+    assert.equal(s.q, 'hello');
+  });
+
+  it('initial load with ?sort=title&dir=asc applies sort col + direction', () => {
+    const s = readFiltersFromUrl('?sort=title&dir=asc', ['mandate']);
+    assert.equal(s.sortCol, 'title');
+    assert.equal(s.sortDir, 'asc');
+  });
+
+  it('initial load with ?children=false applies the children toggle', () => {
+    const s = readFiltersFromUrl('?children=false', ['mandate']);
+    assert.equal(s.showChildren, false);
+  });
+
+  it('initial load with ?cancelled=true applies the cancelled toggle', () => {
+    const s = readFiltersFromUrl('?cancelled=true', ['mandate']);
+    assert.equal(s.showCancelled, true);
+  });
+
+  it('absent keys leave each filter at its declared default (D4)', () => {
+    const s = readFiltersFromUrl('', ['mandate', 'bug']);
+    assert.equal(s.classification, '');
+    assert.deepEqual(s.currentType, new Set(['mandate', 'bug']));
+    assert.equal(s.q, '');
+    assert.equal(s.sortCol, 'createdAt');
+    assert.equal(s.sortDir, 'desc');
+    assert.equal(s.showChildren, true);
+    assert.equal(s.showCancelled, false);
+    assert.equal(s.errors.length, 0);
+  });
+
+  it('fail-loud — invalid classification surfaces an error and does not fall back silently (D6)', () => {
+    const s = readFiltersFromUrl('?classification=bogus', ['mandate']);
+    assert.equal(s.errors.length, 1);
+    assert.match(s.errors[0], /classification.*bogus/);
+    // The default value stays at '' — but the error must be surfaced.
+    assert.equal(s.classification, '');
+  });
+
+  it('fail-loud — unknown type surfaces an error', () => {
+    const s = readFiltersFromUrl('?type=bogus', ['mandate']);
+    assert.equal(s.errors.length, 1);
+    assert.match(s.errors[0], /type.*bogus/);
+  });
+
+  it('fail-loud — invalid sort column / direction', () => {
+    const s = readFiltersFromUrl('?sort=banana&dir=sideways', ['mandate']);
+    assert.equal(s.errors.length, 2);
+    assert.ok(s.errors.some(e => /sort.*banana/.test(e)));
+    assert.ok(s.errors.some(e => /dir.*sideways/.test(e)));
+  });
+
+  it('fail-loud — invalid boolean values', () => {
+    const s = readFiltersFromUrl('?children=maybe&cancelled=perhaps', ['mandate']);
+    assert.equal(s.errors.length, 2);
+    assert.ok(s.errors.some(e => /children.*maybe/.test(e)));
+    assert.ok(s.errors.some(e => /cancelled.*perhaps/.test(e)));
   });
 });