Refactor SharedStateService with dual format support and comprehensive tests

- Added dual format support for legacy and new raw DOM data - Created ElementProcessor service for server-side DOM processing - Added comprehensive test suite with factory pattern - Added DOM_ELEMENT_POINTED message type support - Maintains full backward compatibility Server ready for browser extension updates.

Author: elieteyssedou

.claude/plan.md

@@ -0,0 +1,93 @@
+# Refactoring Plan: Raw/Processed Data Architecture
+
+## Phase 1: Type System Updates ✅ COMPLETED
+
+1. Update PointerMessageType enum 
+- [x] Rename ELEMENT_SELECTED to LEGACY_ELEMENT_SELECTED (keep value 'element-selected')
+- [x] Add new DOM_ELEMENT_POINTED = 'dom-element-pointed' 
+- [x] Remove unused: ELEMENT_CLEARED, CONNECTION_TEST, SERVER_STATUS
+2. Create new data types
+- [x] RawPointedDOMElement: Minimal browser data (outerHTML, boundingClientRect, url, timestamp)
+- [x] ProcessedPointedDOMElement: Server-processed data with extracted metadata
+- [x] StoredPointedData: Container with integer stateVersion, raw, processed, and metadata 
+
+## Phase 2: Browser Extension Updates
+
+1. Keep existing collection (for backward compatibility)
+- [x] Continue sending LEGACY_ELEMENT_SELECTED with full TargetedElement (automatic)
+2. Prepare new collection (deploy after server) 
+- [ ] Create minimal RawPointedDOMElement collector 
+- [ ] Send via DOM_ELEMENT_POINTED message type 
+- [ ] Include: outerHTML, boundingClientRect, url, timestamp
+- [ ] Optional: computedStyles, reactFiber (based on config)
+
+## Phase 3: Server-Side Processing ✅ COMPLETED
+
+1. Create ElementProcessor service
+- [x] Parse HTML using jsdom
+- [x] Extract: tagName, id, classes, attributes, innerText
+- [x] Generate selectors
+- [x] Process optional data (CSS, React info) 
+- [x] Include fail-safe defaults and warning collection 
+2. Update message handlers
+- [x] Support both LEGACY_ELEMENT_SELECTED and DOM_ELEMENT_POINTED
+- [x] Legacy: Store as stateVersion 1, use data as both raw and processed
+- [x] New: Store as stateVersion 2, process server-side
+- [x] Clean switch-based architecture with separate builder functions
+3. Update SharedStateService
+- [x] Store StoredPointedData format instead of raw element 
+- [x] Include metadata (timestamps, message type) 
+- [x] Maintain backward compatibility for reading old format
+
+## Phase 4: MCP Service Updates ✅ COMPLETED
+
+1. Update get-pointed-element tool
+- [x] Return processedPointedDOMElement to agents
+- [x] Include stateVersion in response metadata 
+- [x] Handle legacy format transparently
+
+## Phase 5: Utilities & Safety ✅ COMPLETED
+
+1. Implement safe extraction utilities
+- [x] Create lightweight safeGet function (using lodash.get) 
+- [x] Build DOM extractor with error handling
+- [x] Collect warnings without throwing errors
+2. Add lodash-es for tree-shakeable utilities 
+- [x] Use import { get } from 'lodash-es' for safe property access
+- [x] Only import needed functions
+
+## Deployment Strategy
+
+1. ✅ Day 1: Deploy server with dual format support
+2. Day 2-3: Update Chrome extension to use new format 
+3. Week 2: Monitor and fix any edge cases 
+4. Month 2: Consider deprecating legacy format
+
+## Key Principles
+
+- [x] Fail-safe: Always return some data, even if incomplete
+- [x] Backward compatible: No breaking changes during transition
+- [x] Truly raw: Send actual DOM serialization (outerHTML)
+- [x] Server processing: Process and extract metadata server-side 
+- [x] Integer versioning: Simple stateVersion (1, 2, 3...)
+- [x] Warning system: Track issues without failing
+
+## Benefits Achieved
+
+- [x] Smaller payload from browser (1-5KB vs 10-50KB when Phase 2 is deployed) 
+- [x] Centralized processing logic
+- [x] Future-proof versioning system
+- [x] Better separation of concerns 
+- [x] Maintains service during migration
+- [x] Clean architecture with separated builders, processors, and storage
+
+## Implementation Status
+
+**✅ PHASE 1-5 COMPLETE** - Server is ready for dual format support!
+
+- All tests pass ✅
+- Build successful ✅ 
+- Backward compatibility verified ✅
+- New processed data architecture implemented ✅
+
+**Next Step:** Update Chrome extension to send new `RawPointedDOMElement` format

packages/server/package.json

