feat(embed): make url params consistent with main site, add i_active allow list for gpus

Author: rafaykhan-source

docs/embed.md

@@ -1,16 +1,10 @@
 # Embed Routes
 
-Public-contract, stable iframe-embedding surface for InferenceX charts. Partner sites can embed any supported chart by iframing an `/embed/*` URL and rely on it continuing to work long-term.
+Public iframe-embedding surface for InferenceX charts. Partner sites can embed any supported chart by iframing an `/embed/*` URL.
 
-## Stability guarantee
+## URL parameter contract
 
-The embed URL shape is a **public API**. The following rules apply permanently:
-
-- Existing parameter keys **cannot be removed or renamed**. New keys may be added with sensible defaults.
-- Existing `y` short-form aliases **cannot be removed or renamed**. New aliases may be added.
-- Existing `gpus` hwKey tokens **cannot be removed or renamed**. New tokens may be added when new hardware is added to the benchmark.
-- Unknown values always fall back to the documented default — a stale embed URL must never render an error page.
-- If a rename becomes unavoidable, the old key/alias must be kept as a permanently-handled alias alongside the new one, and a note added to this file.
+Embed URLs use **the same `g_*` / `i_*` parameter keys as the main `/inference` site** — there is no separate embed-specific key contract to maintain. If a site key is renamed or a new key is added, the embed URL automatically benefits from the change. The only embed-specific key is `i_chart` (which chart variant to display — the main site renders both E2E and interactivity together, embeds show only one).
 
 ## Supported routes
 
@@ -23,74 +17,37 @@ The embed URL shape is a **public API**. The following rules apply permanently:
 ### URL shape
 
 ```
-/embed/scatter?model=dsr1&isl=8192&osl=1024&precisions=fp4&gpus=b200_sglang,gb300_dynamo-sglang&y=tpPerGpu&chart=e2e
+/embed/scatter?g_model=DeepSeek-R1-0528&i_seq=8k%2F1k&i_prec=fp4
+  &i_metric=y_tpPerGpu&i_active=b200_sglang,gb300_dynamo-sglang&i_chart=e2e
 ```
 
 ### Parameters
 
