tools.js

/**

 * The five tools, declared once.

 *

 * Each Space linked to the others from its own footer, which meant the

 * same five URLs written out in five files — twenty-five places for a

 * rename to break, and a Space rename is invisible from the linking

 * side: the link keeps returning a page, and the page is a 404.

 *

 * So the registry lives here and is copied into each Space at deploy

 * time, next to `progress.js`. One file to change when a tool moves.

 *

 * The order is the order somebody actually needs them: find a model,

 * see how much context it can serve, learn how to run it, then check

 * what the pack really contains before spending the download.

 */

export const TOOLS = {
  search: {
    space: 'model-search-that-answers',
    title: 'Find a model that fits',
    asks: 'which models fit my card at all',
    // What the visitor has just learned, and why the next tool follows.
    leadsTo: 'context',
    takes: 'query',
  },
  context: {
    space: 'what-context-fits',
    title: 'What context will actually fit?',
    asks: 'how long a conversation this one can serve',
    leadsTo: 'parser',
    takes: 'repo',
  },
  parser: {
    space: 'reasoning-parser-advisor',
    title: 'Does this model need a reasoning parser?',
    asks: 'how to serve it without silently empty answers',
    leadsTo: 'precision',
    takes: 'repo',
  },
  precision: {
    space: 'pack-precision-map',
    title: 'How much of this pack is actually 4-bit?',
    asks: 'what a quantized pack really compressed, and what it kept',
    leadsTo: 'integrity',
    takes: 'repo',
  },
  integrity: {
    space: 'pack-integrity-check',
    title: 'Does this pack keep what it claims?',
    asks: 'whether anything was dropped or left undeclared',
    leadsTo: null,
    takes: 'repo',
  },
};

export const ORDER = ['search', 'context', 'parser', 'precision', 'integrity'];

const BASE = 'https://huggingface.co/spaces/aleada';
const HUB = `${BASE}/start-here`;

/**

 * A link to one tool, carrying the model with it.

 *

 * A funnel where each step starts empty is five separate tools with

 * links between them. `?repo=` is read on load by every page that takes

 * one, so clicking through keeps the model you were looking at.

 */
export function url(key, repo = null) {
  const t = TOOLS[key];
  if (!t) return BASE;
  const q = repo && t.takes === 'repo'
    ? `?repo=${encodeURIComponent(repo)}`
    : repo && t.takes === 'query'
      ? `?q=${encodeURIComponent(repo)}` : '';
  return `${BASE}/${t.space}${q}`;
}

/** The model this page was opened with, if a link carried one over. */
export function repoFromUrl() {
  const p = new URLSearchParams(window.location.search);
  return (p.get('repo') || p.get('q') || '').trim() || null;
}

const esc = (s) => String(s).replace(/[&<>"]/g, (c) =>
  ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));

/**

 * The next questions, rendered under a result.

 *

 * The whole chain is rendered, not just the parts that come after: the

 * current step is marked so a visitor who arrived from a link can see

 * where they are, and the steps behind stay reachable because the order

 * is a suggestion and not a gate.

 *

 * Offered only once there is an answer on screen — a next step shown

 * before the current one is finished is clutter, and one that cannot

 * carry the model over is a link to an empty form.

 */
export function nextSteps(fromKey, repo = null) {
  const here = ORDER.indexOf(fromKey);
  const items = ORDER.map((k, i) => {
    const t = TOOLS[k];
    if (i === here) {
      // The step you are on, shown rather than hidden. A list of "other
      // tools" tells you what exists; a chain with your place marked
      // tells you how far along you are, which is the thing somebody
      // arriving from a link actually wants to know.
      return `<li class="ns-here"><span class="ns-mark">✓</span>

        <span class="ns-title">${esc(t.title)}</span>

        <span class="ns-why">you are here</span></li>`;
    }
    const ahead = i > here;
    return `<li class="${ahead ? 'ns-next' : 'ns-back'}">

      <span class="ns-mark">${ahead ? '→' : '·'}</span>

      <a href="${url(k, repo)}" target="_blank" rel="noopener">${esc(t.title)}</a>

      <span class="ns-why">${esc(t.asks)}</span></li>`;
  }).join('');

  return `<nav class="nextsteps" aria-label="The rest of the chain">

      <h4>Your next question${repo ? ` for <code>${esc(repo)}</code>` : ''}</h4>

      <ul>${items}</ul>

      <a class="ns-hub" href="${HUB}${repo ? `?repo=${encodeURIComponent(repo)}` : ''}"

         target="_blank" rel="noopener">All five, and why they are in this order →</a>

    </nav>`;
}

/** Styles for the block above, injected once so each Space need not carry them. */
export function ensureNextStepStyles() {
  if (document.getElementById('ns-style')) return;
  const el = document.createElement('style');
  el.id = 'ns-style';
  el.textContent = `

.nextsteps { margin: 1.6rem 0 0; padding-top: 1rem; border-top: 1px solid var(--line); }

.nextsteps h4 { margin: 0 0 .5rem; font-size: .74rem; font-weight: 600;

                text-transform: uppercase; letter-spacing: .05em; color: var(--muted); }

.nextsteps h4 code { text-transform: none; letter-spacing: 0; }

.nextsteps ul { list-style: none; margin: 0; padding: 0; }

.nextsteps li { margin: .32rem 0; font-size: .89rem; display: flex;

                gap: .5rem; align-items: baseline; }

.ns-mark { font-family: var(--mono); font-size: .8rem; color: var(--muted);

           width: 1rem; flex: 0 0 1rem; }

.ns-here .ns-mark { color: var(--accent); }

.ns-here .ns-title { font-weight: 600; }

.ns-back { opacity: .72; }

.ns-hub { display: inline-block; margin-top: .7rem; font-size: .84rem; }

.nextsteps a { color: var(--accent); text-decoration: none; }

.nextsteps a:hover { text-decoration: underline; }

.ns-why { color: var(--muted); }

.ns-why::before { content: " — "; }`;
  document.head.appendChild(el);
}