Add shareable URL state, speedup column and family-scoped metric legend

Three independent features, developed on separate branches and merged here.

Shareable URL state (urlstate.js)
Mirrors base family, variant, metric and every filter column into
location.hash, so a specific chart can be linked:
#family=Llama-3.2&device=agx_orin&metric=tps
Uses replaceState, so clicking filters does not fill the history stack.
Unknown families/metrics/filter values are ignored rather than applied.
The Embed modal now deep-links back to the exact view it was generated
from. Verified that huggingface.co forwards the hash into the Space
iframe, so links work both on the Space page and on *.hf.space.
Disable with "url_state": false.

Speedup column (speedup.js)
The data is inherently paired: an external baseline model and its
embedl variants measured under identical conditions. The tables now
carry a VS BASE column with the ratio for the active metric, always
oriented so higher is better. Baselines read 1.00x, unpaired rows read
em-dash, and an ambiguous pairing renders nothing rather than an
arbitrary number. Disable with "speedup_column": false.

Family-scoped metric legend (app.js)
The legend was built once at load from every configured metric, so a
CV family still listed TPS/TPOT/TTFT/E2E and an LLM family still
listed IPS/LAT/MEM. It now re-renders with the view and lists only the
metrics that actually have data. The "has data" predicate existed in
two copies (chart metric buttons, table columns); this factors it into
a single metricsWithData() that the legend also uses, so all three
agree. Disable with "legend_filter": false.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

app.js

@@ -371,11 +371,29 @@ function createFilterGroup(label, id) {
     return div;
 }
 
-// Metric legend
+// ─── Metric legend ────────────────────────────────────────────────────────────
+
+// [legend] Single source of truth for "which metrics have data in these rows".
+// Used by buildChart (metric buttons), buildTables (metric columns) and the
+// legend below, so all three agree on what is relevant to the current family.
+function metricsWithData(rows) {
+    return config.metrics.filter(m =>
+        rows.some(r => r[m.column] !== undefined && r[m.column] !== null && r[m.column] !== 0 && r[m.column] !== "N/A")
+    );
+}
+
+// [legend] The legend explains only the metrics currently on screen: a CV family
+// (ips/lat/mem) no longer shows the LLM keys and vice versa. Re-rendered on every
+// render(). Set config.legend_filter = false to always list every metric.
 const legendGrid = document.getElementById("legend-grid");
-legendGrid.innerHTML = config.metrics.map(m =>
-    `<div><strong>${m.short || m.column}</strong> ${m.description || m.label}</div>`
-).join("");
+
+function renderLegend(metrics) {
+    const shown = config.legend_filter === false ? config.metrics : metrics;
+    legendGrid.innerHTML = shown.map(m =>
+        `<div><strong>${m.short || m.column}</strong> ${m.description || m.label}</div>`
+    ).join("");
+    legendGrid.style.display = shown.length ? "" : "none";
+}
 
 // ─── State ────────────────────────────────────────────────────────────────────
 
