refactor: Refine session lifecycle handling and simplify logic

- Review code changes and consolidate docs

Author: Winify

CLAUDE.md

@@ -24,33 +24,56 @@ src/
 │   ├── local-browser.provider.ts  # Chrome/Firefox/Edge/Safari capability building
 │   └── local-appium.provider.ts   # iOS/Android via appium.config.ts
 ├── tools/
-│   ├── browser.tool.ts          # start_browser, close_session, readTabs(), switch_tab
-│   ├── app-session.tool.ts      # start_app_session (iOS/Android via Appium)
+│   ├── session.tool.ts          # start_session (browser+mobile), close_session
+│   ├── tabs.tool.ts             # switch_tab
+│   ├── launch-chrome.tool.ts    # launch_chrome (remote debugging)
 │   ├── navigate.tool.ts         # navigateAction() + navigateTool
 │   ├── click.tool.ts            # clickAction() + clickTool
 │   ├── set-value.tool.ts        # setValueAction() + setValueTool
 │   ├── scroll.tool.ts           # scrollAction() + scrollTool
 │   ├── gestures.tool.ts         # tapAction(), swipeAction(), dragAndDropAction()
+│   ├── context.tool.ts          # switch_context (native/webview)
+│   ├── device.tool.ts           # rotate_device, hide_keyboard
+│   ├── emulate-device.tool.ts   # emulate_device (viewport/UA)
+│   ├── cookies.tool.ts          # set_cookie, delete_cookies
+│   ├── execute-script.tool.ts   # execute_script
 │   ├── execute-sequence.tool.ts # Batch action sequencing with stability + state delta
 │   └── ...                      # Other tools follow same pattern
+├── resources/
+│   ├── index.ts                 # ResourceDefinition exports
+│   ├── sessions.resource.ts     # wdio://sessions, wdio://session/*/steps, wdio://session/*/code
+│   ├── elements.resource.ts     # wdio://session/current/elements
+│   ├── accessibility.resource.ts# wdio://session/current/accessibility
+│   ├── screenshot.resource.ts   # wdio://session/current/screenshot
+│   ├── cookies.resource.ts      # wdio://session/current/cookies
+│   ├── tabs.resource.ts         # wdio://session/current/tabs
+│   ├── contexts.resource.ts     # wdio://session/current/contexts
+│   ├── app-state.resource.ts    # wdio://session/current/app-state
+│   └── geolocation.resource.ts  # wdio://session/current/geolocation
 ├── recording/
 │   ├── step-recorder.ts         # withRecording HOF, appendStep, session history access
-│   ├── code-generator.ts        # SessionHistory → WebdriverIO JS code
-│   └── resources.ts             # MCP resource builders (sessions index, step log)
+│   └── code-generator.ts        # SessionHistory → WebdriverIO JS code
 ├── scripts/
-│   └── get-interactable-browser-elements.ts  # Browser-context script
+│   ├── get-interactable-browser-elements.ts  # Browser-context element detection
+│   ├── get-browser-accessibility-tree.ts     # Browser-context accessibility tree
+│   └── get-visible-mobile-elements.ts        # Mobile visible element detection
 ├── locators/
 │   ├── element-filter.ts        # Platform-specific element classification
-│   ├── generate-all-locators.ts # Multi-strategy selector generation
-│   └── source-parsing.ts        # XML page source parsing for mobile
+│   ├── locator-generation.ts    # Multi-strategy selector generation
+│   ├── xml-parsing.ts           # XML page source parsing for mobile
+│   ├── constants.ts             # Shared locator constants
+│   ├── types.ts                 # Locator type definitions
+│   └── index.ts                 # Public exports
 ├── config/
 │   └── appium.config.ts         # iOS/Android capability builders (used by local-appium.provider)
 ├── utils/
 │   ├── parse-variables.ts       # URI template variable parsing (parseBool, parseNumber, etc.)
 │   ├── stability-detector.ts    # Page stability polling (signature-based, 200ms/500ms/5s)
