@stigmer/react 3.6.0 → 3.8.0

package/src/models/ModelSelector.tsx

@@ -4,9 +4,11 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Popover } from "@base-ui/react/popover";
 import { cn } from "@stigmer/theme";
 import { useStigmerPortalContainer } from "../portal-container.js";
+import { Switch } from "../switch/Switch.js";
 import { useModelRegistry } from "./useModelRegistry.js";
 import type { ModelInfo, CostTier, SpeedTier } from "./registry.js";
 import { HARNESS_META, HARNESS_OPTIONS, type HarnessOption } from "./harness.js";
+import { FAST_SERVICE_TIER, type ServiceTierOption } from "./service-tier.js";
 
 const COST_TIER_LABEL: Record<CostTier, string> = {
   economy: "$",
@@ -61,6 +63,37 @@ export interface ModelSelectorProps {
   readonly className?: string;
   /** When true, disables the selector. */
   readonly disabled?: boolean;
+  /**
+   * Trigger label shown while `value` is empty, instead of falling back
+   * to the registry's default model. Lets a form distinguish "nothing
+   * pinned — the platform default applies" from an actual selection
+   * (the schedule form's contract: an unset model inherits the
+   * surface's platform default). The harness prefix is hidden while
+   * the placeholder shows, since no engine is pinned either.
+   */
+  readonly placeholderLabel?: string;
+
+  /**
+   * Current service tier for the selected model (stigmer/stigmer#357).
+   * Defaults to "standard". Only meaningful together with
+   * {@link onServiceTierChange}.
+   */
+  readonly serviceTier?: ServiceTierOption;
+  /**
+   * Called when the user toggles the fast tier. Providing this enables the
+   * "Fast tier" switch in the popover's options area (top of the popover,
+   * beside the harness row — the Cursor options-panel convention), which
+   * renders ONLY while the selected model prices a fast variant
+   * ({@link ModelInfo.serviceTiers}) — no dead controls.
+   *
+   * An active fast tier persists across switches between fast-capable
+   * models (the tier is always visible: trigger badge + options switch),
+   * so "fast, but on that other model" is one action, not a re-toggle.
+   * Selecting a model without a fast tier resets to "standard" through
+   * this callback — an unsupported combination can never be submitted
+   * (#357, refused at create time).
+   */
+  readonly onServiceTierChange?: (tier: ServiceTierOption) => void;
 
   /**
    * @deprecated Use {@link onHarnessChange} instead.
@@ -79,6 +112,19 @@ export interface ModelSelectorProps {
  * The trigger button displays the current selection in compact format:
  * `Harness · Model Name ▾` (or just `Model Name ▾` when harness is locked).
  *
+ * **Service tier (#357).** When the consumer opts in via
+ * {@link ModelSelectorProps.onServiceTierChange} and the selected model
+ * prices a fast variant, a "Fast tier" switch renders in the options area
+ * at the TOP of the popover — the first thing visible on open, mirroring
+ * Cursor's own options panel (Jakob's Law: our users already know that
+ * layout). Deliberately not a per-row affordance: row-level chips crowd
+ * the rows and collide with the "Fast/Fastest" speed badge, and an
+ * interactive element inside `role="option"` is an ARIA authoring error
+ * (option children are presentational). An active fast tier persists
+ * across switches between fast-capable models — the visible badge and
+ * switch keep the state honest — and resets only for models with no fast
+ * variant, where it would be refused at create time.
+ *
  * @example
  * ```tsx
  * <ModelSelector
@@ -104,6 +150,9 @@ export function ModelSelector({
   compact = false,
   className,
   disabled,
+  placeholderLabel,
+  serviceTier = "standard",
+  onServiceTierChange,
 }: ModelSelectorProps) {
   const portalContainer = useStigmerPortalContainer();
 
@@ -216,9 +265,21 @@ export function ModelSelector({
   const selectModel = useCallback(
     (model: ModelInfo) => {
       onValueChange(model.modelId);
+      // An active fast tier survives a switch between fast-capable models —
+      // resetting it forced users to re-toggle on every model change, and
+      // the tier is never silent (trigger badge + options switch both show
+      // it). It resets ONLY when the new model prices no fast variant: a
+      // stale tier there would be refused at create time (#357).
+      if (
+        serviceTier === "fast"
+        && onServiceTierChange
+        && !model.serviceTiers.includes(FAST_SERVICE_TIER)
+      ) {
+        onServiceTierChange("standard");
+      }
       setOpen(false);
     },
-    [onValueChange],
+    [onValueChange, serviceTier, onServiceTierChange],
   );
 
   const scrollHighlightIntoView = useCallback((idx: number) => {
@@ -229,7 +290,7 @@ export function ModelSelector({
   }, []);
 
   const handleKeyDown = useCallback(
-    (e: React.KeyboardEvent) => {
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
       const len = visibleModels.length;
       if (len === 0) return;
 
@@ -265,8 +326,27 @@ export function ModelSelector({
 
   const showShowAllButton = !isSearching && !showAll && featuredModels.length > 0 && featuredModels.length < models.length;
 
-  const triggerLabel = selectedModel?.displayName ?? "Select model";
-  const triggerHarness = !isHarnessLocked ? HARNESS_META[activeHarness].label : undefined;
+  // The options-area switch exists only where it applies: a consumer opted
+  // in AND the selected model prices a fast variant (recognition over
+  // recall — never a dead control on models with no tier choice).
+  const showServiceTierToggle =
+    onServiceTierChange !== undefined
+    && selectedModel !== undefined
+    && selectedModel.serviceTiers.includes(FAST_SERVICE_TIER);
+  // The trigger badge is display-only: fast is in effect iff the tier is
+  // fast AND the selected model actually prices the variant.
+  const fastActive =
+    serviceTier === "fast"
+    && (selectedModel?.serviceTiers.includes(FAST_SERVICE_TIER) ?? false);
+
+  const usingPlaceholder = !value && placeholderLabel !== undefined;
+  const triggerLabel = usingPlaceholder
+    ? placeholderLabel
+    : (selectedModel?.displayName ?? "Select model");
+  const triggerHarness =
+    !isHarnessLocked && !usingPlaceholder
+      ? HARNESS_META[activeHarness].label
+      : undefined;
 
   return (
     <Popover.Root open={open} onOpenChange={setOpen}>
@@ -288,6 +368,17 @@ export function ModelSelector({
           <span className="shrink-0 text-border" aria-hidden>·</span>
         )}
         <span className="truncate">{triggerLabel}</span>
+        {fastActive && (
+          <span
+            className={cn(
+              "inline-flex shrink-0 items-center gap-0.5 rounded-full border border-primary px-1.5 py-px",
+              "text-[0.6rem] font-medium uppercase tracking-wider text-primary",
+            )}
+          >
+            <BoltIcon />
+            Fast
+          </span>
+        )}
         <ChevronIcon />
       </Popover.Trigger>
 
@@ -369,6 +460,29 @@ export function ModelSelector({
               )}
             </div>
 
+            {/* Options area — the Cursor options-panel convention: settings
+                of the CURRENT selection sit at the top of the popover, the
+                first thing visible on open, never buried under the list.
+                Rendered only while the selected model prices a fast
+                variant (#357). */}
+            {showServiceTierToggle && (
+              <div className="flex items-center justify-between border-b border-border px-3 py-2">
+                <div className="flex flex-col">
+                  <span className="text-xs text-foreground">Fast tier</span>
+                  <span className="text-[0.65rem] text-muted-foreground">
+                    Faster responses at higher per-token rates
+                  </span>
+                </div>
+                <Switch
+                  checked={fastActive}
+                  onCheckedChange={(next) =>
+                    onServiceTierChange?.(next ? "fast" : "standard")
+                  }
+                  aria-label="Fast tier"
+                />
+              </div>
+            )}
+
             {/* Search input */}
             <div className="border-b border-border px-3 py-1.5">
               <input
@@ -568,3 +682,18 @@ function CheckIcon({ className }: { className?: string }) {
     </svg>
   );
 }