-| Key          | Type           | Default          | Accepted values                                                         | Fallback on unknown    |
-| ------------ | -------------- | ---------------- | ----------------------------------------------------------------------- | ---------------------- |
-| `model`      | string         | `dsr1`           | Any DB model key (see table below)                                      | Default model (`dsr1`) |
-| `isl`        | integer string | `8192`           | Input sequence length in tokens                                         | Default (`8192`)       |
-| `osl`        | integer string | `1024`           | Output sequence length in tokens                                        | Default (`1024`)       |
-| `precisions` | string         | `fp4`            | Comma-separated precision keys (e.g. `fp4`, `fp8`, `bf16`)              | Default (`fp4`)        |
-| `gpus`       | string         | `` (all visible) | Comma-separated hwKey tokens (see format below)                         | Empty — all GPUs shown |
-| `y`          | string         | `tpPerGpu`       | Any short-form alias from the table below, or a full `y_*` internal key | Default (`tpPerGpu`)   |
-| `chart`      | string         | `e2e`            | `e2e`, `interactivity`                                                  | `e2e`                  |
-
-### `model` — accepted DB keys
-
-These are the short DB keys accepted as `model=`. They map to the display model names shown in the chart. Unknown keys fall back to the default (`dsr1`).
-
-The authoritative list lives in `DB_MODEL_TO_DISPLAY` in `packages/constants/src/`. Representative examples:
-
-| `model=` value | Display name               |
-| -------------- | -------------------------- |
-| `dsr1`         | DeepSeek-R1-0528           |
-| `dsv4`         | DeepSeek-V4-Pro            |
-| `llama70b`     | Llama-3.3-70B-Instruct-FP8 |
-| `llama405b`    | Llama-3.1-405B-Instruct    |
-| `qwen72b`      | Qwen2.5-72B-Instruct       |
-
-### `y` — accepted short-form aliases
-
-Both the short form (`tpPerGpu`) and the full internal form (`y_tpPerGpu`) are accepted. **Short-form aliases listed here cannot be removed.**
-
-| `y=` value         | Meaning                                               |
-| ------------------ | ----------------------------------------------------- |
-| `tpPerGpu`         | Total throughput per GPU (tokens/s/GPU) — **default** |
-| `inputTputPerGpu`  | Input throughput per GPU                              |
-| `outputTputPerGpu` | Output throughput per GPU                             |
-| `tpPerMw`          | Total throughput per MW                               |
-| `inputTputPerMw`   | Input throughput per MW                               |
-| `outputTputPerMw`  | Output throughput per MW                              |
-| `costh`            | Cost per hour                                         |
-| `costn`            | Cost per 1 M input tokens                             |
-| `costr`            | Cost per 1 M output tokens                            |
-| `costhOutput`      | Cost per hour (output)                                |
-| `costnOutput`      | Cost per 1 M input tokens (output)                    |
-| `costrOutput`      | Cost per 1 M output tokens (output)                   |
-| `costhi`           | Cost per hour (interactivity)                         |
-| `costni`           | Cost per 1 M input tokens (interactivity)             |
-| `costri`           | Cost per 1 M output tokens (interactivity)            |
-| `jTotal`           | Joules per total token                                |
-| `jOutput`          | Joules per output token                               |
-| `jInput`           | Joules per input token                                |
-
-### `gpus` — hwKey format
-
-The `gpus` parameter is a comma-separated list of hwKey tokens. Each token encodes the hardware and the inference framework together, separated by an underscore (e.g. `b200_sglang`, `gb300_dynamo-sglang`).
-
-**These tokens are stable.** Any hwKey token that has ever been publicly supported in an embed URL must continue to be accepted. New tokens are added when new hardware or framework combinations are added to the benchmark. Existing tokens cannot be removed; retired hardware tokens simply filter to no visible points (which is the same as the user having toggled that GPU off).
-
-To discover the current set of valid hwKeys, visit `/inference` on the live site, open the legend, and note the identifiers shown — or use **Export → Copy embed** on the chart to copy an iframe snippet that already encodes your current filters.
+| Key        | Type   | Default            | Notes                                                                                                                                                                                                                                                                                                          |
+| ---------- | ------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `g_model`  | string | `DeepSeek-R1-0528` | Display model name — same as `g_model` on the main site.                                                                                                                                                                                                                                                       |
+| `i_seq`    | string | `8k/1k`            | Sequence string (e.g. `8k/1k`, `1k/1k`, `1k/8k`) — same as `i_seq` on the main site.                                                                                                                                                                                                                           |
+| `i_prec`   | string | `fp4`              | Comma-separated precision keys (e.g. `fp4`, `fp8`, `bf16`) — same as `i_prec` on the main site.                                                                                                                                                                                                                |
+| `i_metric` | string | `y_tpPerGpu`       | Y-axis metric key (e.g. `y_tpPerGpu`, `y_costh`) — same as `i_metric` on the main site.                                                                                                                                                                                                                        |
+| `i_active` | string | `` (all visible)   | Comma-separated hwKey allow-list (e.g. `b200_sglang,gb300_dynamo-sglang`). When set, the embed legend and chart universe are restricted to exactly these GPUs. Viewers can toggle them on/off but cannot add GPUs outside this set. When absent, all GPUs for the selected model/sequence/precision are shown. |
+| `i_chart`  | string | `e2e`              | Chart variant to render: `e2e` or `interactivity`. Embed-only key — the main site renders both charts together.                                                                                                                                                                                                |
+
+All other `g_*` / `i_*` keys recognized by the main site (e.g. `i_scale`, `i_hc`, `i_nolabel`) are passed through as-is and respected by the embed — the provider stack is identical. Unknown keys are silently ignored.
+
+### `i_active` — hwKey format
+
+Each hwKey token encodes hardware and inference framework together, separated by an underscore (e.g. `b200_sglang`, `gb300_dynamo-sglang`). To find valid hwKey values, visit `/inference` on the live site, open the legend, and note the identifiers shown — or use **Export → Copy embed** to get a ready-made URL with your current filters already encoded.
+
+### `i_metric` — accepted values
+
+Full `y_*` internal keys (e.g. `y_tpPerGpu`, `y_costh`). The authoritative list is in `packages/app/src/lib/chart-utils.ts` (`Y_AXIS_METRICS`).
 
 ## Embed mode behavior
 
 - Site header, footer, background decorations, and navigation are hidden on all `/embed/*` routes.
-- A "SemiAnalysis InferenceX →" link appears in the chart caption (`Source: …`), deep-linking to the equivalent canonical dashboard URL.
+- A "SemiAnalysis InferenceX →" link appears in the chart caption (`Source: …`), deep-linking to the equivalent canonical dashboard URL. The canonical URL is built from the same embed params (minus `i_chart`), so opening it reproduces the same chart state on the main site.
 - `robots: noindex, nofollow` is set on all embed routes — they won't appear in search results.
-- An `embed_view` PostHog event is fired once on mount, capturing `referrer`, `embed_host`, `embed_chart`, `model`, `sequence`, `gpus`, `y_metric`, and `precisions`. This makes external embed traffic attributable in analytics.
+- An `embed_view` PostHog event is fired once on mount, capturing `referrer`, `embed_host`, `embed_chart`, `model` (`g_model`), `sequence` (`i_seq`), `precisions` (`i_prec`), `gpus` (from `i_active`), and `y_metric` (`i_metric`). This makes external embed traffic attributable in analytics.
 
 ## CSP / framing
 