-│   └── state-diff.ts            # Element before/after diff (appeared, disappeared, changed)
+│   ├── state-diff.ts            # Element before/after diff (appeared, disappeared, changed)
+│   └── zod-helpers.ts           # coerceBoolean and other Zod utilities
 └── types/
     ├── tool.ts                  # ToolDefinition interface
+    ├── resource.ts              # ResourceDefinition interface
     └── recording.ts             # RecordedStep, SessionHistory interfaces
 ```
 
@@ -95,17 +118,32 @@ export const myTool: ToolCallback = async ({ param }: { param: string }) => {
   }
 };
 
-// 3. Register in server.ts
-server.tool(myToolDefinition.name, myToolDefinition.description, myToolDefinition.inputSchema, myTool);
+// 3. Register in server.ts via the registerTool helper
+registerTool(myToolDefinition, myTool);
 ```
 
 ### Recording
 
-All tools are wrapped with `withRecording()` in `server.ts`. Steps accumulate in `state.sessionHistory` (keyed by sessionId).
-MCP resources expose history without tool calls:
-- `wdio://sessions` — index of all sessions (fixed URI, discoverable via ListResources)
-- `wdio://session/current/steps` — current session step log + generated JS (fixed URI)
-- `wdio://session/{sessionId}/steps` — any session by ID (URI template, NOT listed by ListResources — see `docs/architecture/mcp-resources-notes.md`)
+Selected tools are wrapped with `withRecording()` in `server.ts`. Steps accumulate in `state.sessionHistory` (keyed by sessionId).
+
+MCP resources expose live session data — all at fixed URIs discoverable via ListResources:
+
+**Session history:**
+- `wdio://sessions` — index of all sessions
+- `wdio://session/current/steps` — current session step log
+- `wdio://session/current/code` — generated WebdriverIO JS for current session
+- `wdio://session/{sessionId}/steps` — step log for any session (URI template)
+- `wdio://session/{sessionId}/code` — generated JS for any session (URI template)
+
+**Live page state (current session):**
+- `wdio://session/current/elements` — interactable elements
+- `wdio://session/current/accessibility` — accessibility tree
+- `wdio://session/current/screenshot` — screenshot (base64)
+- `wdio://session/current/cookies` — browser cookies
+- `wdio://session/current/tabs` — open browser tabs
+- `wdio://session/current/contexts` — native/webview contexts (mobile)
+- `wdio://session/current/app-state` — mobile app state
+- `wdio://session/current/geolocation` — device geolocation
 
 ### Build
 
@@ -120,29 +158,33 @@ MCP resources expose history without tool calls:
 | `src/server.ts`                                    | MCP server init, tool + resource registration |
 | `src/session/state.ts`                             | Session state maps, `getBrowser()`, `getState()` |
 | `src/session/lifecycle.ts`                         | `registerSession()`, `closeSession()`, session transitions |
-| `src/tools/browser.tool.ts`                        | `start_browser`, `close_session`, `switch_tab`, `readTabs()` |
-| `src/tools/app-session.tool.ts`                    | Appium session creation                       |
+| `src/tools/session.tool.ts`                        | `start_session` (browser + mobile), `close_session` |
+| `src/tools/tabs.tool.ts`                           | `switch_tab`                                  |
 | `src/tools/execute-sequence.tool.ts`               | Batch action sequencing with stability + delta |
+| `src/resources/`                                   | All MCP resource definitions (10 files)       |
 | `src/providers/local-browser.provider.ts`          | Chrome/Firefox/Edge/Safari capability building |
 | `src/providers/local-appium.provider.ts`           | iOS/Android capabilities via appium.config.ts |
 | `src/scripts/get-interactable-browser-elements.ts` | Browser-context element detection             |
 | `src/locators/`                                    | Mobile element detection + locator generation |
-| `src/recording/step-recorder.ts`                   | `withRecording(toolName, cb)` HOF — wraps every tool for step logging |
+| `src/recording/step-recorder.ts`                   | `withRecording(toolName, cb)` HOF — wraps tools for step logging |
 | `src/recording/code-generator.ts`                  | Generates runnable WebdriverIO JS from `SessionHistory` |
