feat(server): cover element detail normalization and shaping

Author: ashtonchew

packages/server/src/__tests__/utils/element-detail.test.ts

@@ -0,0 +1,80 @@
+import {
+  normalizeDetailParameters,
+  normalizeCssLevel,
+  normalizeTextDetail,
+  shapeElementForDetail,
+} from '../../utils/element-detail';
+import { createMockElement } from '../test-helpers';
+
+describe('element-detail utilities', () => {
+  describe('normalizeTextDetail', () => {
+    it('returns defaults for invalid values', () => {
+      expect(normalizeTextDetail(undefined)).toBe('full');
+      expect(normalizeTextDetail('VISIBLE')).toBe('visible');
+      expect(normalizeTextDetail('invalid', 'visible')).toBe('visible');
+    });
+  });
+
+  describe('normalizeCssLevel', () => {
+    it('coerces numeric strings and falls back to default', () => {
+      expect(normalizeCssLevel('2')).toBe(2);
+      expect(normalizeCssLevel('not-a-number', 3)).toBe(3);
+      expect(normalizeCssLevel(undefined)).toBe(1);
+    });
+  });
+
+  describe('normalizeDetailParameters', () => {
+    it('applies defaults when params are missing', () => {
+      expect(normalizeDetailParameters(undefined)).toEqual({
+        textDetail: 'full',
+        cssLevel: 1,
+      });
+    });
+
+    it('normalizes provided params', () => {
+      expect(normalizeDetailParameters({ textDetail: 'visible', cssLevel: '0' })).toEqual({
+        textDetail: 'visible',
+        cssLevel: 0,
+      });
+    });
+  });
+
+  describe('shapeElementForDetail', () => {
+    it('omits text and css when levels request none', () => {
+      const element = createMockElement();
+      const shaped = shapeElementForDetail(element, 'none', 0);
+
+      expect(shaped.innerText).toBeUndefined();
+      expect(shaped.textContent).toBeUndefined();
+      expect(shaped.cssProperties).toBeUndefined();
+      expect(shaped.cssLevel).toBe(0);
+    });
+
+    it('returns visible text and level 1 css subset', () => {
+      const element = createMockElement();
+      element.textVariants!.visible = 'Visible text only';
+      element.textVariants!.full = 'Visible text only with hidden';
+      const shaped = shapeElementForDetail(element, 'visible', 1);
+
+      expect(shaped.innerText).toBe('Visible text only');
+      expect(shaped.textContent).toBeUndefined();
+      expect(shaped.cssProperties).toBeDefined();
+      expect(Object.keys(shaped.cssProperties!)).toContain('display');
+      expect(Object.keys(shaped.cssProperties!)).not.toContain('marginTop');
+    });
+
+    it('returns full css when level 3 requested', () => {
+      const element = createMockElement();
+      element.cssComputed = {
+        ...element.cssProperties!,
+        marginTop: '5px',
+      };
+
+      const shaped = shapeElementForDetail(element, 'full', 3);
+      expect(shaped.cssProperties).toEqual({
+        ...element.cssComputed,
+      });
+      expect(shaped.textContent).toBe(element.textVariants!.full);
+    });
+  });
+});

packages/server/src/utils/element-detail.ts

