@shardworks/astrolabe-apparatus 0.1.274 → 0.1.275

package/dist/engines/plan-finalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-finalize.d.ts","sourceRoot":"","sources":["../../src/engines/plan-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,kCAAkC,CAAC;AACxG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAKzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAqB3C,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,YAAY,CA6ExF"}
+{"version":3,"file":"plan-finalize.d.ts","sourceRoot":"","sources":["../../src/engines/plan-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,kCAAkC,CAAC;AACxG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAKzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAmB3C,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,YAAY,CA6ExF"}

package/dist/engines/plan-finalize.js

@@ -38,14 +38,11 @@ const FRAMEWORK_EMITTER = 'framework';
  * installed (astrolabe declares clockworks in `recommends`, not
  * `requires`). Mirrors the lazy resolution `summon()` and the animator's
  * `tryResolveClockworks` use for `LoomApi` and `ClockworksApi`.
+ * Delegates to the framework's `tryApparatus<T>` primitive — the
+ * optional-dependency counterpart to `apparatus<T>`.
  */
 function tryResolveClockworks() {
-    try {
-        return guild().apparatus('clockworks');
-    }
-    catch {
-        return null;
-    }
+    return guild().tryApparatus('clockworks');
 }
 export function createPlanFinalizeEngine(getPlansBook) {
     return {

package/dist/engines/plan-finalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan-finalize.js","sourceRoot":"","sources":["../../src/engines/plan-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAG/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAEjE,8EAA8E;AAC9E,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAEtC;;;;;GAKG;AACH,SAAS,oBAAoB;IAC3B,IAAI,CAAC;QACH,OAAO,KAAK,EAAE,CAAC,SAAS,CAAgB,YAAY,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,YAAiC;IACxE,OAAO;QACL,EAAE,EAAE,yBAAyB;QAE7B,KAAK,CAAC,GAAG,CACP,MAA+B,EAC/B,QAA0B;YAE1B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAgB,CAAC;YACvC,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;YAE5B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,SAAS,MAAM,cAAc,CAAC,CAAC;YACjD,CAAC;YAED,kBAAkB;YAClB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CACb,0DAA0D,IAAI,CAAC,MAAM,eAAe,MAAM,IAAI,CAC/F,CAAC;YACJ,CAAC;YAED,uBAAuB;YACvB,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5D,MAAM,IAAI,KAAK,CACb,SAAS,MAAM,2DAA2D,CAC3E,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YAEvB,kEAAkE;YAClE,8DAA8D;YAC9D,0CAA0C;YAC1C,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;YAEpD,yDAAyD;YACzD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACrC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;gBACvB,MAAM,EAAE,WAAW;gBACnB,kBAAkB;gBAClB,SAAS,EAAE,GAAG;aACf,CAAC,CAAC;YAEH,iEAAiE;YACjE,kEAAkE;YAClE,gEAAgE;YAChE,6DAA6D;YAC7D,gCAAgC;YAChC,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,SAAS,GAAG,8BAA8B,EAAE,CAAC;gBACnD,IAAI,kBAAkB,GAAG,SAAS,EAAE,CAAC;oBACnC,MAAM,UAAU,GAAG,oBAAoB,EAAE,CAAC;oBAC1C,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;wBACxB,IAAI,CAAC;4BACH,MAAM,UAAU,CAAC,IAAI,CACnB,qCAAqC,EACrC,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,EAChD,iBAAiB,CAClB,CAAC;wBACJ,CAAC;wBAAC,OAAO,GAAG,EAAE,CAAC;4BACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;4BAChE,OAAO,CAAC,IAAI,CACV,iFAAiF,MAAM,EAAE,CAC1F,CAAC;wBACJ,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;YAED,OAAO;gBACL,MAAM,EAAE,WAAW;gBACnB,MAAM,EAAE,EAAE,IAAI,EAAE;aACjB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"plan-finalize.js","sourceRoot":"","sources":["../../src/engines/plan-finalize.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/pages/astrolabe/astrolabe.js

@@ -15,6 +15,37 @@
   var LIMIT = 20;
   var writTitleLookup = {};
 
+  // ── URL handling ───────────────────────────────────────────────────────
+
+  /**
+   * Read the current querystring as a `URLSearchParams`. Live snapshot
+   * — read at call time, never cached.
+   */
+  function currentUrlParams() {
+    return new URLSearchParams(window.location.search);
+  }
+
+  /**
+   * 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).
+   */
+  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);
+  }
+
   // ── Utility ────────────────────────────────────────────────────────────
 
   function esc(s) {
@@ -299,11 +330,41 @@
 
   // ── Detail View ────────────────────────────────────────────────────────
 
-  function showPlanDetail(plan) {
+  /**
+   * Render a "not found" empty state inside the plan detail view for a
+   * deep-linked id that does not resolve. Per D16 the URL param is
+   * preserved so the operator can recover (correct the id, hit Back).
+   * Replaces the legacy fall-back-to-list behaviour, which silently
+   * dropped the param and pretended the deep-link never happened.
+   */
+  function renderPlanDetailNotFound(planId) {
+    currentPlan = null;
+    listView.style.display = 'none';
+    detailView.style.display = '';
+    detailTitle.textContent = 'Plan not found';
+    metaCard.innerHTML =
+      '<div class="empty-state" style="padding:1.5rem">' +
+      'No plan with id <code>' + esc(planId) + '</code> exists. ' +
+      'It may have been deleted, or the id may be mistyped.</div>';
+    // Hide tab content / decisions table — they reference fields on a
+    // missing plan that would just render blanks.
+    var tabContent = document.getElementById('tab-content');
+    if (tabContent) tabContent.innerHTML = '';
+  }
+
+  function showPlanDetail(plan, opts) {
+    var skipUrlPush = !!(opts && opts.skipUrlPush);
     currentPlan = plan;
     listView.style.display = 'none';
     detailView.style.display = '';
 
+    // Centralised URL push — every entry path into showPlanDetail
+    // (row click, deep-link init, popstate-driven re-open) emits
+    // ?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 });
+
     detailTitle.textContent = 'Plan: ' + plan.id;
 
     // Metadata card
@@ -605,39 +666,67 @@
 
   // ── Navigation ─────────────────────────────────────────────────────────
 
-  function backToList() {
+  function backToList(opts) {
+    var skipUrlPush = !!(opts && opts.skipUrlPush);
     detailView.style.display = 'none';
     listView.style.display = '';
     currentPlan = null;
+    // 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 });
   }
 
   // ── Deep Link ──────────────────────────────────────────────────────────
 
-  function handleDeepLink() {
-    var params = new URLSearchParams(window.location.search);
-    var planId = params.get('plan');
+  /**
+   * Resolve `?plan=ID` to a detail view. Called on init and from the
+   * popstate handler. Both paths suppress the URL push (the browser
+   * already has the URL in place, or the deep-link landed already).
+   * A missing/deleted/mistyped id renders the not-found empty state
+   * (D16) — the URL param is left intact.
+   *
+   * `opts.fetchOnEmpty` selects what to do when no plan param is
+   * present. Init wants the list to be fetched (this is the page's
+   * normal load); popstate just wants to switch back to whatever was
+   * already rendered.
+   */
+  function handleDeepLink(opts) {
+    var fetchOnEmpty = !(opts && opts.fetchOnEmpty === false);
+    var planId = currentUrlParams().get('plan');
 
     if (planId) {
-      // Deep link: fetch and show the specific plan
       fetch('/api/plan/show?planId=' + encodeURIComponent(planId))
         .then(function (r) {
           if (!r.ok) throw new Error('HTTP ' + r.status);
           return r.json();
         })
         .then(function (plan) {
-          showPlanDetail(plan);
+          showPlanDetail(plan, { skipUrlPush: true });
         })
         .catch(function (err) {
           console.error('Deep-link plan not found:', planId, err);
-          // Fallback: show list view
-          fetchPlans(true);
+          // D16: surface the failure as a not-found empty state inside
+          // the detail panel; never silently rewrite the URL.
+          renderPlanDetailNotFound(planId);
         });
-    } else {
+    } else if (fetchOnEmpty) {
       fetchPlans(true);
+    } else {
+      // popstate to a no-?plan URL: just return to the list view
+      // without re-fetching.
+      backToList({ skipUrlPush: true });
     }
   }
 
   // ── Init ───────────────────────────────────────────────────────────────
 
+  // popstate listener — the browser updated the URL, so we re-run the
+  // deep-link routing without re-pushing. Pairs with the central push
+  // inside showPlanDetail (D11/D12).
+  window.addEventListener('popstate', function () {
+    handleDeepLink({ fetchOnEmpty: false });
+  });
+
   handleDeepLink();
 })();

package/pages/astrolabe/astrolabe.test.js

@@ -708,3 +708,101 @@ 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)', () => {
+    assert.match(
+      astrolabeJs,
+      /function currentUrlParams\(\)\s*\{[\s\S]*?new URLSearchParams\(window\.location\.search\)/,
+      'currentUrlParams reads window.location.search live',
+    );
+    assert.match(
+      astrolabeJs,
+      /function updateUrl\(changes\)\s*\{[\s\S]*?window\.history\.pushState/,
+      'updateUrl pushes via history.pushState',
+    );
+  });
+
+  it('showPlanDetail pushes ?plan=ID via the central updateUrl call (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*\}\)/,
+      '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)', () => {
+    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})',
+    );
+    assert.ok(
+      !/window\.history\.back\s*\(/.test(block[0]),
+      'backToList should never invoke history.back',
+    );
+  });
+
+  it('a popstate listener re-runs handleDeepLink without re-pushing the URL', () => {
+    assert.match(
+      astrolabeJs,
+      /window\.addEventListener\(\s*['"]popstate['"]/,
+      'astrolabe.js registers a popstate listener',
+    );
+    const block = astrolabeJs.match(
+      /addEventListener\(\s*['"]popstate['"][\s\S]*?\}\)/,
+    );
+    assert.ok(block, 'should find popstate handler body');
+    assert.match(
+      block[0],
+      /handleDeepLink\(\{\s*fetchOnEmpty:\s*false\s*\}\)/,
+      'popstate handler invokes handleDeepLink with fetchOnEmpty=false',
+    );
+  });
+
+  it('handleDeepLink renders a not-found state instead of falling back to the list (D16)', () => {
+    const block = astrolabeJs.match(
+      /function handleDeepLink\([\s\S]*?(?=\n {2}\/\/ ── Init)/,
+    );
+    assert.ok(block, 'should find handleDeepLink body');
+    assert.match(
+      block[0],
+      /renderPlanDetailNotFound\(planId\)/,
+      'handleDeepLink should render the not-found state on fetch failure',
+    );
+    // The deep-link calls into showPlanDetail with skipUrlPush so we
+    // don't double-push the URL the operator already arrived with.
+    assert.match(
+      block[0],
+      /showPlanDetail\(plan,\s*\{\s*skipUrlPush:\s*true\s*\}\)/,
+      'init / popstate path passes skipUrlPush=true into showPlanDetail',
+    );
+  });
+
+  it('renderPlanDetailNotFound preserves the URL param', () => {
+    const block = astrolabeJs.match(
+      /function renderPlanDetailNotFound\([\s\S]*?(?=\n {2}function )/,
+    );
+    assert.ok(block, 'should find renderPlanDetailNotFound body');
+    assert.ok(
+      !/updateUrl/.test(block[0]),
+      'renderPlanDetailNotFound must not rewrite the URL',
+    );
+    assert.match(
+      block[0],
+      /No plan with id/,
+      'renderPlanDetailNotFound surfaces a "not found" message',
+    );
+  });
+});