@@ -25,11 +25,13 @@
  "dependencies": {
  "@modelcontextprotocol/sdk": "^0.5.0",
  "commander": "^11.1.0",
+ "jsdom": "^27.0.0",
  "ws": "^8.16.0"
  },
  "devDependencies": {
  "@mcp-pointer/shared": "workspace:*",
  "@types/jest": "^30.0.0",
+ "@types/jsdom": "^21.1.7",
  "@types/ws": "^8.5.10",
  "esbuild": "catalog:",
  "jest": "^30.1.3",

packages/server/src/__tests__/factories/shared-state-factory.ts

@@ -0,0 +1,93 @@
+import { TargetedElement, RawPointedDOMElement, PointerMessageType } from '@mcp-pointer/shared/types';
+import {
+ SharedState, StateDataV1, StateDataV2, ProcessedPointedDOMElement,
+} from '../../types';
+
+export const createProcessedElement = (
+ overrides: Partial<ProcessedPointedDOMElement> = {},
+): ProcessedPointedDOMElement => ({
+ tagName: 'div',
+ classes: [],
+ attributes: {},
+ innerText: 'test content',
+ selector: 'div',
+ position: {
+ x: 10, y: 20, width: 100, height: 50,
+ },
+ url: 'https://example.com',
+ timestamp: '2023-01-01T00:00:00.000Z',
+ ...overrides,
+});
+
+export const createRawElement = (
+ overrides: Partial<RawPointedDOMElement> = {},
+): RawPointedDOMElement => ({
+ outerHTML: '<div>test content</div>',
+ url: 'https://example.com',
+ timestamp: 1672531200000,
+ boundingClientRect: {
+ x: 10,
+ y: 20,
+ width: 100,
+ height: 50,
+ top: 20,
+ right: 110,
+ bottom: 70,
+ left: 10,
+ toJSON() { return this; },
+ },
+ ...overrides,
+});
+
+export const createLegacyElement = (
+ overrides: Partial<TargetedElement> = {},
+): TargetedElement => ({
+ selector: 'div',
+ tagName: 'div',
+ classes: [],
+ innerText: 'test content',
+ attributes: {},
+ position: {
+ x: 10, y: 20, width: 100, height: 50,
+ },
+ cssProperties: {
+ display: 'block',
+ position: 'relative',
+ fontSize: '16px',
+ color: '#000000',
+ backgroundColor: '#ffffff',
+ },
+ timestamp: 1672531200000,
+ url: 'https://example.com',
+ ...overrides,
+});
+
+export const createStateV2 = (
+ rawOverrides: Partial<RawPointedDOMElement> = {},
+ processedOverrides: Partial<ProcessedPointedDOMElement> = {},
+): SharedState => ({
+ stateVersion: 2,
+ data: {
+ rawPointedDOMElement: createRawElement(rawOverrides),
+ processedPointedDOMElement: createProcessedElement(processedOverrides),
+ metadata: {
+ receivedAt: '2023-01-01T00:00:00.000Z',
+ messageType: PointerMessageType.DOM_ELEMENT_POINTED,
+ },
+ } as StateDataV2,
+});
+
+export const createStateV1 = (
+ legacyOverrides: Partial<TargetedElement> = {},
+ processedOverrides: Partial<ProcessedPointedDOMElement> = {},
+): SharedState => ({
+ stateVersion: 1,
+ data: {
+ rawPointedDOMElement: createLegacyElement(legacyOverrides),
+ processedPointedDOMElement: createProcessedElement(processedOverrides),
+ metadata: {
+ receivedAt: '2023-01-01T00:00:00.000Z',
+ messageType: PointerMessageType.LEGACY_ELEMENT_SELECTED,
+ },
+ } as StateDataV1,
+});

packages/server/src/__tests__/services/shared-state-service.test.ts

@@ -1,99 +1,97 @@
 import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
 import SharedStateService from '../../services/shared-state-service';
-import {
- setupTestDir, cleanupTestFiles, createMockElement, TEST_SHARED_STATE_PATH,
-} from '../test-helpers';
+import { createStateV1, createStateV2, createLegacyElement } from '../factories/shared-state-factory';
+
+jest.mock('../../logger', () => ({
+ debug: jest.fn(),
+ error: jest.fn(),
+}));
 
 describe('SharedStateService', () => {
  let service: SharedStateService;
+ let testPath: string;
 
- beforeAll(async () => {
- await setupTestDir();
+ beforeEach(async () => {
+ testPath = path.join(os.tmpdir(), `test-${Date.now()}.json`);
+ (SharedStateService as any).SHARED_STATE_PATH = testPath;
+ service = new SharedStateService();
+ });
 
- // Monkey-patch the constant for testing
- const SharedStateServiceModule = await import('../../services/shared-state-service');
- const SharedStateServiceClass = SharedStateServiceModule.default;
+ afterEach(async () => {
+ try {
+ await fs.unlink(testPath);
+ } catch {
+ // ignore
+ }
+ });
 
- // Override the static constant
- (SharedStateServiceClass as any).SHARED_STATE_PATH = TEST_SHARED_STATE_PATH;
+ describe('saveState', () => {
+ it('writes state to file', async () => {
+ const state = createStateV2();
 
- service = new SharedStateServiceClass();
- });
+ await service.saveState(state);
 
- afterAll(async () => {
- await cleanupTestFiles();
- });
+ const content = await fs.readFile(testPath, 'utf8');
+ const parsed = JSON.parse(content);
+ expect(parsed.stateVersion).toBe(state.stateVersion);
+ expect(parsed.data.processedPointedDOMElement).toEqual(state.data.processedPointedDOMElement);
+ });
 
- it('should save and load current element', async () => {
- const mockElement = createMockElement();
-
- await service.saveCurrentElement(mockElement);
- const loadedElement = await service.getCurrentElement();
-
- expect(loadedElement).toBeTruthy();
- expect(loadedElement!.selector).toBe(mockElement.selector);
- expect(loadedElement!.tagName).toBe(mockElement.tagName);
- expect(loadedElement!.id).toBe(mockElement.id);
- expect(loadedElement!.classes).toEqual(mockElement.classes);
- expect(loadedElement!.innerText).toBe(mockElement.innerText);
- expect(loadedElement!.attributes).toEqual(mockElement.attributes);
- expect(loadedElement!.position).toEqual(mockElement.position);
- expect(loadedElement!.cssProperties).toEqual(mockElement.cssProperties);
- expect(loadedElement!.url).toBe(mockElement.url);
- expect(loadedElement!.tabId).toBe(mockElement.tabId);
- });
+ it('overwrites corrupted file', async () => {
+ await fs.writeFile(testPath, 'invalid json');
+ const state = createStateV1();
 
- it('should handle null element', async () => {
- await service.saveCurrentElement(null);
- const loadedElement = await service.getCurrentElement();
+ await service.saveState(state);
 
- expect(loadedElement).toBeNull();
+ const content = await fs.readFile(testPath, 'utf8');
+ const parsed = JSON.parse(content);
+ expect(parsed.stateVersion).toBe(state.stateVersion);
+ expect(parsed.data.processedPointedDOMElement).toEqual(state.data.processedPointedDOMElement);
+ });
  });
 
- it('should return null for missing file', async () => {
- // Delete the file if it exists
- try {
- await fs.unlink(TEST_SHARED_STATE_PATH);
- } catch {
- // File doesn't exist, which is fine
- }
+ describe('getPointedElement', () => {
+ it('returns processed element from v2 state', async () => {
+ const state = createStateV2();
+ await fs.writeFile(testPath, JSON.stringify(state));
 
- const loadedElement = await service.getCurrentElement();
- expect(loadedElement).toBeNull();
- });
+ const result = await service.getPointedElement();
 
- it('should handle corrupted file gracefully', async () => {
- // Write invalid JSON to the file
- await fs.writeFile(TEST_SHARED_STATE_PATH, 'invalid json content');
+ expect(result).toEqual(state.data.processedPointedDOMElement);
+ });
 
- const loadedElement = await service.getCurrentElement();
- expect(loadedElement).toBeNull();
- });
+ it('returns processed element from v1 state', async () => {
+  const state = createStateV1();
+  await fs.writeFile(testPath, JSON.stringify(state));
 
- it('should save element over corrupted file', async () => {
- // Write invalid JSON to the file
- await fs.writeFile(TEST_SHARED_STATE_PATH, 'invalid json content');
+ const result = await service.getPointedElement();
 
- const mockElement = createMockElement();
- await service.saveCurrentElement(mockElement);
+  expect(result).toEqual(state.data.processedPointedDOMElement);
+ });
 
- const loadedElement = await service.getCurrentElement();
- expect(loadedElement).toBeTruthy();
- expect(loadedElement!.selector).toBe(mockElement.selector);
- });
+ it('returns legacy element as-is', async () => {
+ const legacyElement = createLegacyElement();
+ await fs.writeFile(testPath, JSON.stringify(legacyElement));
+
+ const result = await service.getPointedElement();
+
+ expect(result).toEqual(legacyElement);
+ });
+
+ it('returns null for invalid json', async () => {
+ await fs.writeFile(testPath, 'invalid json');
 
- it('should overwrite previous element', async () => {
- const firstElement = createMockElement();
- firstElement.selector = 'div.first-element';
+ const result = await service.getPointedElement();
 
- const secondElement = createMockElement();
- secondElement.selector = 'div.second-element';
+  expect(result).toBeNull();
+ });
 
- await service.saveCurrentElement(firstElement);
- await service.saveCurrentElement(secondElement);
+ it('returns null when file does not exist', async () => {
+  const result = await service.getPointedElement();
 
- const loadedElement = await service.getCurrentElement();
- expect(loadedElement).toBeTruthy();
- expect(loadedElement!.selector).toBe('div.second-element');
+ expect(result).toBeNull();
+ });
  });
 });