-| `src/recording/resources.ts`                       | Builds text for `wdio://sessions` and `wdio://session/*/steps` resources |
 | `src/utils/stability-detector.ts`                  | Page stability detection (signature polling)  |
 | `src/utils/state-diff.ts`                          | Element state diff (appeared/disappeared/changed) |
+| `src/utils/zod-helpers.ts`                         | `coerceBoolean` for client interop            |
 | `tsup.config.ts`                                   | Build configuration                           |
 
 ## Gotchas
 
 ### Console Output
 
-All console methods redirect to stderr. Chrome writes to stdout which corrupts MCP stdio protocol.
+All console methods redirect to stderr via `console.error`. Chrome writes to stdout which corrupts MCP stdio protocol.
 
 ```typescript
 // In server.ts - do not remove
-console.log = (...args) => process.stderr.write(util.format(...args) + '\n');
+console.log = (...args) => console.error('[LOG]', ...args);
+console.info = (...args) => console.error('[INFO]', ...args);
+console.warn = (...args) => console.error('[WARN]', ...args);
+console.debug = (...args) => console.error('[DEBUG]', ...args);
 ```
 
 ### Browser Scripts Must Be Self-Contained
@@ -169,11 +211,12 @@ catch (e) {
 
 1. Create `src/tools/my-tool.tool.ts`
 2. Export `myToolDefinition` (Zod schema) and `myTool` (ToolCallback)
-3. Import and register in `src/server.ts`:
+3. Import and register in `src/server.ts` using the `registerTool` helper:
    ```typescript
    import { myToolDefinition, myTool } from './tools/my-tool.tool';
-   server.tool(myToolDefinition.name, myToolDefinition.description, myToolDefinition.inputSchema, myTool);
+   registerTool(myToolDefinition, myTool);
    ```
+   To wrap with recording: `registerTool(myToolDefinition, withRecording('my_tool', myTool));`
 
 ## Selector Syntax Reference
 

src/tools/context.tool.ts

@@ -11,7 +11,7 @@ export const switchContextToolDefinition: ToolDefinition = {
     context: z
       .string()
       .describe(
-        'Context name to switch to (e.g., "NATIVE_APP", "WEBVIEW_com.example.app", or use index from get_contexts)',
+        'Context name to switch to (e.g., "NATIVE_APP", "WEBVIEW_com.example.app", or use index from wdio://session/current/contexts resource)',
       ),
   },
 };

src/tools/execute-sequence.tool.ts

@@ -119,88 +119,92 @@ export const executeSequenceTool: ToolCallback = async ({
   actions: z.infer<typeof actionSchema>[];
   waitForStability?: boolean;
 }) => {
-  const browser = getBrowser();
-  const isBrowser = !browser.isAndroid && !browser.isIOS;
-
-  // Capture initial URL/title for diff
-  const { url: beforeUrl, title: beforeTitle } = isBrowser
-    ? await browser.execute(() => ({ url: window.location.href, title: document.title })) as {
-      url: string;
-      title: string
+  try {
+    const browser = getBrowser();
+    const isBrowser = !browser.isAndroid && !browser.isIOS;
+
+    // Capture initial URL/title for diff
+    const { url: beforeUrl, title: beforeTitle } = isBrowser
+      ? await browser.execute(() => ({ url: window.location.href, title: document.title })) as {
+        url: string;
+        title: string
+      }
+      : { url: '', title: '' };
+
+    // Capture initial elements for diff (browser only)
+    const initialBrowserElements = isBrowser ? await getInteractableBrowserElements(browser, {}) : [];
+    const initialElements = initialBrowserElements.map((el) => ({ selector: el.selector, text: el.name }));
+
+    const results: { action: string; durationMs: number }[] = [];
+
+    for (let i = 0; i < actions.length; i++) {
+      const action = actions[i];
+      const start = Date.now();
+      const result = await dispatchAction(action);
+      const durationMs = Date.now() - start;
+      const isError = (result as any).isError === true;
+
+      // Record each sub-action as a step
+      appendStep(
+        action.action,
+        action as Record<string, unknown>,
+        isError ? 'error' : 'ok',
+        durationMs,
+        isError ? (result.content.find((c: any) => c.type === 'text') as any)?.text : undefined,
+      );
+
+      if (isError) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              completed: i,
+              total: actions.length,
+              failed: {
+                index: i,
+                action: action.action,
+                error: (result.content.find((c: any) => c.type === 'text') as any)?.text,
+              },
+              results,
+            }),
+          }],
+        };
+      }
+
+      results.push({ action: action.action, durationMs });
+
+      // Wait for stability after each action (except the last, we do it before diff)
+      if (shouldWait && i < actions.length - 1 && isBrowser) {
+        await waitForStability(browser);
+      }
     }
