@shardworks/astrolabe-apparatus 0.1.280 → 0.1.281

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/astrolabe-apparatus",
-  "version": "0.1.280",
+  "version": "0.1.281",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -20,18 +20,18 @@
   },
   "dependencies": {
     "zod": "4.3.6",
-    "@shardworks/tools-apparatus": "0.1.280",
-    "@shardworks/clerk-apparatus": "0.1.280",
-    "@shardworks/spider-apparatus": "0.1.280",
-    "@shardworks/animator-apparatus": "0.1.280",
-    "@shardworks/fabricator-apparatus": "0.1.280",
-    "@shardworks/stacks-apparatus": "0.1.280",
-    "@shardworks/loom-apparatus": "0.1.280",
-    "@shardworks/clockworks-apparatus": "0.1.280"
+    "@shardworks/stacks-apparatus": "0.1.281",
+    "@shardworks/clerk-apparatus": "0.1.281",
+    "@shardworks/tools-apparatus": "0.1.281",
+    "@shardworks/spider-apparatus": "0.1.281",
+    "@shardworks/animator-apparatus": "0.1.281",
+    "@shardworks/clockworks-apparatus": "0.1.281",
+    "@shardworks/fabricator-apparatus": "0.1.281",
+    "@shardworks/loom-apparatus": "0.1.281"
   },
   "devDependencies": {
     "@types/node": "25.5.0",
-    "@shardworks/nexus-core": "0.1.280"
+    "@shardworks/nexus-core": "0.1.281"
   },
   "files": [
     "dist",

package/pages/astrolabe/astrolabe.js

@@ -16,34 +16,78 @@
   var writTitleLookup = {};
 
   // ── 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=        reading | analyzing | reviewing | writing |
+  //                   completed | failed
+  //                   Matches the server-side ?status= sent to
+  //                   /api/plan/list (D8). Default '' (All).
+  //   ?plan=ID        Detail deep-link; pushes (D5).
+  //
+  // Detail-tab state (inventory / scope / decisions / observations /
+  // spec) is deliberately NOT URL-tracked (D13 narrow reading). The
+  // astrolabe.test.js suite asserts no `?tab=` key is ever written;
+  // do not introduce one.
+
+  var STATUS_VALUES = ['', 'reading', 'analyzing', 'reviewing', 'writing', 'completed', 'failed'];
+
+  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.
-   */
-  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 list-page status filter to the URL (replace, D5). */
+  function writeStatusFilterToUrl() {
+    window.NexusUrl.update({
+      status: currentStatusFilter === '' ? null : currentStatusFilter,
+    });
   }
 
   /**
-   * 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 plan param shape (?plan=ID)
-   * is preserved verbatim — operators have URLs in the wild already
-   * (D10).
+   * Read URL state into module-level variables. Validates ?status=
+   * against STATUS_VALUES; unknowns surface a fail-loud banner per D6
+   * without applying. Returns the deep-link plan 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) {
+        currentStatusFilter = status;
+      } else {
+        showUrlError('Unknown plan status "' + status + '". Expected one of: reading, analyzing, reviewing, writing, completed, failed.');
+      }
+    }
+
+    return params.get('plan');
+  }
+
+  /** Sync the status-filter button row to the current filter state. */
+  function syncStatusFilterUiFromState() {
+    var btns = document.querySelectorAll('#status-filters .filter-btn');
+    for (var i = 0; i < btns.length; i++) {
+      var match = btns[i].getAttribute('data-status') === currentStatusFilter;
+      if (match) btns[i].classList.add('active-filter');
+      else btns[i].classList.remove('active-filter');
     }
-    var qs = params.toString();
-    var next = window.location.pathname + (qs ? '?' + qs : '');
-    window.history.pushState({}, '', next);
   }
 
   // ── Utility ────────────────────────────────────────────────────────────
@@ -205,6 +249,7 @@
           filterBtns[j].classList.remove('active-filter');
         }
         btn.classList.add('active-filter');
+        writeStatusFilterToUrl();
         fetchPlans(true);
       });
     })(filterBtns[fi]);
@@ -363,7 +408,7 @@
     // ?plan=ID for free. The popstate-driven path passes
     // skipUrlPush=true to avoid double-pushing the URL the browser
     // already updated.
-    if (!skipUrlPush) updateUrl({ plan: plan.id });
+    if (!skipUrlPush) window.NexusUrl.update({ plan: plan.id }, { push: true });
 
     detailTitle.textContent = 'Plan: ' + plan.id;
 
@@ -674,7 +719,7 @@
     // D11: push a clean URL — the operator's Forward button still does
     // what they expect, and we never pop history because they may have
     // arrived directly at ?plan=ID with no prior list-view entry.
-    if (!skipUrlPush) updateUrl({ plan: null });
+    if (!skipUrlPush) window.NexusUrl.update({ plan: null }, { push: true });
   }
 
   // ── Deep Link ──────────────────────────────────────────────────────────
@@ -693,7 +738,10 @@
    */
   function handleDeepLink(opts) {
     var fetchOnEmpty = !(opts && opts.fetchOnEmpty === false);
-    var planId = currentUrlParams().get('plan');
+    // Restore the status filter alongside the deep-link id so the
+    // filtered view round-trips through refresh and Back/Forward.
+    var planId = readUrlState();
+    syncStatusFilterUiFromState();
 
     if (planId) {
       fetch('/api/plan/show?planId=' + encodeURIComponent(planId))
@@ -713,9 +761,10 @@
     } else if (fetchOnEmpty) {
       fetchPlans(true);
     } else {
-      // popstate to a no-?plan URL: just return to the list view
-      // without re-fetching.
+      // popstate to a no-?plan URL: refresh the list with the
+      // restored filter and switch back to list view.
       backToList({ skipUrlPush: true });
+      fetchPlans(true);
     }
   }
 

