mobile-ai-agents 1.0.37 → 1.0.39

package/cli/lib/network-capture.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createRequire } = require('node:module');
+
+function origin(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+    throw new Error('Use an HTTP(S) URL without embedded credentials.');
+  }
+  return url.origin;
+}
+
+// Values are deliberately omitted, including harmless-looking IDs and query strings.
+function safeUrl(value) {
+  const url = new URL(value);
+  const pathname = url.pathname.split('/').map(part => /^[a-z][a-z_-]{0,40}$/i.test(part) ? part : part ? '[REDACTED]' : '').join('/');
+  return url.origin + pathname + (url.search ? '?' + [...url.searchParams.keys()].map(key => `${encodeURIComponent(key)}=[REDACTED]`).join('&') : '');
+}
+
+function shape(value, depth = 0) {
+  if (depth > 12) return { type: 'unknown', reason: 'depth-limit' };
+  if (value === null) return { type: 'null' };
+  if (Array.isArray(value)) {
+    const variants = [...new Set(value.slice(0, 20).map(item => JSON.stringify(shape(item, depth + 1))))].map(item => JSON.parse(item));
+    return { type: 'array', observedItems: variants, sampled: value.length > 20 };
+  }
+  if (typeof value === 'object') return { type: 'object', properties: Object.fromEntries(Object.entries(value).map(([key, item]) => [key, shape(item, depth + 1)])) };
+  return { type: typeof value };
+}
+
+function bodyShape(text, contentType = '') {
+  if (!text) return { state: 'empty' };
+  if (Buffer.byteLength(text) > 65536) return { state: 'omitted', reason: 'body-size-limit' };
+  if (/json/i.test(contentType)) {
+    try { return { state: 'observed', schema: shape(JSON.parse(text)) }; }
+    catch { return { state: 'unavailable', reason: 'invalid-json' }; }
+  }
+  if (/application\/x-www-form-urlencoded/i.test(contentType)) {
+    return { state: 'observed', schema: { type: 'object', properties: Object.fromEntries([...new URLSearchParams(text).keys()].map(key => [key, { type: 'string' }])) } };
+  }
+  return { state: 'omitted', reason: 'non-json-body' };
+}
+
+function safeHeaders(headers) {
+  return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, ['content-type', 'accept'].includes(key.toLowerCase()) ? value.split(';')[0] : '[REDACTED]']));
+}
+
+function validateFlow(flow) {
+  if (!Array.isArray(flow) || flow.length > 50) throw new Error('Flow must be an array with at most 50 steps.');
+  for (const step of flow) {
+    if (!step || !['click', 'fill'].includes(step.action) || typeof step.selector !== 'string' || !step.selector || step.selector.length > 500) throw new Error('Each step needs action click|fill and a selector.');
+    if (step.action === 'fill' && typeof step.value !== 'string') throw new Error('Fill steps need a string value; use test data only.');
+    if (step.waitMs !== undefined && (!Number.isInteger(step.waitMs) || step.waitMs < 0 || step.waitMs > 10000)) throw new Error('waitMs must be an integer from 0 to 10000.');
+  }
+}
+
+function loadPlaywright() {
+  try { return require('playwright'); }
+  catch {
+    try { return createRequire(path.join(process.cwd(), 'package.json'))('playwright'); }
+    catch { throw new Error('Optional browser tooling missing. Install playwright in your project, then run: npx playwright install chromium'); }
+  }
+}
+
+async function capture({ url, flow = [], allowedOrigins = [], allowWrites = false, output, headless = true, channel, playwright }) {
+  const firstOrigin = origin(url);
+  const allowed = new Set([firstOrigin, ...allowedOrigins.map(origin)]);
+  validateFlow(flow);
+  if (!output) throw new Error('Choose an output directory.');
+  // Every run gets a fresh directory: never overwrite an existing report or follow it as a symlink.
+  fs.mkdirSync(output, { recursive: false });
+  const report = {
+    schemaVersion: 1, startedAt: new Date().toISOString(), source: safeUrl(url),
+    viewport: { width: 390, height: 844 }, status: 'capturing',
+    privacy: 'Body values omitted; header values and query values redacted. Review field names and route segments before sharing.',
+    limitations: [
+      'Touchpoint attribution is temporal, not proof of causality; delayed work may belong to a later window.',
+      'Fresh isolated browser; no existing login session imported. Service workers blocked and routing disables HTTP cache.',
+      'No screenshots, DOM text, raw HAR, SSE messages or multipart values saved. WebSocket connections are blocked.',
+      'Observed shapes are samples, not complete API contracts. No mobile implementation or mobile parity verified.',
+      'One page supported; popups blocked. JSON bodies capped at 64 KiB after transfer; request count capped at 500.',
+      'Same-origin analytics are not automatically classified as product APIs. UI state is metadata only, not business outcome proof.',
+    ], touchpoints: [], requests: [],
+  };
+  let browser, context, current, stopped = false;
+  const records = new Map();
+  const pending = new Set();
+  const track = promise => { pending.add(promise); promise.finally(() => pending.delete(promise)); };
+  const flush = async () => { await Promise.allSettled([...pending]); };
+  const save = () => {
+    fs.writeFileSync(path.join(output, 'capture.json'), JSON.stringify(report, null, 2));
+    const lines = ['# Website API capture', '', `Status: ${report.status}`, '', 'Body values are omitted. No mobile parity has been verified.', '', '## Touchpoints', ''];
+    for (const point of report.touchpoints) {
+      lines.push(`### ${point.id}: ${point.action}`, '', `Result: ${point.status}. Requests: ${point.requestIds.join(', ') || 'none observed in this window'}.`, '');
+      for (const id of point.requestIds) {
+        const item = report.requests.find(r => r.id === id);
+        lines.push(`- ${id}: ${item.method} ${item.url.replace(/[\r\n`<>]/g, '')} — ${item.status || item.outcome}`);
+      }
+      lines.push('');
+    }
+    lines.push('## Limitations', '', ...report.limitations.map(item => `- ${item}`));
+    fs.writeFileSync(path.join(output, 'report.md'), lines.join('\n') + '\n');
+  };
+  try {
+    const pw = playwright || loadPlaywright();
+    report.tool = { name: 'playwright', node: process.version };
+    browser = await pw.chromium.launch({ headless, ...(channel ? { channel } : {}) });
+    report.tool.browser = browser.version();
+    context = await browser.newContext({ viewport: report.viewport, serviceWorkers: 'block', acceptDownloads: false });
+    if (typeof context.routeWebSocket !== 'function') throw new Error('Install a current Playwright version with WebSocket routing support.');
+    await context.routeWebSocket('**/*', socket => socket.close());
+    context.setDefaultTimeout(10000);
+    const page = await context.newPage();
+    context.on('page', popup => { if (popup !== page) popup.close().catch(() => {}); });
+    context.on('request', request => {
+      if (stopped || report.requests.length >= 500) return;
+      const headers = request.headers();
+      const record = {
+        id: `R${report.requests.length + 1}`, touchpoint: current?.id || null,
+        at: new Date().toISOString(), method: request.method(), url: safeUrl(request.url()),
+        resourceType: request.resourceType(), requestHeaders: safeHeaders(headers),
+        auth: headers.authorization ? 'authorization-header' : headers.cookie ? 'cookie' : 'not-observed',
+        requestBody: bodyShape(request.postData(), headers['content-type']), outcome: 'pending',
+        redirectedFrom: records.get(request.redirectedFrom())?.id || null,
+      };
+      records.set(request, record); report.requests.push(record); current?.requestIds.push(record.id);
+    });
+    await context.route('**/*', async route => {
+      const request = route.request();
+      const record = records.get(request);
+      let reason;
+      if (report.requests.length >= 500) reason = 'request-limit';
+      else if (!allowed.has(new URL(request.url()).origin)) reason = 'outside-allowed-origins';
+      else if (!allowWrites && !['GET', 'HEAD', 'OPTIONS'].includes(request.method())) reason = 'writes-disabled';
+      if (reason) { if (record) record.blockedReason = reason; await route.abort(); }
+      else await route.continue();
+    });
+    context.on('requestfailed', request => {
+      const record = records.get(request);
+      if (record) { record.outcome = 'failed'; record.failure = record.blockedReason || 'network-failure'; }
+    });
+    context.on('response', response => {
+      const record = records.get(response.request());
+      if (!record) return;
+      record.status = response.status(); record.responseHeaders = safeHeaders(response.headers());
+      record.outcome = response.ok() ? 'http-success' : 'http-error';
+      track((async () => {
+        const type = response.headers()['content-type'] || '';
+        if (!/json/i.test(type)) { record.responseBody = { state: 'omitted', reason: 'non-json-body' }; return; }
+        if (Number(response.headers()['content-length']) > 65536) { record.responseBody = { state: 'omitted', reason: 'body-size-limit' }; return; }
+        // A stalled body cannot hold finalization indefinitely.
+        let timer;
+        try {
+          const text = await Promise.race([response.text(), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('timeout')), 5000); })]);
+          record.responseBody = bodyShape(text, type);
+        } catch { record.responseBody = { state: 'unavailable', reason: 'body-read-failed-or-timeout' }; }
+        finally { clearTimeout(timer); }
+      })());
+    });
+    const state = async () => ({
+      url: safeUrl(page.url() === 'about:blank' ? url : page.url()),
+      invalidInputs: await page.locator('input:invalid,select:invalid,textarea:invalid').count().catch(() => null),
+    });
+    const window = async (action, execute, waitMs = 500) => {
+      current = { id: `T${report.touchpoints.length + 1}`, action, startedAt: new Date().toISOString(), requestIds: [], before: await state(), status: 'running' };
+      report.touchpoints.push(current);
+      try { await execute(); await page.waitForTimeout(waitMs); current.status = 'completed'; }
+      catch { current.status = 'failed'; throw new Error('Browser action failed; check selector, access and tooling. Sensitive browser error details omitted.'); }
+      finally { await flush(); current.after = await state(); current.finishedAt = new Date().toISOString(); }
+    };
+    await window('navigate', () => page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 }));
+    for (const step of flow) {
+      await window(step.action, () => step.action === 'fill' ? page.locator(step.selector).fill(step.value) : page.locator(step.selector).click(), step.waitMs ?? 500);
+    }
+    report.status = report.requests.length >= 500 || report.requests.some(r => r.outcome === 'pending' || r.outcome === 'failed' || r.outcome === 'http-error' || r.responseBody?.state === 'unavailable') ? 'partial' : 'captured';
+  } catch (error) {
+    report.status = 'failed';
+    // Only our own actionable setup errors are returned; browser messages may contain secrets.
+    report.error = /Optional browser tooling|Browser action failed/.test(error.message) ? error.message : 'Browser capture unavailable; check Playwright/browser installation and scoped site access.';
+  } finally {
+    stopped = true;
+    await context?.close().catch(() => {});
+    await flush();
+    await browser?.close().catch(() => {});
+    report.finishedAt = new Date().toISOString(); save();
+  }
+  return report;
+}
+
+module.exports = { capture, origin, safeUrl, shape, bodyShape, safeHeaders, validateFlow };

package/docs/figma-mcp.md

@@ -0,0 +1,131 @@
+# Figma MCP: setup, specs, and implementation
+
+Connect your coding assistant once, extract a design contract, then implement it in your project's own framework. Installing this toolkit installs prompts; it does **not** connect your Figma account or grant access to files.
+
+## 1. Connect Figma
+
+Use the official remote endpoint `https://mcp.figma.com/mcp` and complete Figma OAuth. No personal access token is needed for this route. Choose one setup below; preserve your existing MCP servers when adding configuration.
+
+### Codex
+
+In the Codex app, open Plugins, find Figma, install it, and complete authentication. Alternatively, with Codex CLI installed:
+
+```sh
+codex mcp add figma --url https://mcp.figma.com/mcp
+codex mcp login figma
+codex mcp list
+```
+
+### Claude Code
+
+```sh
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
+
+Start a new session, run `/mcp`, select Figma, and authenticate. Use `--scope user` on the add command if you want it across projects.
+
+### Cursor
+
+Use `/add-plugin figma` in agent chat and authenticate, or follow Figma's manual Cursor installation guide linked below.
+
+### VS Code
+
+Run **MCP: Open Workspace Folder MCP Configuration** (or **MCP: Open User Configuration** for global setup). Merge this entry into the `servers` object:
+
+```json
+{
+  "servers": {
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}
+```
+
+Start the server and complete authentication. This `servers` shape belongs to VS Code; do not paste it into clients expecting `mcpServers` or TOML.
+
+### Desktop alternative
+
+Open the file in Figma desktop, switch to Dev Mode, and enable the desktop MCP server in the inspect panel. Configure your supported client with Streamable HTTP URL `http://127.0.0.1:3845/mcp`. Keep Figma desktop running on the same machine as the MCP client. Desktop access depends on your seat/plan; consult current Figma documentation. Selection-based prompts are available here; use explicit frame links for reproducible handoffs.
+
+### Check the connection
+
+Copy a frame's link, including `node-id`, from a file your authenticated account can access. Ask:
+
+```text
+Use Figma MCP to read this frame's metadata and capture a reference screenshot.
+Report the file key, node ID, tools available, and any access failures.
+Do not change the Figma file or app code.
+URL: paste your frame link here
+```
+
+Success means a real node read and screenshot, not just a configured server. Tool names and capabilities vary by client and server. Load the Figma plugin's prerequisite skills when supplied, especially before `get_design_context` or `use_figma`. `use_figma` is optional; do not require it for basic design-to-code.
+
+## 2. Load the toolkit workflows
+
+```sh
+npx mobile-ai-agents install
+```
+
+Select your coding tool and platform. Install the portable extraction and verification helpers inside your target project:
+
+```sh
+npx mobile-ai-agents figma tools init
+```
+
+This preserves existing helper files. Read `tools/figma-spec/README.md` for Python prerequisites, raw-dump conversion, strict validation and screenshot comparison. In a checkout of this toolkit, you can also run `node /absolute/path/to/mobile-dev-skills/cli/index.js figma tools init` from the target project. Available starting with v1.0.38.
+
+ The three Figma skills are included for every platform. In tools supporting the installed slash commands:
+
+```text
+/figma-mcp-setup
+Help me connect Figma MCP and verify a read of my frame.
+
+/figma-spec-harvest
+URL: paste your frame link here
+FEATURE: checkout
+SCOPE: this frame and its variants
+Extract written requirements, exact available values, assets, and reference screenshots.
+
+/figma-to-implementation
+SPEC: docs/design-spec/checkout
+PLATFORM: detect from this repository
+Implement the verified scope and report requirement and screenshot evidence.
+```
+
+For tools without those commands, ask the assistant to read the corresponding `skills/cross-platform/figma-*.md` files. Use `/figma-to-code` for the combined workflow; `/figma` remains the component translation agent. There is no automatic Figma authentication during toolkit installation. The existing `mobile-ai-agents mcp setup` command configures **Mobile MCP device QA**, not Figma.
+
+## 3. Platform mapping
+
+| Target | Native implementation | Verification |
+|---|---|---|
+| Android | Compose or existing XML Views; semantic theme tokens | Gradle checks and emulator/device captures |
+| iOS | SwiftUI or existing UIKit; dynamic type and safe areas | Xcode build/tests and simulator/device captures |
+| Flutter | Existing Dart state management, bounded flex/scroll layout | Analyze, widget tests, golden/device captures |
+| React Native | Existing JS/TS components and navigation | Project checks and iOS/Android captures |
+| Kotlin Multiplatform | Existing shared UI or separate native UIs | Checks/captures per rendered target |
+| Unity | Existing UI Toolkit or uGUI; canvas scaling and anchors | Editor/player checks and target resolution captures |
+| Unreal | Existing UMG/Slate; anchors and DPI scaling | Compile/automation and viewport captures |
+| Web or other framework | User-selected repository stack | Native build/tests and browser/runtime captures |
+
+Figma pixels describe the reference canvas. Record how they map to logical dp/pt/framework units and responsive constraints; do not use device pixel ratio as a universal conversion. A generated React/Tailwind snippet is evidence about the design, not a reason to change the project's platform.
+
+## Troubleshooting
+
+- **No tools:** restart the client/session, confirm the server is enabled, and check client support. If both remote and desktop are configured, confirm which server is selected.
+- **Access denied:** authenticate the account that can open the design; a shared URL does not guarantee API access.
+- **Rate limit:** record incomplete scope, retry within server guidance, and resume from saved evidence. Do not report a partial harvest as complete.
+- **Missing exact values or written notes:** request the missing export/data or use read-only file inspection if available. Record unknowns; screenshots cannot prove exact token values or hidden behavior.
+- **Missing assets/fonts:** list the gap and resolve licensing/availability before substituting. Respect the client's media-download rules.
+- **Only web code returned:** specify the target framework, reuse repository components, and select the matching Code Connect label when available.
+
+## Sources and validation
+
+Setup checked against official documentation on 2026-10-08:
+- [Figma remote setup](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/)
+- [Figma desktop setup](https://developers.figma.com/docs/figma-mcp-server/local-server-installation/)
+- [Figma tools and prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
+- [OpenAI Codex MCP configuration](https://developers.openai.com/codex/mcp/)
+
+Adapted from the seller-app's `figma-spec-harvest`, `figma-spec-harvester`, `figma-to-flutter`, `figma-to-implementation`, and `design-sync` workflows. No seller-app file IDs, business copy, or package paths are included. Live Figma extraction and per-platform compilation must be validated in users' connected projects; they were not run when authoring this guide.

package/docs/website-api-discovery.md

@@ -0,0 +1,111 @@
+# Website API discovery for mobile developers
+
+Capture a website's HTTP requests and response shapes at each interaction, then hand the evidence to your AI coding agent. This is useful when a web/backend team has shipped a feature and Android, iOS, Flutter, React Native or Kotlin Multiplatform developers need to implement the same API flow.
+
+The runnable command delivers **browser network evidence**, not generated mobile clients or verified mobile parity. Use the [web-network-to-mobile skill](../skills/cross-platform/web-network-to-mobile.md) for that handoff. Follow-up work is tracked in [#70–#72](https://github.com/salmanashraf/mobile-ai-agents/issues/70).
+
+## Run from a checkout
+
+Browser tooling is optional and is not installed with the toolkit. In a project with a package.json:
+
+```bash
+npm install --no-save playwright
+npx playwright install chromium
+```
+
+From this repository, start the owned demo (terminal 1):
+
+```bash
+node cli/fixtures/network-demo.js /tmp/mobile-api-flow.json
+```
+
+Capture the demo (terminal 2):
+
+```bash
+node cli/index.js network capture \
+  --url http://127.0.0.1:4173 \
+  --flow /tmp/mobile-api-flow.json \
+  --out /tmp/mobile-api-demo \
+  --allow-writes
+```
+
+Use a new flow-file path and output directory on subsequent runs; existing outputs are never overwritten. Stop the demo with Ctrl+C. If using installed Google Chrome rather than Playwright Chromium, add `--channel chrome`. `--headed` shows the isolated browser. The module never connects to your personal browser profile.
+
+Available starting in `mobile-ai-agents@1.0.39`. For your own authorized site, use `npx mobile-ai-agents@latest network capture --url URL --out NEW_DIRECTORY`. The owned fixture above runs from a checkout. Playwright must be installed in your project; the optional loader resolves it from the current working directory.
+
+## Expected demo evidence
+
+The fixture exercises six touchpoints:
+
+| Touchpoint | Action | Expected product calls |
+|---|---|---|
+| T1 | Navigate | HTML document; no initial product API call |
+| T2 | Load listings | `GET /api/items` |
+| T3 | Open detail | `GET /api/detail` and `GET /api/options` |
+| T4 | Validate empty title locally | None |
+| T5 | Fill title | None |
+| T6 | Save test listing | `POST /api/save` → 201 |
+
+`capture.json` contains timestamped request IDs, touchpoint windows, methods, sanitized URLs and headers, status codes, observed body schemas, failures and redirect links. `report.md` provides a readable index. Body scalar values are omitted rather than guessed to be safe. For example, an email response field is represented as `{"type":"string"}`, not its actual value.
+
+## Capture your own authorized test flow
+
+Create a JSON array of bounded actions using stable CSS selectors:
+
+```json
+[
+  { "action": "click", "selector": "[data-testid=load-listings]", "waitMs": 1000 },
+  { "action": "fill", "selector": "input[name=title]", "value": "Test listing" },
+  { "action": "click", "selector": "[data-testid=save]", "waitMs": 1500 }
+]
+```
+
+```bash
+node cli/index.js network capture \
+  --url https://staging.example.com/listings \
+  --allow-origin https://api.staging.example.com \
+  --flow flow.json \
+  --out ./api-capture-run-1
+```
+
+Initial navigation is always captured before the steps. Without `--flow`, only initial navigation is inspected. Additional allowed origins are comma-separated; all unlisted HTTP(S) origins are blocked, including third-party analytics. WebSocket connections are blocked and require a current Playwright version with `routeWebSocket` support. Same-origin analytics remain unclassified in the report. Route interception also disables HTTP cache and service workers are blocked so this is a controlled capture rather than faithful cache behavior. There is no crawler, manual interactive recorder, existing-session import, or automatic login bypass.
+
+Only GET, HEAD and OPTIONS are allowed by default. `--allow-writes` enables other HTTP methods for the supplied flow; use it only for authorized test data and resettable environments. Read-like GraphQL POST requests also require it. An HTTP method alone cannot establish that an endpoint is safe; even GET can have side effects. The tool does not retry or replay failed writes.
+
+## Evidence limits and privacy
+
+- Attribution is by the active time window, not a causal dependency graph. A delayed request may appear under a later touchpoint. Choose waits appropriate to the test and inspect the timestamps.
+- JSON and URL-encoded request shapes and JSON response shapes are sampled observations. Requiredness, enum ranges and all error responses cannot be inferred from a single run. GraphQL operation values, socket/SSE messages, multipart values and binary data are not recorded.
+- Query values, URL credentials, fragments and non-content header values are removed/redacted. Numeric/opaque route segments are redacted. Readable path segments, origins, query keys and JSON property names remain; review them before sharing. This is not a guarantee of anonymous artifacts.
+- No screenshot, DOM text, raw HAR, auth storage or body scalar values are written. Input flow files can contain sensitive test values; keep them local. Redirect links use captured request IDs. Auth presence is a hint from exposed header names, not a complete authentication contract.
+- Fresh context, one page, 390×844 viewport; popups are closed. Default action timeout 10 seconds, navigation timeout 15 seconds, body-read timeout 5 seconds, at most 50 actions, 500 captured requests, 64 KiB body inspection, and depth/array sampling limits. Body transfer itself is not capped when content length is unavailable. Do not use large download/streaming flows.
+- `captured` means scoped browser windows completed without recorded failures. HTTP errors, blocked requests, pending requests or unavailable JSON bodies yield `partial`; action/browser failures yield `failed`. Partial/failed runs return a nonzero exit code and retain evidence. Neither status proves mobile parity.
+
+## Mobile integration handoff
+
+Give your coding agent the report, the current app repository, and an explicit target:
+
+```text
+Use skills/cross-platform/web-network-to-mobile.md.
+Read /tmp/mobile-api-demo/capture.json and report.md as observed browser evidence.
+Map each touchpoint to the existing Flutter app's networking and UI architecture.
+Cross-check the backend contract before resolving optional fields or auth.
+Implement the scoped flow, then verify actual mobile requests and UI behavior.
+Keep missing runtime evidence unverified.
+```
+
+Use the same process for Android, iOS, React Native and KMP; tooling and runtime proof are target-specific. Mobile MCP UI screenshots do not establish network parity. Use app-owned debug instrumentation or authorized server correlation for the network side.
+
+## Maintainer decisions and validation
+
+Issue [#69](https://github.com/salmanashraf/mobile-ai-agents/issues/69) uses an optional Playwright adapter, a fresh browser context and an owned demo instead of a default browser dependency. CLI command modules and fixtures are already inside the package's shipped `cli/` directory. This resolves the capture-specific adapter/demo choices from #63; the broader MIRROR design/build inventory remains separate. Reuse #54/#55 for device QA/demo and #57 for visual checks rather than duplicating them here.
+
+Run deterministic checks with `npm test`. Browser tests skip when Playwright is absent; require real browser validation with:
+
+```bash
+NETWORK_BROWSER_TESTS=1 NETWORK_BROWSER_CHANNEL=chrome node --test test/network-capture.test.js
+```
+
+Remove `NETWORK_BROWSER_CHANNEL=chrome` to use installed Playwright Chromium. Browser tests use only a loopback fixture and cover observed shapes, zero/multiple calls, blocked writes/origins, HTTP/network failures and failed actions. They do not validate any mobile runtime.
+
+Discoverability phrases used here describe the delivered behavior: **website API discovery**, **browser network capture**, **HTTP request and response analysis**, and **mobile API integration**. Search-volume and ranking data have not been measured; keywords do not guarantee Google/GitHub placement or virality.

package/docs/wiki.md

@@ -768,3 +768,12 @@ A: Yes. The repo is MIT licensed — free to use, modify, and incorporate into c
 ---
 
 *Last updated: v1.0.25 — August 2026*
+
+## Figma MCP and Design Handoff
+
+Connect your coding assistant using the [Figma MCP guide](figma-mcp.md). Use `/figma-spec-harvest` for source-traced specs and `/figma-to-implementation` to build in the existing platform. `/figma-to-code` chains setup, harvest, implementation and evidence checks. Install portable helpers with `npx mobile-ai-agents figma tools init`; this preserves existing files and does not authenticate Figma. APPFORGE, Mobile Harness and `/prd-verification` carry node/AC traceability into planning and verification.
+
+
+## Website API discovery and mobile handoff
+
+Starting in v1.0.39, `npx mobile-ai-agents@latest network capture --url URL --out NEW_DIRECTORY` records bounded website flows with optional Playwright. The `/web-network-to-mobile` skill is installed across platform bundles and maps browser request/response evidence to the existing mobile stack. See [the setup and owned demo](website-api-discovery.md). Captures are observed shapes with temporal attribution; mobile implementation and actual network/UI verification remain separate.

package/install.sh

@@ -93,6 +93,7 @@ _agent_lines() {
 # Outputs: "<slug> <src_path>" lines
 _skill_lines() {
     # Cross-platform skills (always)
+    echo "web-network-to-mobile skills/cross-platform/web-network-to-mobile.md"
     echo "grill-mobile        skills/cross-platform/grill-mobile.md"
     echo "crash-triage        skills/cross-platform/crash-triage.md"
     echo "perf-audit          skills/cross-platform/perf-audit.md"
@@ -215,6 +216,7 @@ install_claude() {
     echo "   /security-scanner  /store-listing-writer"
     echo ""
     echo "   Cross-platform skills:"
+    echo "   /web-network-to-mobile"
     echo "   /grill-mobile  /clean-code-audit  /security-audit  /crash-triage"
     echo "   /perf-audit  /store-listing  /release-prep"
     echo "   /feature-slice  /mobile-mcp-qa  /mobile-memory-save  /mobile-memory-graph"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-ai-agents",
-  "version": "1.0.37",
+  "version": "1.0.39",
   "description": "AI agents, skills, and Loop Engineering workflows for building, testing, auditing, and releasing mobile apps.",
   "bin": {
     "mobile-ai-agents": "cli/index.js",
@@ -19,7 +19,8 @@
     "mobile-karpathy.md",
     "skills/",
     "templates/",
-    "workflows/"
+    "workflows/",
+    "tools/figma-spec/"
   ],
   "keywords": [
     "mobile",
@@ -40,6 +41,10 @@
     "skills",
     "loop-engineering",
     "mobile-harness",
+    "api-discovery",
+    "network-traffic-analysis",
+    "browser-automation",
+    "api-integration",
     "llm",
     "cursor",
     "windsurf"

package/skills/cross-platform/figma-mcp-setup.md

@@ -0,0 +1,60 @@
+# Skill — /figma-mcp-setup
+
+**Platform:** Cross-Platform  
+**Category:** UI & Design  
+**Composable With:** FIGMA, /figma-spec-harvest, /figma-to-implementation, /prd-verification, /mobile-mcp-qa
+
+## Purpose
+
+Connect a supported assistant to official Figma MCP and verify read access.
+
+## When to Use
+
+- First Figma connection or authentication troubleshooting.
+- Before harvesting a design when MCP tools are missing.
+
+## Inputs
+
+Client name/version, remote or desktop preference, and a frame URL for verification.
+
+## Skill Prompt
+
+```text
+You help the user configure official Figma MCP for their chosen coding client.
+Prefer the official remote server https://mcp.figma.com/mcp with OAuth. Offer
+http://127.0.0.1:3845/mcp when desktop selection access is wanted and supported.
+Identify the client before choosing its configuration syntax. Follow the current
+official Figma setup guide; use docs/figma-mcp.md when present. Preserve existing
+servers. Installing toolkit prompts does not configure MCP or authenticate Figma.
+Do not print credentials. Let the user complete OAuth in the client's flow.
+Discover available tools and load any required vendor skills before calling them.
+Verify with a real read of the supplied node plus reference screenshot. Never edit
+Figma or app code during setup. If no URL is provided, configuration can be ready
+but access remains unverified. Do not claim a live check from static configuration.
+Return: CLIENT, SERVER, CONFIGURATION (ready|missing), AUTH (verified|unverified),
+READ (pass|fail|unverified), SCREENSHOT (pass|fail|unverified), NEXT ACTION.
+```
+
+## Example
+
+**Input:** `Client: VS Code. Remote. No frame URL yet. Existing configuration contains figma.url=https://mcp.figma.com/mcp and type=http.`
+
+**Output:**
+```text
+CLIENT: VS Code
+SERVER: https://mcp.figma.com/mcp
+CONFIGURATION: ready
+AUTH: unverified
+READ: unverified
+SCREENSHOT: unverified
+NEXT ACTION: Start the server, authenticate, and supply an accessible frame link.
+```
+
+## Composition Example
+
+Use this skill before `/figma-spec-harvest`; proceed when node access is verified.
+
+## Notes
+
+- Official setup and client-specific examples: https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
+- Tested with: authored/reviewed in Codex; no live OAuth or Figma read test performed.