Honest unresolved-faminst placeholder text

The previous status text said "the equation isn't in this project's
dumps", which is only one of the reasons the placeholder fires. The
other — equally common in real codebases — is that classgraph doesn't
fully simulate GHC's type-family rewrite chain: a use site like
@ChainDepState (BlockProtocol blk)@ won't unify with the
@ChainDepState (Praos c)@ data instance unless we can first reduce
@BlockProtocol blk@ to @Praos _@. If @blk@ stays abstract or the
inner reduction stops, the outer family looks unresolvable even when
the equations are right there in the dumps.

Spell out both reasons in the side panel, with concrete examples and
a hint to open the family node to inspect the equations we *do*
have.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

diff --git a/data/viewer.css b/data/viewer.css
index bbb9108a2d8f762a31a924211efb282ea64b87d0..b10c21ee469cd197f2c0a8dbc0677f8281627890 100644 (file)
--- a/data/viewer.css
+++ b/data/viewer.css
@@ -154,6 +154,23 @@ ul.datacons li {
   padding: 2px 0;
   color: #1e293b;
 }
+ol.placeholder-reasons {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  margin: 4px 0 6px;
+  padding-left: 20px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: #1e293b;
+}
+ol.placeholder-reasons li {
+  margin-bottom: 6px;
+}
+.placeholder-hint {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  font-size: 12px;
+  color: #475569;
+  margin: 0;
+}
 .swatch-external { background: #e5e7eb; color: #374151; border-color: #9ca3af; border-style: dashed; }
 .swatch-ghost    { background: #dbeafe; color: #1e3a8a; border-color: #1d4ed8; border-style: dashed; opacity: 0.85; }
 .swatch-orphan   { background: #ecfdf5; color: #065f46; border: 1px dashed #dc2626; }

diff --git a/data/viewer.js b/data/viewer.js
index e8de2383122964bf90ff0b59aedca89dd2b0fe24..0e63c788e4deaee19ed4aa8d7b8df26bb446d8a2 100644 (file)
--- a/data/viewer.js
+++ b/data/viewer.js
@@ -1970,7 +1970,15 @@
         <h2>${head}</h2>
         <p class="pkgmod">${escape(fi.fiFamily.qnPackage)} · ${escape(fi.fiFamily.qnModule)}</p>
         <dl>
-          <dt>Status</dt><dd><em>Use site of an external type family — the equation isn't in this project's dumps, so the right-hand side can't be resolved here.</em></dd>
+          <dt>Status</dt>
+          <dd>
+            <p>Use site that classgraph couldn't match against any known fam-instance. Two common reasons:</p>
+            <ol class="placeholder-reasons">
+              <li><strong>External family</strong> — the family's equations live in a package you haven't extracted. Re-run the plugin against the defining package to surface them here.</li>
+              <li><strong>Nested or abstract args</strong> — classgraph doesn't fully simulate GHC's type-family rewrite chain. For example, <code>ChainDepState (BlockProtocol blk)</code> won't match a concrete instance like <code>ChainDepState (Praos c)</code> unless we can first reduce <code>BlockProtocol blk</code> to a <code>Praos _</code> shape; if <code>blk</code> stays abstract or the inner reduction fails, the outer family looks unresolvable even though the equations are in your dumps.</li>
+            </ol>
+            <p class="placeholder-hint">Open the family node (the diamond above this row) to see all the fam-instances we <em>do</em> have for it — one of them may be the satisfier in the actual program.</p>
+          </dd>
         </dl>`;
     }
     const tvs = fi.fiTyVars.length === 0 ? '<dd><em>none</em></dd>' :