web: extract hostContext utilities for the Apps host (AppRenderer/hostContext.ts)

[cliffhall]

Summary

Extract host-context utilities into clients/web/src/components/elements/AppRenderer/hostContext.ts: read the current theme and Mantine design tokens from the DOM, measure the host container, and assemble an initial McpUiHostContext snapshot.

Why

Today the Apps host only tells a widget about theme. The ext-apps spec's hostContext also carries styles, display mode, and container dimensions. Centralizing snapshot/measurement logic in a pure module keeps the renderer thin and makes the follow-up features (full hostContext delivery, live host-context-changed, size-changed) testable in isolation.

Reference implementation (PR #1510)

Re-implement informed by these changes at 33fac3f:

• clients/web/src/components/elements/AppRenderer/hostContext.ts — currentTheme(), currentStyles() (Mantine tokens → McpUiHostStyles via STYLE_VARIABLE_SOURCES), measureContainerDimensions(), snapshotHostContext() (+156 lines)

Depends on

Nothing — Wave 1 foundation, parallel-safe. Consumed later by the hostContext-delivery and size-changed issues.

Notes

• Coverage gate ≥90 on all four dimensions; happy-dom quirks around getBoundingClientRect/computed styles may need justified /* v8 ignore */ comments per AGENTS.md — one line, statement-level (see repo guidance on JSX-adjacent ignores).

Part of the PR #1510 decomposition (see tracking issue).

[cliffhall]

Smoke test & AGENTS.md audit — PR #1591

Audited the extracted host-context utilities (clients/web/src/components/elements/AppRenderer/hostContext.ts: currentTheme, currentStyles, measureContainerDimensions, snapshotHostContext, STYLE_VARIABLE_SOURCES).

Smoke test — method

This is a pure utilities module (no Playwright needed), but the functions touch the DOM / CSS custom properties, so I exercised them under happy-dom via a throwaway vitest. The test sets data-mantine-color-scheme, backs currentStyles() with the real --mantine-* / --inspector-* source variables, mocks a real container's layout box, and also drives the SSR / non-DOM guard branch (document/window stubbed undefined). Real output below.

===== SMOKE: hostContext utilities (DOM path) =====
currentTheme() -> "dark"
currentStyles() -> {
  "variables": {
    "--color-background-primary": "#101113",
    "--color-background-secondary": "#1a1b1e",
    "--color-text-primary": "#c9c9c9",
    "--color-text-secondary": "#909296",
    "--font-sans": "Inter, sans-serif",
    "--border-radius-md": "0.5rem",
    "--shadow-lg": "0 4px 12px rgba(0,0,0,0.3)"
  }
}
measureContainerDimensions(container) -> {"width":813,"height":456}
snapshotHostContext(container, modes) -> {
  "theme": "dark",
  "displayMode": "inline",
  "availableDisplayModes": [
    "inline",
    "fullscreen"
  ],
  "styles": {
    "variables": {
      "--color-background-primary": "#101113",
      "--color-background-secondary": "#1a1b1e",
      "--color-text-primary": "#c9c9c9",
      "--color-text-secondary": "#909296",
      "--font-sans": "Inter, sans-serif",
      "--border-radius-md": "0.5rem",
      "--shadow-lg": "0 4px 12px rgba(0,0,0,0.3)"
    }
  },
  "containerDimensions": {
    "width": 813,
    "height": 456
  }
}
===== END DOM path =====

===== SMOKE: hostContext utilities (non-DOM / SSR) =====
currentTheme() -> "light"
currentStyles() -> undefined
snapshotHostContext(null, ['inline']) -> {
  "theme": "light",
  "displayMode": "inline",
  "availableDisplayModes": [
    "inline"
  ]
}
===== END non-DOM path =====

Observed behavior matches the module's contract exactly:

• currentTheme() reads the resolved data-mantine-color-scheme (dark), falls back to light with no DOM.
• currentStyles() maps spec keys → resolved inspector tokens, trims / keeps non-empty values only, and returns undefined when nothing resolves (SSR).
• measureContainerDimensions() rounds to whole pixels (812.7×456.2 → 813×456).
• snapshotHostContext() omits optional styles / containerDimensions (not set to undefined) — verified in the SSR / null-container snapshot.

AGENTS.md compliance

• Mantine idioms — This is a utilities module, not a component. Its only "styling" reference is the STYLE_VARIABLE_SOURCES map, whose values are CSS variable names (--mantine-* design tokens and --inspector-* tokens like --inspector-surface-card, --inspector-text-secondary, --inspector-log-error). No inline styles, no CSS classes, and no raw hex / rgba() literals in the source. Compliant.
• TypeScript — No any, no ts-ignore / ts-expect-error / eslint-disable, no v8 ignore. Type-safety via Partial<Record<McpUiStyleVariableKey, string>>, a typed Object.entries cast, and NonNullable<McpUiHostContext["containerDimensions"]> for the ContainerDimensions alias. Clean.
• Coverage — hostContext.ts is 100 / 100 / 100 / 100 (statements / branches / functions / lines); all 20 unit tests pass. Confirms the reported 100%.

File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
  hostContext.ts   |     100 |      100 |     100 |     100 |

Note: the full clients/web test:coverage run currently reports 6 failures in unrelated files (useServers, PromptArgumentsForm, InspectorView localStorage, ServerConfigModal) — all timing / waitFor / fake-timer / localStorage flakes surfacing under a fully-instrumented ~337s run on a loaded machine, none touching hostContext. The per-file hostContext.ts numbers above are authoritative.

Verdict

APPROVE. Clean pure extraction — behavior verified end-to-end (DOM + SSR paths), 100% coverage confirmed, and fully AGENTS.md-compliant (Mantine token usage, no any/suppressions, no raw color literals).

Throwaway smoke script (not committed)

import { describe, it, vi } from "vitest";
import type { McpUiDisplayMode } from "@modelcontextprotocol/ext-apps/app-bridge";
import {
  currentStyles,
  currentTheme,
  measureContainerDimensions,
  snapshotHostContext,
} from "./hostContext";

describe("SMOKE hostContext", () => {
  it("produces a real host-context snapshot (DOM path)", () => {
    document.documentElement.setAttribute("data-mantine-color-scheme", "dark");
    const root = document.documentElement.style;
    root.setProperty("--mantine-color-body", "#101113");
    root.setProperty("--mantine-color-text", "#c9c9c9");
    root.setProperty("--inspector-surface-card", "#1a1b1e");
    root.setProperty("--inspector-text-secondary", "#909296");
    root.setProperty("--mantine-font-family", "Inter, sans-serif");
    root.setProperty("--mantine-radius-md", "0.5rem");
    root.setProperty("--mantine-shadow-lg", "0 4px 12px rgba(0,0,0,0.3)");

    const resolved: Record<string, string> = {
      "--mantine-color-body": "#101113",
      "--mantine-color-text": "#c9c9c9",
      "--inspector-surface-card": "#1a1b1e",
      "--inspector-text-secondary": "#909296",
      "--mantine-font-family": "Inter, sans-serif",
      "--mantine-radius-md": "0.5rem",
      "--mantine-shadow-lg": "0 4px 12px rgba(0,0,0,0.3)",
    };
    vi.spyOn(window, "getComputedStyle").mockReturnValue({
      getPropertyValue: (name: string) => resolved[name] ?? "",
    } as unknown as CSSStyleDeclaration);

    const container = document.createElement("div");
    vi.spyOn(container, "getBoundingClientRect").mockReturnValue({
      width: 812.7,
      height: 456.2,
    } as DOMRect);

    const modes: readonly McpUiDisplayMode[] = ["inline", "fullscreen"];
    console.log("currentTheme() ->", JSON.stringify(currentTheme()));
    console.log("currentStyles() ->", JSON.stringify(currentStyles(), null, 2));
    console.log(
      "measureContainerDimensions(container) ->",
      JSON.stringify(measureContainerDimensions(container)),
    );
    console.log(
      "snapshotHostContext(container, modes) ->",
      JSON.stringify(snapshotHostContext(container, modes), null, 2),
    );
  });

  it("exercises the SSR / non-DOM guard branch", () => {
    vi.stubGlobal("document", undefined);
    vi.stubGlobal("window", undefined);
    console.log("currentTheme() ->", JSON.stringify(currentTheme()));
    console.log("currentStyles() ->", JSON.stringify(currentStyles()));
    console.log(
      "snapshotHostContext(null, ['inline']) ->",
      JSON.stringify(snapshotHostContext(null, ["inline"]), null, 2),
    );
    vi.unstubAllGlobals();
  });
});

Run with: npx vitest run --project unit --disableConsoleIntercept <file>

[cliffhall]

🔗 Implemented by PR #1591. Its code is already integrated into the Wave 1 rollup branch 1579-wave-1 (see rollup PR #1601 / verification #1600). #1591 currently targets v2/main and will auto-show as Merged once the rollup lands in v2/main. The Development panel doesn't link it now because the closing keyword is on a non-default base branch.