+
+function BoltIcon() {
+  return (
+    <svg
+      className="shrink-0"
+      width="8"
+      height="10"
+      viewBox="0 0 8 10"
+      fill="currentColor"
+      aria-hidden
+    >
+      <path d="M4.9 0.2L0.6 5.6h2.6L3.1 9.8l4.3-5.4H4.8L4.9 0.2z" />
+    </svg>
+  );
+}

package/src/models/__tests__/ModelSelector-serviceTier.test.tsx

@@ -0,0 +1,256 @@
+import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { ModelSelector } from "../ModelSelector";
+import { ModelRegistryContext } from "../ModelRegistryContext";
+import type { ModelInfo } from "../registry";
+
+// Portal into document.body so the popover mounts under happy-dom, and shim
+// ResizeObserver for Base UI's positioner (the scheduleCreation.test.tsx
+// pattern).
+vi.mock("../../portal-container", () => ({
+  useStigmerPortalContainer: () => document.body,
+}));
+
+beforeAll(() => {
+  if (!("ResizeObserver" in globalThis)) {
+    (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver =
+      class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      };
+  }
+});
+
+/**
+ * Fast-tier switch in the popover's options area (stigmer/stigmer#357).
+ *
+ * The switch sits at the TOP of the popover (the Cursor options-panel
+ * convention) and is capability-gated: it renders only when the consumer
+ * opted in (onServiceTierChange) AND the selected model prices a fast
+ * variant (ModelInfo.serviceTiers) — no dead controls. An active fast
+ * tier persists across switches between fast-capable models (the trigger
+ * badge and the switch keep the state visible), and resets ONLY when the
+ * chosen model prices no fast variant — a stale tier there would be
+ * refused at create time.
+ */
+
+const FAST_CAPABLE: ModelInfo = {
+  modelId: "composer-2.5",
+  provider: "cursor",
+  displayName: "Composer 2.5",
+  shortDescription: "Fast agentic model",
+  speedTier: "fastest",
+  costTier: "economy",
+  harness: "cursor",
+  featured: true,
+  serviceTiers: ["fast"],
+};
+
+const ALSO_FAST_CAPABLE: ModelInfo = {
+  modelId: "claude-opus-4-8",
+  provider: "anthropic",
+  displayName: "Claude 4.8 Opus",
+  shortDescription: "Frontier Opus via Cursor",
+  speedTier: "slow",
+  costTier: "premium",
+  harness: "cursor",
+  featured: true,
+  serviceTiers: ["fast"],
+};
+
+const NO_FAST_TIER: ModelInfo = {
+  modelId: "claude-haiku-4-5",
+  provider: "anthropic",
+  displayName: "Haiku 4.5",
+  shortDescription: "Small fast model",
+  speedTier: "fastest",
+  costTier: "economy",
+  harness: "cursor",
+  featured: true,
+  serviceTiers: [],
+};
+
+function renderSelector(
+  props?: Partial<React.ComponentProps<typeof ModelSelector>>,
+) {
+  const onValueChange = vi.fn();
+  const onServiceTierChange = vi.fn();
+
+  const result = render(
+    <ModelRegistryContext.Provider
+      value={{
+        models: [FAST_CAPABLE, ALSO_FAST_CAPABLE, NO_FAST_TIER],
+        isLoading: false,
+        error: null,
+        refetch: vi.fn(),
+      }}
+    >
+      <ModelSelector
+        value="composer-2.5"
+        onValueChange={onValueChange}
+        harness="cursor"
+        serviceTier="standard"
+        onServiceTierChange={onServiceTierChange}
+        {...props}
+      />
+    </ModelRegistryContext.Provider>,
+  );
+
+  return { ...result, onValueChange, onServiceTierChange };
+}
+
+/**
+ * Open the popover via its trigger and wait for the portaled popup to
+ * mount (Base UI portals render asynchronously in jsdom). The search
+ * input is the popup's always-present landmark.
+ */
+async function openPopover(triggerLabel: string) {
+  fireEvent.click(screen.getByRole("button", { name: new RegExp(triggerLabel) }));
+  await screen.findByPlaceholderText("Search models…");
+}
+
+/** A model row inside the popup list (never matches the trigger). */
+function modelOption(displayName: string): HTMLElement {
+  const option = screen
+    .getAllByText(displayName)
+    .map((el) => el.closest<HTMLElement>("[data-model-option]"))
+    .find((el) => el != null);
+  if (!option) throw new Error(`No popup option for "${displayName}"`);
+  return option;
+}
+
+afterEach(cleanup);
+
+describe("ModelSelector — fast tier switch in the options area", () => {
+  it("renders the switch for a fast-capable selected model", async () => {
+    renderSelector();
+    await openPopover("Composer 2.5");
+
+    const toggle = screen.getByRole("switch", { name: "Fast tier" });
+    expect(toggle.getAttribute("aria-checked")).toBe("false");
+  });
+
+  it("places the switch in the options area above the model list", async () => {
+    renderSelector();
+    await openPopover("Composer 2.5");
+
+    const toggle = screen.getByRole("switch", { name: "Fast tier" });
+    const search = screen.getByRole("searchbox", { name: "Search models" });
+    // DOCUMENT_POSITION_FOLLOWING: the search input comes after the switch,
+    // i.e. the options area precedes search + list (never a footer).
+    expect(
+      toggle.compareDocumentPosition(search)
+        & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("does not render the switch for a model without a fast tier", async () => {
+    renderSelector({ value: "claude-haiku-4-5" });
+    await openPopover("Haiku 4.5");
+
+    expect(screen.queryByRole("switch", { name: "Fast tier" })).toBeNull();
+  });
+
+  it("does not render the switch when the consumer did not opt in", async () => {
+    renderSelector({ onServiceTierChange: undefined });
+    await openPopover("Composer 2.5");
+
+    expect(screen.queryByRole("switch", { name: "Fast tier" })).toBeNull();
+  });
+
+  it("toggling fires onServiceTierChange with the flipped tier", async () => {
+    const { onServiceTierChange } = renderSelector();
+    await openPopover("Composer 2.5");
+
+    fireEvent.click(screen.getByRole("switch", { name: "Fast tier" }));
+    expect(onServiceTierChange).toHaveBeenCalledOnce();
+    expect(onServiceTierChange).toHaveBeenCalledWith("fast");
+  });
+
+  it("toggling off an active fast tier fires 'standard'", async () => {
+    const { onServiceTierChange } = renderSelector({ serviceTier: "fast" });
+    await openPopover("Composer 2.5");
+
+    fireEvent.click(screen.getByRole("switch", { name: "Fast tier" }));
+    expect(onServiceTierChange).toHaveBeenCalledOnce();
+    expect(onServiceTierChange).toHaveBeenCalledWith("standard");
+  });
+
+  it("keeps the popover open across a toggle", async () => {
+    renderSelector();
+    await openPopover("Composer 2.5");
+
+    fireEvent.click(screen.getByRole("switch", { name: "Fast tier" }));
+    expect(screen.getByPlaceholderText("Search models…")).toBeTruthy();
+  });
+});
+
+describe("ModelSelector — trigger badge", () => {
+  it("shows the Fast badge on the trigger when the fast tier is active", () => {
+    renderSelector({ serviceTier: "fast" });
+
+    expect(screen.getByText("Fast")).toBeTruthy();
+  });
+
+  it("hides the badge when the selected model has no fast tier", () => {
+    renderSelector({ serviceTier: "fast", value: "claude-haiku-4-5" });
+
+    expect(screen.queryByText("Fast")).toBeNull();
+  });
+});
+
+describe("ModelSelector — fast tier persistence across model switches", () => {
+  it("selecting a model while standard emits no tier change", async () => {
+    const { onValueChange, onServiceTierChange } = renderSelector();
+    await openPopover("Composer 2.5");
+
+    fireEvent.click(modelOption("Composer 2.5"));
+
+    expect(onValueChange).toHaveBeenCalledWith("composer-2.5");
+    expect(onServiceTierChange).not.toHaveBeenCalled();
+  });
+
+  it("keeps an active fast tier when selecting another fast-capable model", async () => {
+    // "Fast, but on that other model" is one action — resetting here made
+    // users re-toggle on every model change, and the tier is never silent
+    // (trigger badge + options switch both show it).
+    const { onValueChange, onServiceTierChange } = renderSelector({
+      serviceTier: "fast",
+    });
+    await openPopover("Composer 2.5");
+
+    fireEvent.click(modelOption("Claude 4.8 Opus"));
+
+    expect(onValueChange).toHaveBeenCalledWith("claude-opus-4-8");
+    expect(onServiceTierChange).not.toHaveBeenCalled();
+  });
+
+  it("toggle-then-pick works in a single popover visit", async () => {
+    // Flip the switch first (popover stays open), then pick a fast-capable
+    // model: the toggle survives the selection.
+    const { onValueChange, onServiceTierChange } = renderSelector();
+    await openPopover("Composer 2.5");
+
+    fireEvent.click(screen.getByRole("switch", { name: "Fast tier" }));
+    fireEvent.click(modelOption("Claude 4.8 Opus"));
+
+    expect(onServiceTierChange).toHaveBeenCalledOnce();
+    expect(onServiceTierChange).toHaveBeenCalledWith("fast");
+    expect(onValueChange).toHaveBeenCalledWith("claude-opus-4-8");
+  });
+
+  it("resets an active fast tier when selecting a model without one", async () => {
+    const { onValueChange, onServiceTierChange } = renderSelector({
+      serviceTier: "fast",
+    });
+    await openPopover("Composer 2.5");
+
+    fireEvent.click(modelOption("Haiku 4.5"));
+
+    expect(onValueChange).toHaveBeenCalledOnce();
+    expect(onValueChange).toHaveBeenCalledWith("claude-haiku-4-5");
+    expect(onServiceTierChange).toHaveBeenCalledOnce();
+    expect(onServiceTierChange).toHaveBeenCalledWith("standard");
+  });
+});

package/src/models/__tests__/useModelRegistry.test.tsx

@@ -73,6 +73,9 @@ const TEST_REGISTRY_JSON = {
       costTier: "standard",
       featured: false,
       pricing: { inputPricePerMillion: 3, outputPricePerMillion: 15, cacheWritePricePerMillion: 3.75, cacheReadPricePerMillion: 0.3 },
+      pricingVariants: {
+        fast: { inputPricePerMillion: 18, outputPricePerMillion: 90 },
+      },
     },
     {
       id: "ollama-local",
@@ -103,6 +106,18 @@ function createWrapper(models: readonly ModelInfo[] = TEST_MODELS) {
   };
 }
 
+describe("parseRegistryJson service tiers (#357)", () => {
+  it("surfaces pricingVariants keys as serviceTiers", () => {
+    const withVariants = TEST_MODELS.find((m) => m.modelId === "claude-4.6-sonnet");
+    expect(withVariants?.serviceTiers).toEqual(["fast"]);
+  });
+
+  it("yields an empty serviceTiers list for models without variants", () => {
+    const withoutVariants = TEST_MODELS.find((m) => m.modelId === "claude-sonnet-4.6");
+    expect(withoutVariants?.serviceTiers).toEqual([]);
+  });
+});
+
 describe("useModelRegistry", () => {
   describe("unified mode (no harness)", () => {
     it("excludes DISABLED_PROVIDERS from models", () => {

package/src/models/index.ts

@@ -11,3 +11,5 @@ export { HarnessSelector } from "./HarnessSelector.js";
 export type { HarnessSelectorProps } from "./HarnessSelector.js";
 export { DEFAULT_HARNESS, HARNESS_LABELS, HARNESS_META, HARNESS_OPTIONS, toProtoHarness, fromProtoHarness } from "./harness.js";
 export type { HarnessOption, HarnessDisplayInfo } from "./harness.js";
+export { FAST_SERVICE_TIER, toProtoServiceTier, fromProtoServiceTier } from "./service-tier.js";
+export type { ServiceTierOption } from "./service-tier.js";

package/src/models/registry.ts

@@ -89,6 +89,17 @@ export interface ModelInfo {
    * before "Show All Models" is expanded or search is used).
    */
   readonly featured: boolean;
+  /**
+   * Pricing-variant keys the registry prices for this model (e.g.
+   * `["fast"]`). A priced variant is a *selectable* service tier
+   * (stigmer/stigmer#357): the fast-tier switch in the model popover's
+   * options area renders only while the selected model's `serviceTiers`
+   * includes it. Empty for models with no variants.
+   *
+   * Distinct from {@link speedTier}, which is a static latency badge,
+   * not a selectable option.
+   */
+  readonly serviceTiers: readonly string[];
 }
 
 /**
@@ -153,6 +164,8 @@ interface RegistryJsonEntry {
     cacheWritePricePerMillion: number;
     cacheReadPricePerMillion: number;
   };
+  /** Variant-key → variant pricing block; only the key set matters here. */
+  pricingVariants?: Record<string, unknown>;
   $comment?: string;
 }
 
@@ -192,6 +205,10 @@ export function parseRegistryJson(data: unknown): ModelInfo[] {
       costTier: m.costTier as CostTier,
       harness: m.harness as HarnessOption,
       featured: m.featured ?? false,
+      serviceTiers:
+        m.pricingVariants && typeof m.pricingVariants === "object"
+          ? Object.keys(m.pricingVariants).sort()
+          : [],
     }));
 }
 

package/src/models/service-tier.ts

@@ -0,0 +1,49 @@
+import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/**
+ * String form of the service tier for component props and hook inputs
+ * (stigmer/stigmer#357). Mirrors {@link HarnessOption}: components speak
+ * strings, execution creation speaks proto.
+ *
+ * "standard" is the model's base-priced configuration; "fast" is the
+ * provider's fast variant at the registry's fast rates — selectable only
+ * for models whose {@link ModelInfo.serviceTiers} includes "fast".
+ */
+export type ServiceTierOption = "standard" | "fast";
+
+/** The tier key a model must price for the fast-tier switch to render. */
+export const FAST_SERVICE_TIER = "fast";
+
+/**
+ * Convert a {@link ServiceTierOption} string to the proto enum.
+ */
+export function toProtoServiceTier(tier: ServiceTierOption): ServiceTier {
+  switch (tier) {
+    case "fast":
+      return ServiceTier.FAST;
+    case "standard":
+    default:
+      return ServiceTier.STANDARD;
+  }
+}
+
+/**
+ * Convert a proto {@link ServiceTier} enum to its string form.
+ *
+ * `UNSPECIFIED` (and any unknown value) maps to `undefined` so callers can
+ * decide their own default — matching the proto contract (`UNSPECIFIED`
+ * resolves to `SERVICE_TIER_STANDARD` in the runner, never the provider
+ * account default).
+ */
+export function fromProtoServiceTier(
+  tier: ServiceTier | undefined,
+): ServiceTierOption | undefined {
+  switch (tier) {
+    case ServiceTier.STANDARD:
+      return "standard";
+    case ServiceTier.FAST:
+      return "fast";
+    default:
+      return undefined;
+  }
+}