@@ -431,9 +449,13 @@ function updateDependentFilters(resetDefaults) {
         const strVals = vals.map(String);
         const needsReset = resetDefaults || !strVals.includes(String(filters[f.column]));
         if (needsReset) {
+            // [urlstate] a value asked for by the URL hash wins over the family default
+            const wanted = urlstate.desiredFilterValue(f.column, strVals);
             // Prefer family-specific default_device for the device/group_by filter
             const defaultVal = f.column === GROUP_BY && familyCfg.default_device;
-            if (defaultVal && strVals.includes(String(defaultVal))) {
+            if (wanted !== null) {
+                filters[f.column] = wanted;
+            } else if (defaultVal && strVals.includes(String(defaultVal))) {
                 filters[f.column] = defaultVal;
             } else {
                 filters[f.column] = vals[0] ?? "";
@@ -529,9 +551,7 @@ function buildChart(filtered) {
     headerRight.className = "chart-header-right";
 
     // Only show metric buttons for metrics that have non-zero data
-    const chartVisibleMetrics = config.metrics.filter(m =>
-        gRows.some(r => r[m.column] !== undefined && r[m.column] !== null && r[m.column] !== 0 && r[m.column] !== "N/A")
-    );
+    const chartVisibleMetrics = metricsWithData(gRows); // [legend] was an inline config.metrics.filter(...)
     if (chartVisibleMetrics.length > 1) {
         const metricEl = metricGroup.querySelector(".btn-group");
         renderBtnGroup(metricEl,
@@ -683,9 +703,7 @@ function buildTables(filtered, chartsShown) {
     });
 
     // Hide metric columns where every value in the filtered data is zero, null, or N/A
-    const visibleMetrics = config.metrics.filter(m =>
-        filtered.some(r => r[m.column] !== undefined && r[m.column] !== null && r[m.column] !== 0 && r[m.column] !== "N/A")
-    );
+    const visibleMetrics = metricsWithData(filtered); // [legend] was an inline config.metrics.filter(...)
 
     // Build column list: Model + visible display cols + metrics
     const colDefs = [
@@ -743,6 +761,9 @@ function buildTables(filtered, chartsShown) {
             return metricHib ? va - vb : vb - va;
         });
 
+        // [speedup] pair optimized rows with their baseline for this table
+        speedup.prepare(rows, { tableGroupCols, visibleMetrics, activeMetricCol });
+
         // Track row group for break detection
         let prevGroupVal = undefined;
 
@@ -759,6 +780,7 @@ function buildTables(filtered, chartsShown) {
             const cls = i === firstMetricIdx ? ' class="first-metric metric-cell"' : (c.isMetric ? ' class="metric-cell"' : '');
             return `<th${tip}${cls}>${c.label}</th>`;
         }).join("");
+        html += speedup.headerHtml();   // [speedup] extra right-hand column
         html += `</tr></thead><tbody>`;
 
         // Compute best metric value per sub-group (tableGroupBy) per column
@@ -805,6 +827,7 @@ function buildTables(filtered, chartsShown) {
                     html += `<td>${val || "—"}</td>`;
                 }
             });
+            html += speedup.cellHtml(r);   // [speedup] extra right-hand column
             html += "</tr>";
         });
 
@@ -932,6 +955,17 @@ async function buildAccuracyTable() {
     section.appendChild(card);
 }
 
+// ─── URL state module ────────────────────────────────────────────────────────
+
+// [urlstate] Construction applies any incoming #hash to `filters` right here,
+// before populateFilters()/switchBaseFamily() below, so the first render
+// already shows the linked view. render() then keeps the hash in sync.
+const urlstate = initUrlState({
+    config, filters, BASE_FAMILIES, deriveBaseFamily, GROUP_BY,
+    availableOptions, renderSidebar, updateDependentFilters,
+    switchBaseFamily, render,
+});
+
 // ─── Embed SVG module ────────────────────────────────────────────────────────
 
 const embed = initEmbed({
@@ -939,8 +973,12 @@ const embed = initEmbed({
     getData: () => DATA, MODEL_COL, FAMILY_COL, GROUP_BY, CHART_CFG,
     MODEL_COLORS, MODEL_SHORT, isOOMRow, isExternalModel,
     sortModels, parseModelSize,
+    shareHash: urlstate.currentHash,   // [urlstate] embed link points at this view
 });
 
+// [speedup] Speedup vs baseline column module
+const speedup = initSpeedup({ config, MODEL_COL, FAMILY_COL, isExternalModel });
+
 // ─── Render ───────────────────────────────────────────────────────────────────
 
 function render() {
@@ -959,9 +997,12 @@ function render() {
     buildChart(filtered);
     const chartsShown = charts.length > 0;
     buildTables(filtered, chartsShown);
+    renderLegend(metricsWithData(filtered)); // [legend] follows the table columns
+
     buildDemo();
     buildAccuracyTable();
     buildExperimentSetup();
+    urlstate.sync();   // [urlstate] mirror the settled view into location.hash
 }
 
 // ─── Switch Base Family (load data + re-render) ───────────────────────────────

config.json

@@ -5,6 +5,7 @@
   "model_family_column": "model_family",
   "model_link_prefix": "https://huggingface.co/",
   "optimized_org": "embedl",
+  "speedup_column": true,
   "base_names": {
     "Llama-3.2-1B": "Llama-3.2-1B-Instruct",
     "Llama-3.2-3B": "Llama-3.2-3B-Instruct",

embed.js

@@ -10,7 +10,7 @@ const {
     config, filters, activeFamilyKey, getActiveModelSet,
     getData, MODEL_COL, FAMILY_COL, GROUP_BY, CHART_CFG,
     MODEL_COLORS, MODEL_SHORT, isOOMRow, isExternalModel,
-    sortModels, parseModelSize,
+    sortModels, parseModelSize, shareHash,
 } = deps;
 
 let embedModal = null;
@@ -310,7 +310,10 @@ async function showEmbedModal() {
     const fileName = embedFileName();
     const svgUrl = "https://huggingface.co/datasets/" + HF_DOCS_REPO + "/resolve/main/" + HF_SVG_FOLDER + "/" + fileName;
 
-    const embedCode = '<a href="' + HF_SPACES_URL + '" target="_blank" rel="noopener">\n  <img\n    src="' + svgUrl + '"\n    alt="Edge Inference Benchmarks for ' + famKey + '"\n    width="100%"\n  />\n</a>';
+    // Deep-link the embed back to the exact view it was generated from.
+    const spacesUrl = HF_SPACES_URL + (typeof shareHash === "function" ? shareHash() : "");
+
+    const embedCode = '<a href="' + spacesUrl + '" target="_blank" rel="noopener">\n  <img\n    src="' + svgUrl + '"\n    alt="Edge Inference Benchmarks for ' + famKey + '"\n    width="100%"\n  />\n</a>';
 
     embedModal.querySelector("#embed-code").value = embedCode;
     embedModal.classList.add("visible");

index.html

@@ -86,6 +86,8 @@
 
 <script src="demo/demo.js"></script>
 <script src="embed.js"></script>
+<script src="speedup.js"></script>
+<script src="urlstate.js"></script>
 <script src="app.js"></script>
 </body>
 </html>

speedup.js

@@ -0,0 +1,127 @@
+// ─── Speedup vs Baseline Column ──────────────────────────────────────────────
+//
+// Extracted module. Call initSpeedup(deps) from the main app once globals are
+// ready.  Returns { prepare, headerHtml, cellHtml }.
+//
+// The benchmark data is inherently paired: an external baseline model (e.g.
+// meta-llama/Llama-3.2-1B-Instruct) and the optimized embedl variants of it
+// (embedl/Llama-3.2-1B-Instruct-FlashHead, …) measured under identical
+// conditions. This module pairs them up and renders their ratio for the
+// active metric as an extra right-hand column in the benchmark tables.
+
+// eslint-disable-next-line no-unused-vars
+function initSpeedup(deps) {
+
+const {
+    config, MODEL_COL, FAMILY_COL, isExternalModel,
+} = deps;
+
+const ENABLED = config.speedup_column !== false;
+const LABEL   = config.speedup_label || "VS BASE";
+
+// Two rows are comparable only when everything that defines the measurement
+// matches: the model family, every filter column (type / batch / device) and
+// every configured display column (res / fps / frames / ctx). Leaving the
+// display columns out would happily pair a 1920x1080 run with a 854x480 one.
+const KEY_COLS = [
+    FAMILY_COL,
+    ...config.filters.map(f => f.column),
+    ...(config.display_columns || []).map(d => d.column),
+].filter(Boolean);
+
+function pairKey(row, cols) {
+    return cols.map(c => String(row[c] ?? "")).join("\0");
+}
+
+/** Metric value as a usable positive number; undefined for OOM / not-measured / "N/A" / 0. */
+function usable(val) {
+    return typeof val === "number" && isFinite(val) && val > 0 ? val : undefined;
+}
+
+function formatRatio(ratio) {
+    return ratio.toFixed(2) + "×";
+}
+
+// Per-table state, rebuilt by prepare() before each table is rendered.
+let state = null;
+
+// ─── Pairing ─────────────────────────────────────────────────────────────────
+
+/**
+ * Compute the baseline pairing for one rendered table.
+ * @param rows  the rows of this table (already filtered to one group_by value)
+ * @param opts  { tableGroupCols, visibleMetrics, activeMetricCol }
+ */
+function prepare(rows, opts) {
+    state = null;
+    if (!ENABLED || !rows || !rows.length) return;
+
+    const visibleMetrics = opts.visibleMetrics || [];
+    const metricCfg = visibleMetrics.find(m => m.column === opts.activeMetricCol)
+        || visibleMetrics[0];
+    if (!metricCfg) return;
+
+    const metricCol = metricCfg.column;
+    const hib = metricCfg.higher_is_better !== false;
+    const cols = [...new Set(KEY_COLS.concat(opts.tableGroupCols || []))];
+
+    // Bucket the external (baseline) rows by comparison key.
+    const baselines = {};
+    rows.forEach(r => {
+        if (!isExternalModel(r[MODEL_COL])) return;
+        const k = pairKey(r, cols);
+        (baselines[k] = baselines[k] || []).push(r);
+    });
+
+    const ratios  = new Map();  // optimized row -> ratio
+    const isBase  = new Set();  // baseline rows that actually anchor a pair
+
+    rows.forEach(r => {
+        if (isExternalModel(r[MODEL_COL])) return;
+        const cands = baselines[pairKey(r, cols)];
+        if (!cands || !cands.length) return;
+        // Ambiguous: several *different* baseline models match the same key.
+        // Show nothing rather than an arbitrary ratio.
+        if (new Set(cands.map(c => c[MODEL_COL])).size > 1) return;
+        const base = cands[0];
+        const b = usable(base[metricCol]);
+        const o = usable(r[metricCol]);
+        if (b === undefined || o === undefined) return;
+        const ratio = hib ? o / b : b / o;
+        if (!isFinite(ratio) || ratio <= 0) return;
+        ratios.set(r, ratio);
+        isBase.add(base);
+    });
+
+    if (!ratios.size) return;   // no real pair in this table -> no column
+    state = { ratios, isBase, metricCfg };
+}
+
+// ─── Rendering ───────────────────────────────────────────────────────────────
+
+function headerHtml() {
+    if (!state) return "";
+    const m = state.metricCfg;
+    const tip = `Ratio of this model's ${m.label || m.column} against the original `
+        + `(non-${config.optimized_org || "embedl"}) model measured under identical conditions. `
+        + `Always oriented so that higher is better: 1.26× means 26% better than the baseline.`;
+    return `<th class="metric-cell speedup-cell" data-tip="${tip.replace(/"/g, "&quot;")}">${LABEL}</th>`;
+}
+
+function cellHtml(row) {
+    if (!state) return "";
+    if (state.isBase.has(row)) {
+        // The baseline is the reference point, so it is 1.00x by definition.
+        // Spelling it out keeps "—" unambiguously meaning "no comparison".
+        return `<td class="metric-cell speedup-cell"><span class="speedup-ref">1.00×</span></td>`;
+    }
+    const ratio = state.ratios.get(row);
+    if (ratio === undefined) return `<td class="metric-cell speedup-cell">—</td>`;
+    const down = ratio < 0.995 ? " is-down" : "";
+    return `<td class="metric-cell speedup-cell">`
+        + `<span class="speedup-val${down}">${formatRatio(ratio)}</span></td>`;
+}
+
+return { prepare, headerHtml, cellHtml };
+
+}

style.css

@@ -798,6 +798,27 @@ tbody tr.row-group-break td {
     border-color: var(--btn-active-border);
 }
 
+/* ── Speedup ─────────────────────────────────────────── */
+td.speedup-cell {
+    position: relative;
+    color: var(--text);
+    font-variant-numeric: tabular-nums;
+}
+
+.speedup-val {
+    position: relative;
+    font-weight: 600;
+    color: var(--green);
+}
+
+.speedup-val.is-down {
+    color: var(--red);
+}
+
+.speedup-ref {
+    color: var(--text-dim);
+}
+
 /* ── Responsive ──────────────────────────────────────── */
 @media (max-width: 900px) {
     .page {

urlstate.js

@@ -0,0 +1,213 @@
+// ─── Shareable URL State ─────────────────────────────────────────────────────
+//
+// Mirrors the current view — base family, variant, metric and every
+// config.filters column — into location.hash so that a view can be linked:
+//
+//     #family=Llama-3.2&device=agx_orin&metric=tps
+//
+// Extracted module. Call initUrlState(deps) once, after `filters` exists and
+// BEFORE the first render: construction applies an incoming hash to `filters`
+// in place, so the very first render already shows the linked view (there is
+// no visible second render). Returns { desiredFilterValue, sync, currentHash }.
+//
+// Disable with "url_state": false in config.json.
+
+// eslint-disable-next-line no-unused-vars
+function initUrlState(deps) {
+
+const {
+    config, filters, BASE_FAMILIES, deriveBaseFamily, GROUP_BY,
+    availableOptions, renderSidebar, updateDependentFilters,
+    switchBaseFamily, render,
+} = deps;
+
+const ENABLED     = config.url_state !== false;
+const FILTER_COLS = config.filters.map(f => f.column);
+const METRIC_COLS = config.metrics.map(m => m.column);
+
+// Filter values requested by the hash but not applied yet. They are consumed
+// by updateDependentFilters(), which otherwise resets every filter column to a
+// family default whenever the newly loaded data does not contain the current
+// value. Cleared by sync() once the view has settled.
+let pending = {};
+
+// The hash this module last wrote, so our own replaceState is not re-applied.
+let lastWritten = null;
+
+// Guard against re-entrant hashchange handling during an async family switch.
+let applying = false;
+
+// ─── Parse ────────────────────────────────────────────────────────────────────
+
+function parseHash(raw) {
+    const out = {};
+    const s = String(raw || "").replace(/^#/, "");
+    if (!s) return out;
+    s.split("&").forEach(part => {
+        const i = part.indexOf("=");
+        if (i < 1) return;
+        try {
+            const k = decodeURIComponent(part.slice(0, i)).trim();
+            const v = decodeURIComponent(part.slice(i + 1)).trim();
+            if (k) out[k] = v;
+        } catch {
+            // Malformed percent-escape — drop the pair rather than throw.
+        }
+    });
+    return out;
+}
+
+// Accept either a base family ("Llama-3.2") or a config family key
+// ("Llama-3.2-1B"), mirroring the ?family= query deep link.
+function resolveFamily(fam) {
+    if (!fam) return null;
+    if (BASE_FAMILIES[fam]) return { baseFamily: fam, variant: null };
+    if (config.model_families?.[fam]) {
+        const base = deriveBaseFamily(fam);
+        if (BASE_FAMILIES[base]) return { baseFamily: base, variant: fam };
+    }
+    return null;
+}
+
+// Apply parsed hash params onto `filters`. Unknown families/metrics/variants
+// are ignored, never applied. Returns true when the base family changed (the
+// caller then has to reload that family's data).
+function applyParams(params) {
+    let familyChanged = false;
+
+    const fam = resolveFamily(params.family);
+    if (fam) {
+        familyChanged = fam.baseFamily !== filters.baseFamily;
+        filters.baseFamily = fam.baseFamily;
+        filters.variant = fam.variant;
+    }
+
+    if (params.variant !== undefined) {
+        const v = params.variant;
+        // A variant may be a data-derived model_family key that is absent from
+        // config, so it can only be checked against the base-family rule here;
+        // sync() drops it later if the loaded family does not offer it.
+        filters.variant = (v && deriveBaseFamily(v) === filters.baseFamily) ? v : null;
+    }
+
+    if (params.metric && METRIC_COLS.includes(params.metric)) {
+        filters.metric = params.metric;
+    }
+
+    pending = {};
+    FILTER_COLS.forEach(col => {
+        if (params[col] !== undefined && params[col] !== "") pending[col] = params[col];
+    });
+
+    return familyChanged;
+}
+
+// ─── Serialize ────────────────────────────────────────────────────────────────
+
+// Drop a variant the currently loaded family does not actually offer — the
+// sidebar only shows variants when there is more than one.
+function normalizeVariant() {
+    const variants = BASE_FAMILIES[filters.baseFamily]?.variants || [];
+    if (filters.variant && (variants.length <= 1 || !variants.includes(filters.variant))) {
+        filters.variant = null;
+    }
+}
+
+function buildHash() {
+    const parts = [];
+    const push = (k, v) => parts.push(encodeURIComponent(k) + "=" + encodeURIComponent(v));
+
+    push("family", filters.baseFamily);
+    if (filters.variant) push("variant", filters.variant);
+
+    // Always link the group_by (device) column — it is what people share.
+    // The remaining filter columns are only linked when the loaded family
+    // actually offers a choice; otherwise their button group is hidden and the
+    // value is noise that would be re-derived identically anyway.
+    const opts = availableOptions();
+    config.filters.forEach(f => {
+        const v = filters[f.column];
+        if (v === "" || v === null || v === undefined) return;
+        if (f.column !== GROUP_BY && (opts[f.column] || []).length <= 1) return;
+        push(f.column, v);
+    });
+
+    if (filters.metric) push("metric", filters.metric);
+    return parts.join("&");
+}
+
+// ─── Public: called from app.js ──────────────────────────────────────────────
+
+// Hook in updateDependentFilters(): the value the hash asked for, when it is
+// available in the freshly loaded data, else null (caller falls back to its
+// own default). "all" is only meaningful for the group_by column.
+function desiredFilterValue(col, availableStrVals) {
+    if (!ENABLED) return null;
+    const want = pending[col];
+    if (want === undefined) return null;
+    if (col === GROUP_BY && want === "all") return "all";
+    return availableStrVals.includes(want) ? want : null;
+}
+
+// Hook at the end of render(): the view has settled, publish it. replaceState
+// keeps every button click out of the history stack.
+function sync() {
+    if (!ENABLED) return;
+    pending = {};
+    normalizeVariant();
+    const hash = buildHash();
+    if (hash === lastWritten && String(location.hash).replace(/^#/, "") === hash) return;
+    lastWritten = hash;
+    const url = location.pathname + location.search + "#" + hash;
+    try {
+        history.replaceState(history.state, "", url);
+    } catch {
+        // file:// and a few sandboxes reject replaceState; the assignment below
+        // fires hashchange, which the lastWritten guard then ignores.
+        location.hash = hash;
+    }
+}
+
+function currentHash() {
+    return ENABLED ? "#" + buildHash() : "";
+}
+
+// ─── Incoming navigation ─────────────────────────────────────────────────────
+
+async function onHashChange() {
+    if (!ENABLED || applying) return;
+    const raw = String(location.hash).replace(/^#/, "");
+    if (raw === lastWritten) return;
+    const params = parseHash(raw);
+    if (!Object.keys(params).length) return;
+    applying = true;
+    try {
+        const familyChanged = applyParams(params);
+        renderSidebar();
+        if (familyChanged) {
+            await switchBaseFamily(filters.baseFamily);
+        } else {
+            // Reset first so columns the URL omits fall back to their default,
+            // then desiredFilterValue() re-applies the ones it does name.
+            updateDependentFilters(true);
+            render();
+        }
+    } finally {
+        applying = false;
+    }
+}
+
+// ─── Init ─────────────────────────────────────────────────────────────────────
+
+// Applied here, before populateFilters()/switchBaseFamily() run, so the first
+// render already reflects the link. The hash therefore wins over the existing
+// ?family= query deep link, which is applied earlier in app.js.
+if (ENABLED) {
+    const initial = parseHash(typeof location !== "undefined" ? location.hash : "");
+    if (Object.keys(initial).length) applyParams(initial);
+    if (typeof window !== "undefined") window.addEventListener("hashchange", onHashChange);
+}
+
+return { desiredFilterValue, sync, currentHash };
+
+} // end initUrlState