package/pages/astrolabe/astrolabe.test.js

@@ -712,41 +712,50 @@ describe('astrolabe.js cost-panel rig lookup uses rig-for-writ', () => {
 // ── Deep-link URL state (?plan=ID) ──────────────────────────────────────
 
 describe('astrolabe.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(astrolabeJs),
+      'inline currentUrlParams must not be redeclared',
+    );
+    assert.ok(
+      !/function\s+updateUrl\s*\(/.test(astrolabeJs),
+      'inline updateUrl must not be redeclared',
+    );
     assert.match(
       astrolabeJs,
-      /function currentUrlParams\(\)\s*\{[\s\S]*?new URLSearchParams\(window\.location\.search\)/,
-      'currentUrlParams reads window.location.search live',
+      /window\.NexusUrl\.read\(\)/,
+      'astrolabe.js should read URL state via window.NexusUrl.read',
     );
     assert.match(
       astrolabeJs,
-      /function updateUrl\(changes\)\s*\{[\s\S]*?window\.history\.pushState/,
-      'updateUrl pushes via history.pushState',
+      /window\.NexusUrl\.update\(/,
+      'astrolabe.js should write URL state via window.NexusUrl.update',
     );
   });
 
-  it('showPlanDetail pushes ?plan=ID via the central updateUrl call (D12)', () => {
+  it('showPlanDetail pushes ?plan=ID via NexusUrl with push: true (D12)', () => {
     const block = astrolabeJs.match(
       /function showPlanDetail\(plan(?:, opts)?\)[\s\S]*?(?=\n {2}function )/,
     );
     assert.ok(block, 'should find showPlanDetail body');
     assert.match(
       block[0],
-      /updateUrl\(\{\s*plan:\s*plan\.id\s*\}\)/,
+      /window\.NexusUrl\.update\(\{\s*plan:\s*plan\.id\s*\}\s*,\s*\{\s*push:\s*true\s*\}\)/,
       'showPlanDetail should push ?plan=<plan.id> when not skipUrlPush',
     );
     assert.match(block[0], /skipUrlPush/, 'showPlanDetail accepts a skipUrlPush opt');
   });
 
-  it('backToList clears ?plan via updateUrl({plan: null}) — never pops history (D11)', () => {
+  it('backToList clears ?plan via NexusUrl with push: true — never pops history (D11)', () => {
     const block = astrolabeJs.match(
       /function backToList\((?:opts)?\)[\s\S]*?(?=\n {2}\/\/)/,
     );
     assert.ok(block, 'should find backToList body');
     assert.match(
       block[0],
-      /updateUrl\(\{\s*plan:\s*null\s*\}\)/,
-      'backToList should push a clean URL via updateUrl({plan: null})',
+      /window\.NexusUrl\.update\(\{\s*plan:\s*null\s*\}\s*,\s*\{\s*push:\s*true\s*\}\)/,
+      'backToList should push a clean URL via NexusUrl.update with plan: null',
     );
     assert.ok(
       !/window\.history\.back\s*\(/.test(block[0]),
@@ -796,7 +805,7 @@ describe('astrolabe.js — deep-link URL state', () => {
     );
     assert.ok(block, 'should find renderPlanDetailNotFound body');
     assert.ok(
-      !/updateUrl/.test(block[0]),
+      !/NexusUrl\.update/.test(block[0]),
       'renderPlanDetailNotFound must not rewrite the URL',
     );
     assert.match(
@@ -805,4 +814,52 @@ describe('astrolabe.js — deep-link URL state', () => {
       'renderPlanDetailNotFound surfaces a "not found" message',
     );
   });
+
+  it('list-page status filter writes through NexusUrl.update (replace, no push: true)', () => {
+    const writer = astrolabeJs.match(
+      /function writeStatusFilterToUrl\(\)[\s\S]*?(?=\n {2}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('readUrlState validates ?status= against STATUS_VALUES and surfaces fail-loud errors (D6)', () => {
+    const reader = astrolabeJs.match(
+      /function readUrlState\(\)[\s\S]*?(?=\n {2}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',
+    );
+  });
+
+  it('detail-tab state stays non-URL-tracked (D13 narrow reading)', () => {
+    // Astrolabe's detail tabs (inventory / scope / decisions /
+    // observations / spec) are deliberately NOT URL-tracked. Filter-
+    // shaped only — the tab affordance remains client-only state.
+    assert.ok(
+      !/NexusUrl\.update\(\{\s*tab:/.test(astrolabeJs),
+      'detail-tab state must remain client-only (D13)',
+    );
+    // Defensive — also forbid the legacy updateUrl shape.
+    assert.ok(
+      !/updateUrl\(\{\s*tab:/.test(astrolabeJs),
+      'detail-tab state must remain client-only (D13) — legacy form too',
+    );
+  });
 });

package/pages/astrolabe/index.html

@@ -8,6 +8,14 @@
 <body>
 <main style="padding: 24px;">
 
+  <!--
+    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="plan-list-view">
     <h2>Plans</h2>