feat(shared): switch detail levels to enums

Author: ashtonchew

packages/server/src/__tests__/test-helpers.ts

@@ -1,7 +1,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
-import { TargetedElement } from '@mcp-pointer/shared/types';
+import { TargetedElement, TextDetailLevel, CSSDetailLevel } from '@mcp-pointer/shared/types';
 
 // Test constants - use a temp directory that works in Jest
 export const TEST_MCP_POINTER_PORT = 7008;
@@ -33,7 +33,7 @@ export function createMockElement(): TargetedElement {
     classes: ['test-class'],
     innerText: text,
     textContent: text,
-    textDetail: 'full',
+    textDetail: TextDetailLevel.FULL,
     textVariants: {
       visible: text,
       full: text,
@@ -42,7 +42,7 @@ export function createMockElement(): TargetedElement {
     position: {
       x: 100, y: 200, width: 300, height: 50,
     },
-    cssLevel: 1,
+    cssLevel: CSSDetailLevel.BASIC,
     cssProperties: {
       display: 'block',
       position: 'relative',

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

@@ -1,8 +1,9 @@
+import { CSSDetailLevel, TextDetailLevel } from '@mcp-pointer/shared/types';
 import {
   normalizeDetailParameters,
   normalizeCssLevel,
   normalizeTextDetail,
-  shapeElementForDetail,
+  serializeElement,
 } from '../../utils/element-detail';
 import { ProcessedPointedDOMElement } from '../../types';
 
@@ -18,15 +19,6 @@ function createMockProcessedElement(): ProcessedPointedDOMElement {
     position: {
       x: 100, y: 200, width: 300, height: 50,
     },
-    cssProperties: {
-      display: 'block',
-      position: 'relative',
-      fontSize: '16px',
-      color: 'rgb(0, 0, 0)',
-      backgroundColor: 'rgb(255, 255, 255)',
-      marginTop: '10px',
-      paddingLeft: '5px',
-    },
     cssComputed: {
       display: 'block',
       position: 'relative',
@@ -44,40 +36,44 @@ function createMockProcessedElement(): ProcessedPointedDOMElement {
 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');
+      expect(normalizeTextDetail(undefined)).toBe(TextDetailLevel.FULL);
+      expect(normalizeTextDetail('VISIBLE')).toBe(TextDetailLevel.VISIBLE);
+      expect(normalizeTextDetail('invalid', TextDetailLevel.VISIBLE)).toBe(TextDetailLevel.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);
+      expect(normalizeCssLevel('2')).toBe(CSSDetailLevel.BOX_MODEL);
+      expect(normalizeCssLevel('not-a-number', CSSDetailLevel.FULL)).toBe(CSSDetailLevel.FULL);
+      expect(normalizeCssLevel(undefined)).toBe(CSSDetailLevel.BASIC);
     });
   });
 
   describe('normalizeDetailParameters', () => {
     it('applies defaults when params are missing', () => {
       expect(normalizeDetailParameters(undefined)).toEqual({
-        textDetail: 'full',
-        cssLevel: 1,
+        textDetail: TextDetailLevel.FULL,
+        cssLevel: CSSDetailLevel.BASIC,
       });
     });
 
     it('normalizes provided params', () => {
       expect(normalizeDetailParameters({ textDetail: 'visible', cssLevel: '0' })).toEqual({
-        textDetail: 'visible',
-        cssLevel: 0,
+        textDetail: TextDetailLevel.VISIBLE,
+        cssLevel: CSSDetailLevel.NONE,
       });
     });
   });
 
-  describe('shapeElementForDetail', () => {
+  describe('serializeElement', () => {
     it('omits text and css when levels request none', () => {
       const element = createMockProcessedElement();
-      const shaped = shapeElementForDetail(element, 'none', 0);
+      const shaped = serializeElement(
+        element,
+        TextDetailLevel.NONE,
+        CSSDetailLevel.NONE,
+      );
 
       expect(shaped.innerText).toBe('');
       expect(shaped.textContent).toBeUndefined();
@@ -88,7 +84,11 @@ describe('element-detail utilities', () => {
       const element = createMockProcessedElement();
       element.innerText = 'Visible text only';
       element.textContent = 'Visible text only with hidden';
-      const shaped = shapeElementForDetail(element, 'visible', 1);
+      const shaped = serializeElement(
+        element,
+        TextDetailLevel.VISIBLE,
+        CSSDetailLevel.BASIC,
+      );
 
       expect(shaped.innerText).toBe('Visible text only');
       expect(shaped.textContent).toBeUndefined();
@@ -99,7 +99,11 @@ describe('element-detail utilities', () => {
 
     it('returns full css when level 3 requested', () => {
       const element = createMockProcessedElement();
-      const shaped = shapeElementForDetail(element, 'full', 3);
+      const shaped = serializeElement(
+        element,
+        TextDetailLevel.FULL,
+        CSSDetailLevel.FULL,
+      );
 
       expect(shaped.cssProperties).toEqual(element.cssComputed);
       expect(shaped.textContent).toBe(element.textContent);

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

@@ -10,7 +10,7 @@ import {
   isValidCSSLevel,
   isValidTextDetail,
 } from '@mcp-pointer/shared/detail';
-import { ProcessedPointedDOMElement } from '../types';
+import { ProcessedPointedDOMElement, SerializedDOMElement } from '../types';
 
 export interface DetailParameters {
   textDetail?: unknown;
@@ -37,6 +37,17 @@ function toNumber(value: unknown): number | null {
   return null;
 }
 
+const TEXT_DETAIL_ALIAS_MAP: Record<string, TextDetailLevel> = {
+  full: TextDetailLevel.FULL,
+  visible: TextDetailLevel.VISIBLE,
+  none: TextDetailLevel.NONE,
+};
+
+function fromTextDetailAlias(value: string): TextDetailLevel | null {
+  const normalized = value.trim().toLowerCase();
+  return TEXT_DETAIL_ALIAS_MAP[normalized] ?? null;
+}
+
 export function normalizeTextDetail(
   detail: unknown,
   fallback: TextDetailLevel = DEFAULT_TEXT_DETAIL,
@@ -46,9 +57,14 @@ export function normalizeTextDetail(
   }
 
   if (typeof detail === 'string') {
-    const lowered = detail.toLowerCase();
-    if (isValidTextDetail(lowered)) {
-      return lowered as TextDetailLevel;
+    const alias = fromTextDetailAlias(detail);
+    if (alias !== null) {
+      return alias;
+    }
+
+    const parsed = toNumber(detail);
+    if (parsed !== null && isValidTextDetail(parsed)) {
+      return parsed;
     }
   }
 
@@ -91,41 +107,37 @@ function resolveTextContent(
   element: ProcessedPointedDOMElement,
   detail: TextDetailLevel,
 ): string | undefined {
-  if (detail === 'none') {
+  if (detail === TextDetailLevel.NONE) {
     return undefined;
   }
 
-  if (detail === 'visible') {
+  if (detail === TextDetailLevel.VISIBLE) {
     return element.innerText;
   }
 
-  // 'full' - return textContent if available, otherwise innerText
+  // Full detail returns textContent if available, otherwise falls back to innerText
   return element.textContent ?? element.innerText;
 }
 
 function buildCssProperties(
   element: ProcessedPointedDOMElement,
   cssLevel: CSSDetailLevel,
 ): CSSProperties | undefined {
-  if (cssLevel === 0) {
+  if (cssLevel === CSSDetailLevel.NONE) {
     return undefined;
   }
 
-  if (cssLevel === 3) {
+  if (cssLevel === CSSDetailLevel.FULL) {
     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 ?? {};
+  const source = element.cssComputed ?? {};
 
   fields.forEach((property) => {
     const value = source[property];
@@ -138,23 +150,23 @@ function buildCssProperties(
     return cssProperties;
   }
 
-  if (element.cssProperties) {
-    return { ...element.cssProperties };
+  if (element.cssComputed) {
+    return { ...element.cssComputed };
   }
 
   return undefined;
 }
 
-export function shapeElementForDetail(
+export function serializeElement(
   element: ProcessedPointedDOMElement,
   detail: TextDetailLevel,
   cssLevel: CSSDetailLevel,
-): ProcessedPointedDOMElement {
+): SerializedDOMElement {
   const resolvedText = resolveTextContent(element, detail);
-  const textContent = detail === 'full' ? element.textContent : undefined;
+  const textContent = detail === TextDetailLevel.FULL ? element.textContent : undefined;
   const cssProperties = buildCssProperties(element, cssLevel);
 
-  const shaped: ProcessedPointedDOMElement = {
+  const shaped: SerializedDOMElement = {
     selector: element.selector,
     tagName: element.tagName,
     id: element.id,

packages/shared/src/detail.ts

@@ -1,8 +1,16 @@
 import { CSSDetailLevel, TextDetailLevel } from './types';
 
-export const TEXT_DETAIL_OPTIONS: readonly TextDetailLevel[] = ['full', 'visible', 'none'];
+function getEnumNumberValues<T extends Record<string, string | number>>(enumObj: T): number[] {
+  return Object.values(enumObj).filter((value): value is number => typeof value === 'number');
+}
+
+export const TEXT_DETAIL_OPTIONS: readonly TextDetailLevel[] = Object.freeze(
+  getEnumNumberValues(TextDetailLevel) as TextDetailLevel[],
+);
 
-export const CSS_DETAIL_OPTIONS: readonly CSSDetailLevel[] = [0, 1, 2, 3];
+export const CSS_DETAIL_OPTIONS: readonly CSSDetailLevel[] = Object.freeze(
+  getEnumNumberValues(CSSDetailLevel) as CSSDetailLevel[],
+);
 
 export const CSS_LEVEL_1_FIELDS: readonly string[] = [
   'display',
@@ -59,16 +67,16 @@ export const CSS_LEVEL_2_FIELDS: readonly string[] = Object.freeze([
 ]);
 
 export const CSS_LEVEL_FIELD_MAP: Record<
-Exclude<CSSDetailLevel, 0>,
+Exclude<CSSDetailLevel, CSSDetailLevel.NONE>,
 readonly string[]
 > = Object.freeze({
-  1: CSS_LEVEL_1_FIELDS,
-  2: CSS_LEVEL_2_FIELDS,
-  3: [],
+  [CSSDetailLevel.BASIC]: CSS_LEVEL_1_FIELDS,
+  [CSSDetailLevel.BOX_MODEL]: CSS_LEVEL_2_FIELDS,
+  [CSSDetailLevel.FULL]: [],
 });
 
 export function isValidTextDetail(detail: unknown): detail is TextDetailLevel {
-  return typeof detail === 'string' && (TEXT_DETAIL_OPTIONS as readonly string[]).includes(detail);
+  return typeof detail === 'number' && (TEXT_DETAIL_OPTIONS as readonly number[]).includes(detail);
 }
 
 export function isValidCSSLevel(level: unknown): level is CSSDetailLevel {

packages/shared/src/types.ts

@@ -1,10 +1,19 @@
-export type TextDetailLevel = 'full' | 'visible' | 'none';
+export enum TextDetailLevel {
+  NONE = 0,
+  VISIBLE = 1,
+  FULL = 2,
+}
 
-export type CSSDetailLevel = 0 | 1 | 2 | 3;
+export enum CSSDetailLevel {
+  NONE = 0,
+  BASIC = 1,
+  BOX_MODEL = 2,
+  FULL = 3,
+}
 
-export const DEFAULT_TEXT_DETAIL: TextDetailLevel = 'full';
+export const DEFAULT_TEXT_DETAIL: TextDetailLevel = TextDetailLevel.FULL;
 
-export const DEFAULT_CSS_LEVEL: CSSDetailLevel = 1;
+export const DEFAULT_CSS_LEVEL: CSSDetailLevel = CSSDetailLevel.BASIC;
 
 export interface TextSnapshots {
   visible: string;