-    : { url: '', title: '' };
-
-  // Capture initial elements for diff (browser only)
-  const initialBrowserElements = isBrowser ? await getInteractableBrowserElements(browser, {}) : [];
-  const initialElements = initialBrowserElements.map((el) => ({ selector: el.selector, text: el.name }));
-
-  const results: { action: string; durationMs: number }[] = [];
-
-  for (let i = 0; i < actions.length; i++) {
-    const action = actions[i];
-    const start = Date.now();
-    const result = await dispatchAction(action);
-    const durationMs = Date.now() - start;
-    const isError = (result as any).isError === true;
-
-    // Record each sub-action as a step
-    appendStep(
-      action.action,
-      action as Record<string, unknown>,
-      isError ? 'error' : 'ok',
-      durationMs,
-      isError ? (result.content.find((c: any) => c.type === 'text') as any)?.text : undefined,
-    );
-
-    if (isError) {
-      return {
-        content: [{
-          type: 'text' as const,
-          text: JSON.stringify({
-            completed: i,
-            total: actions.length,
-            failed: {
-              index: i,
-              action: action.action,
-              error: (result.content.find((c: any) => c.type === 'text') as any)?.text,
-            },
-            results,
-          }),
-        }],
-      };
-    }
-
-    results.push({ action: action.action, durationMs });
 
-    // Wait for stability after each action (except the last, we do it before diff)
-    if (shouldWait && i < actions.length - 1 && isBrowser) {
+    // Final stability wait before capturing end state
+    if (shouldWait && isBrowser) {
       await waitForStability(browser);
     }
-  }
 
-  // Final stability wait before capturing end state
-  if (shouldWait && isBrowser) {
-    await waitForStability(browser);
-  }
+    // Capture final elements for state delta (browser only)
+    const finalBrowserElements = isBrowser ? await getInteractableBrowserElements(browser, {}) : [];
+    const finalElements = finalBrowserElements.map((el) => ({ selector: el.selector, text: el.name }));
+
+    const delta = isBrowser
+      ? await captureStateDelta(browser, initialElements, finalElements, beforeUrl, beforeTitle)
+      : null;
+
+    const response: Record<string, unknown> = {
+      completed: actions.length,
+      total: actions.length,
+      results,
+    };
+    if (delta) {
+      response.delta = delta;
+    }
 
-  // Capture final elements for state delta (browser only)
-  const finalBrowserElements = isBrowser ? await getInteractableBrowserElements(browser, {}) : [];
-  const finalElements = finalBrowserElements.map((el) => ({ selector: el.selector, text: el.name }));
-
-  const delta = isBrowser
-    ? await captureStateDelta(browser, initialElements, finalElements, beforeUrl, beforeTitle)
-    : null;
-
-  const response: Record<string, unknown> = {
-    completed: actions.length,
-    total: actions.length,
-    results,
-  };
-  if (delta) {
-    response.delta = delta;
+    return {
+      content: [{ type: 'text' as const, text: JSON.stringify(response) }],
+    };
+  } catch (e) {
+    return { isError: true, content: [{ type: 'text', text: `Error executing sequence: ${e}` }] };
   }
-
-  return {
-    content: [{ type: 'text' as const, text: JSON.stringify(response) }],
-  };
 };