@shardworks/spider-apparatus 0.1.235 → 0.1.237

package/package.json

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

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

@@ -20,54 +20,82 @@ const indexHtml = readFileSync(resolve(__dirname, 'index.html'), 'utf-8');
 // ── Rig list row structure ──────────────────────────────────────────────
 
 describe('spider.js rig list row HTML', () => {
+  // After the keyed in-place refactor, rig rows are assembled by
+  // createRigRow via document.createElement rather than an HTML template.
+  // These assertions pin the same invariants against the new function
+  // body: both writ-title and rig-id cells are built as rig-link anchors,
+  // and the writ-title cell is never a plain <td> of text.
+  const createRigRowMatch = spiderJs.match(
+    /function createRigRow\(rig\)[\s\S]*?return tr;\s*\}/,
+  );
+  const createRigRowBody = createRigRowMatch ? createRigRowMatch[0] : '';
+
   it('renders the writ-title cell as a rig-link anchor', () => {
-    // The row template should contain a <td> with a rig-link anchor for the
-    // writ title (the second <td> in each row).  We match the template
-    // fragment that builds the writ-title cell.
-    const writTitleCellPattern =
-      /<td><a class="rig-link" href="#" data-rig-id="[^"]*"\s*>\s*'\s*\+\s*esc\(writTitle\)/;
+    // createRigRow builds a dedicated anchor for the writ title with
+    // class 'rig-link' and copies data-rig-id across to it.
+    assert.ok(createRigRowBody, 'should find createRigRow body');
     assert.match(
-      spiderJs,
-      writTitleCellPattern,
-      'writ-title cell should be a clickable rig-link anchor',
+      createRigRowBody,
+      /writTitleAnchor\s*=\s*document\.createElement\(['"]a['"]\)/,
+      'writ-title cell should be built around a dedicated anchor element',
+    );
+    assert.match(
+      createRigRowBody,
+      /writTitleAnchor\.className\s*=\s*['"]rig-link['"]/,
+      'writ-title anchor should carry the rig-link class',
+    );
+    assert.match(
+      createRigRowBody,
+      /writTitleAnchor\.setAttribute\(['"]data-rig-id['"]\s*,\s*rig\.id\)/,
+      'writ-title anchor should carry data-rig-id for click routing',
     );
   });
 
   it('renders the rig-id cell as a rig-link anchor', () => {
-    const rigIdCellPattern =
-      /<td><a class="rig-link" href="#" data-rig-id="[^"]*"\s*>\s*'\s*\+\s*esc\(rig\.id\)/;
+    assert.ok(createRigRowBody, 'should find createRigRow body');
     assert.match(
-      spiderJs,
-      rigIdCellPattern,
-      'rig-id cell should be a clickable rig-link anchor',
+      createRigRowBody,
+      /rigIdAnchor\s*=\s*document\.createElement\(['"]a['"]\)/,
+      'rig-id cell should be built around a dedicated anchor element',
+    );
+    assert.match(
+      createRigRowBody,
+      /rigIdAnchor\.className\s*=\s*['"]rig-link['"]/,
+      'rig-id anchor should carry the rig-link class',
+    );
+    assert.match(
+      createRigRowBody,
+      /rigIdAnchor\.textContent\s*=\s*rig\.id/,
+      'rig-id anchor should show rig.id as its visible text',
     );
   });
 
   it('writ-title and rig-id cells share the same rig-link class', () => {
-    // Both cells must use the same class so the click handler wires them
-    // identically.  Count rig-link anchors in the row template.
-    const rowTemplateMatch = spiderJs.match(
-      /var rows = filtered\.map\(function \(rig\) \{[\s\S]*?\.join\(''\)/,
-    );
-    assert.ok(rowTemplateMatch, 'should find the row template block');
-    const rowTemplate = rowTemplateMatch[0];
-
-    const rigLinkCount = (rowTemplate.match(/class="rig-link"/g) || []).length;
+    // Both cells must use the same class so the click-wiring treats them
+    // identically.  Count rig-link references inside createRigRow.
+    assert.ok(createRigRowBody, 'should find createRigRow body');
+    const rigLinkCount = (createRigRowBody.match(/['"]rig-link['"]/g) || []).length;
     assert.ok(
       rigLinkCount >= 2,
-      `expected at least 2 rig-link anchors in the row template, found ${rigLinkCount}`,
+      `expected at least 2 rig-link anchors in createRigRow, found ${rigLinkCount}`,
     );
   });
 
   it('writ-title cell is NOT rendered as plain text', () => {
-    // Regression guard: the old pattern was just  '<td>' + esc(writTitle) + '</td>'
-    // with no anchor.  Ensure that pattern no longer exists.
+    // Regression guard: the writ-title cell must always be an anchor, not
+    // a plain text <td>. We forbid both the legacy string-template shape
+    // and any plain assignment of the writ title onto a <td>'s textContent.
     const plainTitlePattern = /'<td>'\s*\+\s*esc\(writTitle\)\s*\+\s*'<\/td>'/;
     assert.doesNotMatch(
       spiderJs,
       plainTitlePattern,
       'writ-title cell must not be rendered as plain (non-linked) text',
     );
+    assert.doesNotMatch(
+      spiderJs,
+      /writTitleTd\.textContent\s*=\s*writTitle/,
+      'writ-title text must never be written directly onto the td',
+    );
   });
 
   it('writ deep-links target the canonical Clerk writs page path', () => {
@@ -900,6 +928,70 @@ describe('spider.js pipeline keyed update', () => {
   });
 });
 
+// ── Rig-list renderer keyed in-place update ─────────────────────────────
+
+describe('spider.js rig-list keyed update', () => {
+  // Mirrors the pipeline keyed-update block: a fast-path / slow-path
+  // update strategy for the rig-tbody, keyed by data-rig-id on each <tr>.
+  // The three mutating <td>s carry per-cell class hooks so updateRigRow
+  // can patch them without positional selectors.
+
+  it('createRigRow sets data-rig-id on the <tr>', () => {
+    const block = spiderJs.match(
+      /function createRigRow\(rig\)[\s\S]*?return tr;\s*\}/,
+    );
+    assert.ok(block, 'should find createRigRow');
+    assert.match(
+      block[0],
+      /tr\.setAttribute\(['"]data-rig-id['"]\s*,\s*rig\.id\)/,
+      'createRigRow should index the row by data-rig-id on the <tr>',
+    );
+  });
+
+  it('renderRigList has a fast path that patches in place when order is unchanged', () => {
+    const block = spiderJs.match(
+      /function renderRigList\([\s\S]*?(?=\n  \/\/|\n  function )/,
+    );
+    assert.ok(block, 'should find renderRigList');
+    assert.match(
+      block[0],
+      /getAttribute\(['"]data-rig-id['"]\)/,
+      'renderRigList should key existing rows by data-rig-id',
+    );
+    assert.match(
+      block[0],
+      /orderUnchanged/,
+      'renderRigList should compute an orderUnchanged flag for the fast path',
+    );
+    assert.match(
+      block[0],
+      /updateRigRow\(/,
+      'renderRigList should reach into updateRigRow for in-place patches',
+    );
+  });
+
+  it('exposes updateRigRow(row, rig) for in-place cell updates', () => {
+    assert.match(
+      spiderJs,
+      /function updateRigRow\(row, rig\)/,
+      'should define updateRigRow(row, rig) helper for in-place row updates',
+    );
+  });
+
+  it('rig-row cells carry per-cell class hooks for status, cost, and engines', () => {
+    // Without class hooks, the keyed-update path would have to fall back
+    // to positional selectors inside the row — brittle and inconsistent
+    // with the pipeline pattern.
+    for (const cls of ['rig-row-status', 'rig-row-cost', 'rig-row-engines']) {
+      assert.match(
+        spiderJs,
+        new RegExp(`['"]${cls}['"]`),
+        `createRigRow/updateRigRow should reference the ${cls} class hook`,
+      );
+    }
+  });
+});
+
 // ── Server-supplied cost (no per-engine fetch) ──────────────────────────
 
 describe('spider.js server-supplied engine cost', () => {
@@ -1015,7 +1107,9 @@ describe('spider.js rig-list Cost column', () => {
   // T5 / D7: the rig-list table has a dedicated Cost column, rendered
   // immediately to the left of Engines, sourced from rig.costSummary.
   // The Cost column always renders — showing $0.00 when no sessions have
-  // reported cost yet.
+  // reported cost yet. After the keyed in-place refactor, the Cost cell
+  // is structurally built in createRigRow and the $0.00 fallback lives
+  // inside updateRigRow.
 
   it('index.html declares a Cost <th> between Writ Title and Engines', () => {
     assert.match(
@@ -1026,19 +1120,20 @@ describe('spider.js rig-list Cost column', () => {
   });
 
   it('row template emits a cost cell between writ-title and engines cells', () => {
-    const rowTemplateMatch = spiderJs.match(
-      /var rows = filtered\.map\(function \(rig\) \{[\s\S]*?\.join\(''\)/,
-    );
-    assert.ok(rowTemplateMatch, 'should find the row template block');
-    const rowTemplate = rowTemplateMatch[0];
-    // esc(writTitle) must come before esc(formatCostUsd(costUsd))
-    // which must come before esc(engineSummary(rig.engines))
-    const writIdx = rowTemplate.indexOf('esc(writTitle)');
-    const costIdx = rowTemplate.indexOf('formatCostUsd(costUsd)');
-    const enginesIdx = rowTemplate.indexOf('engineSummary(rig.engines)');
-    assert.ok(writIdx >= 0, 'row template should include writ title cell');
-    assert.ok(costIdx >= 0, 'row template should include cost cell');
-    assert.ok(enginesIdx >= 0, 'row template should include engines cell');
+    // createRigRow appends cells to the <tr> in DOM order, so we pin the
+    // ordering invariant by checking that the writ-title cell is appended
+    // before the cost cell, which is appended before the engines cell.
+    const createRigRowMatch = spiderJs.match(
+      /function createRigRow\(rig\)[\s\S]*?return tr;\s*\}/,
+    );
+    assert.ok(createRigRowMatch, 'should find createRigRow body');
+    const body = createRigRowMatch[0];
+    const writIdx = body.indexOf('tr.appendChild(writTitleTd)');
+    const costIdx = body.indexOf('tr.appendChild(costTd)');
+    const enginesIdx = body.indexOf('tr.appendChild(enginesTd)');
+    assert.ok(writIdx >= 0, 'createRigRow should append a writ-title cell');
+    assert.ok(costIdx >= 0, 'createRigRow should append a cost cell');
+    assert.ok(enginesIdx >= 0, 'createRigRow should append an engines cell');
     assert.ok(
       writIdx < costIdx && costIdx < enginesIdx,
       'cost cell must sit between writ-title and engines cells',
@@ -1046,15 +1141,23 @@ describe('spider.js rig-list Cost column', () => {
   });
 
   it('row template falls back to 0 when costSummary is absent (renders $0.00)', () => {
-    const rowTemplateMatch = spiderJs.match(
-      /var rows = filtered\.map\(function \(rig\) \{[\s\S]*?\.join\(''\)/,
+    // The $0.00 fallback now lives in updateRigRow — the cost cell's
+    // textContent is always derived via formatCostUsd, defaulting costUsd
+    // to 0 when costSummary is missing or costUsd is not a number.
+    const updateRigRowMatch = spiderJs.match(
+      /function updateRigRow\(row, rig\)[\s\S]*?(?=\n  \}\n\n  \/\/|\n  function )/,
     );
-    assert.ok(rowTemplateMatch, 'should find the row template block');
-    const rowTemplate = rowTemplateMatch[0];
+    assert.ok(updateRigRowMatch, 'should find updateRigRow body');
+    const body = updateRigRowMatch[0];
     assert.match(
-      rowTemplate,
+      body,
       /rig\.costSummary[\s\S]*?costUsd[\s\S]*?:\s*0/,
-      'row template should default costUsd to 0 when costSummary is missing',
+      'updateRigRow should default costUsd to 0 when costSummary is missing',
+    );
+    assert.match(
+      body,
+      /formatCostUsd\(costUsd\)/,
+      'updateRigRow should render the cell via formatCostUsd',
     );
   });
 });

package/src/static/spider.js

@@ -577,35 +577,174 @@
     if (empty) empty.style.display = 'none';
     if (table) table.style.display = '';
 
-    var rows = filtered.map(function (rig) {
-      var writTitle = (writLookup[rig.writId] && writLookup[rig.writId].title) || '\u2014';
-      // D7/D11: render $0.00 when no cost data exists. Server populates
-      // costSummary from the animator sessions book for every rig.
-      var costUsd = (rig.costSummary && typeof rig.costSummary.costUsd === 'number') ? rig.costSummary.costUsd : 0;
-      return '<tr>' +
-        '<td>' + badgeHtml(rig.status) + '</td>' +
-        '<td><a class="rig-link" href="#" data-rig-id="' + esc(rig.id) + '">' + esc(writTitle) + '</a></td>' +
-        '<td>' + esc(formatCostUsd(costUsd)) + '</td>' +
-        '<td>' + esc(engineSummary(rig.engines)) + '</td>' +
-        '<td><a class="rig-link" href="#" data-rig-id="' + esc(rig.id) + '">' + esc(rig.id) + '</a></td>' +
-        '<td><a href="/pages/writs/?writ=' + esc(rig.writId) + '">' + esc(rig.writId) + '</a></td>' +
-        '<td>' + esc(formatDate(rig.createdAt)) + '</td>' +
-        '</tr>';
+    // Index existing row children by rig id (mirrors renderPipelineInto).
+    var existingRows = {};
+    var existingList = tbody.children;
+    for (var i = 0; i < existingList.length; i++) {
+      var existingId = existingList[i].getAttribute('data-rig-id');
+      if (existingId) existingRows[existingId] = existingList[i];
+    }
+
+    // Fast path: same rig set in the same order. Patch each row in place
+    // without touching the parent's child list — the common case during
+    // the 2 s poll when nothing has been added or removed.
+    var orderUnchanged =
+      existingList.length === filtered.length &&
+      filtered.every(function (rig, idx) {
+        return existingList[idx].getAttribute('data-rig-id') === rig.id;
+      });
+
+    if (orderUnchanged) {
+      for (var f = 0; f < filtered.length; f++) {
+        updateRigRow(existingList[f], filtered[f]);
+      }
+      return;
+    }
+
+    // Slow path: rig set or order changed. Detach every row (without
+    // `innerHTML = ''`, which would drop the nodes we want to reuse),
+    // then re-append matched rows via createRigRow / updateRigRow in the
+    // new filtered order. Rows for rig ids not in the incoming list are
+    // simply not re-attached and fall out of scope.
+    while (tbody.firstChild) {
+      tbody.removeChild(tbody.firstChild);
+    }
+
+    filtered.forEach(function (rig) {
+      var row = existingRows[rig.id];
+      if (!row) {
+        row = createRigRow(rig);
+      }
+      updateRigRow(row, rig);
+      tbody.appendChild(row);
     });
+  }
 
-    tbody.innerHTML = rows.join('');
-
-    // Wire rig-link clicks
-    var links = tbody.querySelectorAll('.rig-link');
-    for (var i = 0; i < links.length; i++) {
-      (function (link) {
-        link.addEventListener('click', function (e) {
-          e.preventDefault();
-          var rigId = link.getAttribute('data-rig-id');
-          var rig = rigs.find(function (r) { return r.id === rigId; });
-          if (rig) showRigDetail(rig);
-        });
-      })(links[i]);
+  // ── Rig-row construction + in-place update ─────────────────────────────
+
+  /**
+   * Build a new <tr> for the given rig. Modeled one-for-one on
+   * createPipelineNode: data-rig-id on the outer node (D3), per-cell class
+   * hooks on the mutating <td>s (D4), and rig-link click handlers wired
+   * once per anchor with a closure over rig.id (D5/D6). The live rig is
+   * resolved inside the handler via rigs.find so reused rows pick up the
+   * latest payload without needing their listeners re-attached.
+   */
+  function createRigRow(rig) {
+    var tr = document.createElement('tr');
+    tr.setAttribute('data-rig-id', rig.id);
+
+    // Cell 1: Status. A stable <span class="badge"> child is patched in
+    // place by updateRigRow — the className toggles the variant, the
+    // textContent is the status word.
+    var statusTd = document.createElement('td');
+    statusTd.className = 'rig-row-status';
+    var statusBadge = document.createElement('span');
+    statusBadge.className = 'badge';
+    statusTd.appendChild(statusBadge);
+    tr.appendChild(statusTd);
+
+    // Cell 2: Writ title (rig-link anchor). Writ title text is written by
+    // updateRigRow on every poll (D9) so writLookup refreshes are visible.
+    var writTitleTd = document.createElement('td');
+    var writTitleAnchor = document.createElement('a');
+    writTitleAnchor.className = 'rig-link';
+    writTitleAnchor.href = '#';
+    writTitleAnchor.setAttribute('data-rig-id', rig.id);
+    writTitleAnchor.addEventListener('click', function (e) {
+      e.preventDefault();
+      var live = rigs.find(function (r) { return r.id === rig.id; });
+      if (live) showRigDetail(live);
+    });
+    writTitleTd.appendChild(writTitleAnchor);
+    tr.appendChild(writTitleTd);
+
+    // Cell 3: Cost.
+    var costTd = document.createElement('td');
+    costTd.className = 'rig-row-cost';
+    tr.appendChild(costTd);
+
+    // Cell 4: Engines.
+    var enginesTd = document.createElement('td');
+    enginesTd.className = 'rig-row-engines';
+    tr.appendChild(enginesTd);
+
+    // Cell 5: Rig id (rig-link anchor). The id text never changes for a
+    // given row, so it's written once at create time.
+    var rigIdTd = document.createElement('td');
+    var rigIdAnchor = document.createElement('a');
+    rigIdAnchor.className = 'rig-link';
+    rigIdAnchor.href = '#';
+    rigIdAnchor.setAttribute('data-rig-id', rig.id);
+    rigIdAnchor.textContent = rig.id;
+    rigIdAnchor.addEventListener('click', function (e) {
+      e.preventDefault();
+      var live = rigs.find(function (r) { return r.id === rig.id; });
+      if (live) showRigDetail(live);
+    });
+    rigIdTd.appendChild(rigIdAnchor);
+    tr.appendChild(rigIdTd);
+
+    // Cell 6: Writ deep-link to the Clerk writs page. Stable per row.
+    var writIdTd = document.createElement('td');
+    var writIdAnchor = document.createElement('a');
+    writIdAnchor.href = '/pages/writs/?writ=' + encodeURIComponent(rig.writId || '');
+    writIdAnchor.textContent = rig.writId || '';
+    writIdTd.appendChild(writIdAnchor);
+    tr.appendChild(writIdTd);
+
+    // Cell 7: Created timestamp (stable per row).
+    var createdTd = document.createElement('td');
+    createdTd.textContent = formatDate(rig.createdAt);
+    tr.appendChild(createdTd);
+
+    return tr;
+  }
+
+  /**
+   * Patch the mutating cells of an existing rig row in place. Safe to
+   * call on every 2 s poll — writes only happen when values actually
+   * changed, mirroring the idempotent-write pattern used by setText /
+   * updatePipelineNode. Cells touched: status (badge class + text), writ
+   * title (anchor textContent — re-read from writLookup each call per
+   * D9), cost, engines.
+   */
+  function updateRigRow(row, rig) {
+    // Status badge — class + text, both idempotent.
+    var statusTd = row.querySelector('.rig-row-status');
+    if (statusTd) {
+      var badgeEl = statusTd.querySelector('.badge');
+      if (badgeEl) {
+        var bc = badgeClass(rig.status);
+        var nextClass = bc ? 'badge ' + bc : 'badge';
+        if (badgeEl.className !== nextClass) badgeEl.className = nextClass;
+        if (badgeEl.textContent !== rig.status) badgeEl.textContent = rig.status;
+      }
+    }
+
+    // Writ title — re-read from writLookup on every call (D9). The
+    // writ-title anchor is the first .rig-link in the row; the rig-id
+    // anchor appears later and is not touched here.
+    var writTitle = (writLookup[rig.writId] && writLookup[rig.writId].title) || '\u2014';
+    var writTitleAnchor = row.querySelector('.rig-link');
+    if (writTitleAnchor && writTitleAnchor.textContent !== writTitle) {
+      writTitleAnchor.textContent = writTitle;
+    }
+
+    // Cost — D7/D11 fallback to 0 when costSummary is absent so the cell
+    // always renders $0.00 rather than blank.
+    var costTd = row.querySelector('.rig-row-cost');
+    if (costTd) {
+      var costUsd = (rig.costSummary && typeof rig.costSummary.costUsd === 'number') ? rig.costSummary.costUsd : 0;
+      var costText = formatCostUsd(costUsd);
+      if (costTd.textContent !== costText) costTd.textContent = costText;
+    }
+
+    // Engine summary.
+    var enginesTd = row.querySelector('.rig-row-engines');
+    if (enginesTd) {
+      var enginesText = engineSummary(rig.engines);
+      if (enginesTd.textContent !== enginesText) enginesTd.textContent = enginesText;
     }
   }