@@ -0,0 +1,196 @@
+import {
+  CSSDetailLevel,
+  CSSProperties,
+  DEFAULT_CSS_LEVEL,
+  DEFAULT_TEXT_DETAIL,
+  TargetedElement,
+  TextDetailLevel,
+  TextSnapshots,
+} from '@mcp-pointer/shared/types';
+import {
+  CSS_LEVEL_FIELD_MAP,
+  isValidCSSLevel,
+  isValidTextDetail,
+} from '@mcp-pointer/shared/detail';
+
+export interface DetailParameters {
+  textDetail?: unknown;
+  cssLevel?: unknown;
+}
+
+export interface NormalizedDetailParameters {
+  textDetail: TextDetailLevel;
+  cssLevel: CSSDetailLevel;
+}
+
+function toNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (typeof value === 'string' && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (!Number.isNaN(parsed)) {
+      return parsed;
+    }
+  }
+
+  return null;
+}
+
+export function normalizeTextDetail(
+  detail: unknown,
+  fallback: TextDetailLevel = DEFAULT_TEXT_DETAIL,
+): TextDetailLevel {
+  if (isValidTextDetail(detail)) {
+    return detail;
+  }
+
+  if (typeof detail === 'string') {
+    const lowered = detail.toLowerCase();
+    if (isValidTextDetail(lowered)) {
+      return lowered as TextDetailLevel;
+    }
+  }
+
+  return fallback;
+}
+
+export function normalizeCssLevel(
+  level: unknown,
+  fallback: CSSDetailLevel = DEFAULT_CSS_LEVEL,
+): CSSDetailLevel {
+  if (isValidCSSLevel(level)) {
+    return level;
+  }
+
+  const parsed = toNumber(level);
+  if (parsed !== null && isValidCSSLevel(parsed)) {
+    return parsed;
+  }
+
+  return fallback;
+}
+
+export function normalizeDetailParameters(
+  params: DetailParameters | undefined,
+  defaults?: Partial<NormalizedDetailParameters>,
+): NormalizedDetailParameters {
+  return {
+    textDetail: normalizeTextDetail(
+      params?.textDetail,
+      defaults?.textDetail ?? DEFAULT_TEXT_DETAIL,
+    ),
+    cssLevel: normalizeCssLevel(
+      params?.cssLevel,
+      defaults?.cssLevel ?? DEFAULT_CSS_LEVEL,
+    ),
+  };
+}
+
+function resolveTextVariants(element: TargetedElement): TextSnapshots {
+  const visible = element.textVariants?.visible ?? element.innerText ?? '';
+  const full = element.textVariants?.full ?? element.textContent ?? visible;
+
+  return {
+    visible,
+    full,
+  };
+}
+
+function resolveTextContent(
+  variants: TextSnapshots,
+  detail: TextDetailLevel,
+): string | undefined {
+  if (detail === 'none') {
+    return undefined;
+  }
+
+  if (detail === 'visible') {
+    return variants.visible;
+  }
+
+  return variants.full || variants.visible;
+}
+
+function buildCssProperties(
+  element: TargetedElement,
+  cssLevel: CSSDetailLevel,
+): CSSProperties | undefined {
+  if (cssLevel === 0) {
+    return undefined;
+  }
+
+  if (cssLevel === 3) {
+    if (element.cssComputed) {
+      return { ...element.cssComputed };
+    }
+
+    if (element.cssProperties) {
+      return { ...element.cssProperties };
+    }
+
+    return undefined;
+  }
+
+  const fields = CSS_LEVEL_FIELD_MAP[cssLevel];
+  const cssProperties: CSSProperties = {};
+  const source = element.cssComputed ?? element.cssProperties ?? {};
+
+  fields.forEach((property) => {
+    const value = source[property];
+    if (value !== undefined) {
+      cssProperties[property] = value;
+    }
+  });
+
+  if (Object.keys(cssProperties).length > 0) {
+    return cssProperties;
+  }
+
+  if (element.cssProperties) {
+    return { ...element.cssProperties };
+  }
+
+  return undefined;
+}
+
+export function shapeElementForDetail(
+  element: TargetedElement,
+  detail: TextDetailLevel,
+  cssLevel: CSSDetailLevel,
+): TargetedElement {
+  const variants = resolveTextVariants(element);
+  const resolvedText = resolveTextContent(variants, detail);
+  const textContent = detail === 'full' ? variants.full : undefined;
+  const cssProperties = buildCssProperties(element, cssLevel);
+
+  const shaped: TargetedElement = {
+    selector: element.selector,
+    tagName: element.tagName,
+    id: element.id,
+    classes: [...element.classes],
+    attributes: { ...element.attributes },
+    position: { ...element.position },
+    cssLevel,
+    componentInfo: element.componentInfo ? { ...element.componentInfo } : undefined,
+    timestamp: element.timestamp,
+    url: element.url,
+    tabId: element.tabId,
+    textDetail: detail,
+  };
+
+  if (resolvedText !== undefined) {
+    shaped.innerText = resolvedText;
+  }
+
+  if (textContent !== undefined) {
+    shaped.textContent = textContent;
+  }
+
+  if (cssProperties) {
+    shaped.cssProperties = cssProperties;
+  }
+
+  return shaped;
+}