@@ -102,7 +59,7 @@ All other routes set `frame-ancestors 'self'` and `X-Frame-Options: SAMEORIGIN`,
 
 ```html
 <iframe
-  src="https://inferencex.semianalysis.com/embed/scatter?model=dsr1&isl=8192&osl=1024&precisions=fp4&y=tpPerGpu"
+  src="https://inferencex.semianalysis.com/embed/scatter?g_model=DeepSeek-R1-0528&i_seq=8k%2F1k&i_prec=fp4&i_metric=y_tpPerGpu"
   width="800"
   height="500"
   loading="lazy"

packages/app/cypress/e2e/embed-scatter.cy.ts

@@ -50,9 +50,9 @@ describe('Embed — Scatter Chart', () => {
     });
   });
 
-  describe('custom params', () => {
+  describe('custom params (site-style keys)', () => {
     before(() => {
-      cy.visit('/embed/scatter?model=dsr1&isl=8192&osl=1024&precisions=fp4&y=costh');
+      cy.visit('/embed/scatter?g_model=DeepSeek-R1-0528&i_seq=8k%2F1k&i_prec=fp4&i_metric=y_costh');
     });
 
     it('renders chart with the custom y metric', () => {
@@ -65,18 +65,49 @@ describe('Embed — Scatter Chart', () => {
         .should('have.attr', 'href')
         .and('include', 'i_metric=y_costh');
     });
+
+    it('canonical link does not include i_chart', () => {
+      cy.get('[data-testid="embed-attribution"]')
+        .should('have.attr', 'href')
+        .and('not.include', 'i_chart');
+    });
   });
 
-  describe('gpus param filters the legend', () => {
+  describe('i_active param restricts legend to creator-selected GPUs', () => {
     before(() => {
-      cy.visit('/embed/scatter?gpus=b200_sglang');
+      cy.visit('/embed/scatter?i_active=b200_sglang');
     });
 
-    it('renders chart and legend reflects the active GPU set', () => {
+    it('renders chart without "No data available"', () => {
       cy.get('[data-testid="embed-scatter-figure"]', { timeout: 15000 }).should('exist');
       cy.get('[data-testid="embed-scatter-figure"]').find('svg').should('exist');
       cy.contains('No data available').should('not.exist');
     });
+
+    it('legend contains only the allowed GPU', () => {
+      // Each GPU renders as a <li> inside [data-testid="chart-legend"].
+      // With i_active=b200_sglang, only that GPU is in the allow-list, so
+      // exactly 1 <li> should appear (fp-indicators and controls use <div>).
+      cy.get('[data-testid="embed-scatter-figure"]', { timeout: 15000 }).should('exist');
+      cy.contains('No data available').should('not.exist');
+      cy.get('[data-testid="embed-legend-panel"] [data-testid="chart-legend"] li').should(
+        'have.length',
+        1,
+      );
+    });
+  });
+
+  describe('i_chart param selects chart variant', () => {
+    it('renders e2e chart by default', () => {
+      cy.visit('/embed/scatter');
+      cy.get('[data-testid="embed-scatter-figure"]', { timeout: 15000 }).should('exist');
+    });
+
+    it('renders interactivity chart when i_chart=interactivity', () => {
+      cy.visit('/embed/scatter?i_chart=interactivity');
+      cy.get('[data-testid="embed-scatter-figure"]', { timeout: 15000 }).should('exist');
+      cy.contains('No data available').should('not.exist');
+    });
   });
 
   describe('CSP headers', () => {

packages/app/src/app/embed/scatter/embed-scatter-client.tsx

@@ -7,11 +7,11 @@ import { GlobalFilterProvider } from '@/components/GlobalFilterContext';
 import { InferenceProvider } from '@/components/inference/InferenceContext';
 import { UnofficialRunProvider } from '@/components/unofficial-run-provider';
 import { track } from '@/lib/analytics';
-import { type EmbedParams, embedParamsToUrlState } from '@/lib/embed-params';
-import { seedUrlState } from '@/lib/url-state';
+import { readEmbedChartVariant } from '@/lib/embed-params';
+import { type UrlStateParams, seedUrlState } from '@/lib/url-state';
 
 interface Props {
-  params: EmbedParams;
+  params: UrlStateParams & { i_chart?: string };
   canonicalHref: string;
 }
 
@@ -21,17 +21,35 @@ interface Props {
  * already reflects the requested embed params, then wraps the providers and
  * the chart display.
  *
+ * Embed URLs use the same `g_*` / `i_*` keys as the main site — params flow
+ * straight through `seedUrlState` with no translation. The only embed-specific
+ * key is `i_chart` (which chart variant to render).
+ *
+ * When `i_active` is present, those hwKeys become the allow-list for the embed:
+ * the legend and chart universe are restricted to exactly those GPUs. The
+ * viewer can toggle them on/off but cannot add GPUs outside the set.
+ *
  * Lives outside the `(dashboard)` route group, so we re-establish the
  * provider stack here (`UnofficialRunProvider` → `GlobalFilterProvider` →
  * `InferenceProvider`). `QueryProvider` is in the root layout and inherits.
  */
 export default function EmbedScatterClient({ params, canonicalHref }: Props) {
   const seededRef = useRef(false);
   if (!seededRef.current) {
-    seedUrlState(embedParamsToUrlState(params));
+    // params are already in site-style UrlStateParams shape — seed directly.
+    const { i_chart: _chart, ...urlParams } = params;
+    seedUrlState(urlParams);
     seededRef.current = true;
   }
 
+  const chartType = readEmbedChartVariant(params.i_chart);
+
+  // Build the allow-list from i_active: restrict the embed legend/chart to
+  // only the GPUs the creator chose. null means "no restriction" (all GPUs).
+  const embedAllowedHwTypes = params.i_active
+    ? new Set(params.i_active.split(',').filter(Boolean))
+    : null;
+
   // Fire `embed_view` once on mount with referrer + host so external embed
   // traffic is attributable. Strict mode in dev double-fires effects, but
   // that's only in dev — production fires once.
@@ -46,16 +64,16 @@ export default function EmbedScatterClient({ params, canonicalHref }: Props) {
     } catch {
       embedHost = '';
     }
-    const gpus = params.gpus ? params.gpus.split(',').filter(Boolean) : [];
+    const gpus = params.i_active ? params.i_active.split(',').filter(Boolean) : [];
     track('embed_view', {
       embed_chart: 'scatter',
-      chart_type: params.chart,
-      model: params.model,
-      sequence: `${params.isl}/${params.osl}`,
-      precisions: params.precisions,
+      chart_type: chartType,
+      model: params.g_model,
+      sequence: params.i_seq,
+      precisions: params.i_prec,
       gpus,
       gpu_count: gpus.length,
-      y_metric: params.y,
+      y_metric: params.i_metric,
       referrer,
       embed_host: embedHost,
     });
@@ -64,10 +82,10 @@ export default function EmbedScatterClient({ params, canonicalHref }: Props) {
   return (
     <UnofficialRunProvider>
       <GlobalFilterProvider>
-        <InferenceProvider activeTab="inference">
+        <InferenceProvider activeTab="inference" embedAllowedHwTypes={embedAllowedHwTypes}>
           <div className="flex h-screen min-h-0 flex-col p-1 sm:p-2">
             <div className="min-h-0 flex-1">
-              <EmbedScatterDisplay chartType={params.chart} canonicalHref={canonicalHref} />
+              <EmbedScatterDisplay chartType={chartType} canonicalHref={canonicalHref} />
             </div>
           </div>
         </InferenceProvider>

packages/app/src/app/embed/scatter/page.tsx

@@ -1,7 +1,8 @@
 import type { Metadata } from 'next';
 
 import { SITE_URL } from '@semianalysisai/inferencex-constants';
-import { buildCanonicalHref, readEmbedParams } from '@/lib/embed-params';
+import { buildCanonicalHref } from '@/lib/embed-params';
+import type { UrlStateParams } from '@/lib/url-state';
 
 import EmbedScatterClient from './embed-scatter-client';
 
@@ -16,11 +17,13 @@ export default async function EmbedScatterPage({
   searchParams: Promise<Record<string, string | string[] | undefined>>;
 }) {
   const sp = await searchParams;
-  const flat: Record<string, string | undefined> = {};
+  const flat: UrlStateParams & { i_chart?: string } = {};
   for (const [k, v] of Object.entries(sp)) {
-    flat[k] = Array.isArray(v) ? v[0] : v;
+    const val = Array.isArray(v) ? v[0] : v;
+    if (val !== undefined) {
+      (flat as Record<string, string>)[k] = val;
+    }
   }
-  const params = readEmbedParams(flat);
-  const canonicalHref = buildCanonicalHref(params, SITE_URL);
-  return <EmbedScatterClient params={params} canonicalHref={canonicalHref} />;
+  const canonicalHref = buildCanonicalHref(flat, SITE_URL);
+  return <EmbedScatterClient params={flat} canonicalHref={canonicalHref} />;
 }