@swmansion/argent 0.16.2-next.9 → 0.17.0

package/dist/tool-server.cjs

@@ -109,7 +109,9 @@ var init_artifacts = __esm({
       ".xml": "application/xml",
       ".txt": "text/plain",
       ".md": "text/markdown",
-      ".html": "text/html"
+      ".html": "text/html",
+      ".mp4": "video/mp4",
+      ".mov": "video/quicktime"
     };
     ArtifactStore = class {
       entries = /* @__PURE__ */ new Map();
@@ -138,6 +140,7 @@ var init_artifacts = __esm({
         };
         if (mtimeMs != null) handle.mtimeMs = mtimeMs;
         if (isDirectory2) handle.archive = "tar.gz";
+        if (opts?.saveDir) handle.saveDir = opts.saveDir;
         return handle;
       }
       get(id) {
@@ -382,6 +385,7 @@ var init_failure_codes = __esm({
       SCREEN_RECORDING_NO_ACTIVE_SESSION: "SCREEN_RECORDING_NO_ACTIVE_SESSION",
       SCREEN_RECORDING_STOP_IN_PROGRESS: "SCREEN_RECORDING_STOP_IN_PROGRESS",
       SCREEN_RECORDING_START_EXITED: "SCREEN_RECORDING_START_EXITED",
+      SCREEN_RECORDING_START_TIMEOUT: "SCREEN_RECORDING_START_TIMEOUT",
       SCREEN_RECORDING_PROCESS_ERROR: "SCREEN_RECORDING_PROCESS_ERROR",
       SCREEN_RECORDING_OUTPUT_MISSING: "SCREEN_RECORDING_OUTPUT_MISSING",
       SCREEN_RECORDING_SERVER_SHUTTING_DOWN: "SCREEN_RECORDING_SERVER_SHUTTING_DOWN",
@@ -34931,7 +34935,7 @@ var require_view = __commonJS({
     var path38 = require("node:path");
     var fs50 = require("node:fs");
     var dirname14 = path38.dirname;
-    var basename9 = path38.basename;
+    var basename10 = path38.basename;
     var extname4 = path38.extname;
     var join46 = path38.join;
     var resolve7 = path38.resolve;
@@ -34970,7 +34974,7 @@ var require_view = __commonJS({
         var root2 = roots[i];
         var loc = resolve7(root2, name);
         var dir = dirname14(loc);
-        var file2 = basename9(loc);
+        var file2 = basename10(loc);
         path39 = this.resolve(dir, file2);
       }
       return path39;
@@ -35000,7 +35004,7 @@ var require_view = __commonJS({
       if (stat4 && stat4.isFile()) {
         return path39;
       }
-      path39 = join46(dir, basename9(file2, ext), "index" + ext);
+      path39 = join46(dir, basename10(file2, ext), "index" + ext);
       stat4 = tryStat(path39);
       if (stat4 && stat4.isFile()) {
         return path39;
@@ -57445,9 +57449,9 @@ var require_content_disposition = __commonJS({
       if (typeof fallback === "string" && NON_LATIN1_REGEXP.test(fallback)) {
         throw new TypeError("fallback must be ISO-8859-1 string");
       }
-      var name = basename9(filename);
+      var name = basename10(filename);
       var isQuotedString = TEXT_REGEXP.test(name);
-      var fallbackName = typeof fallback !== "string" ? fallback && getlatin1(name) : basename9(fallback);
+      var fallbackName = typeof fallback !== "string" ? fallback && getlatin1(name) : basename10(fallback);
       var hasFallback = typeof fallbackName === "string" && fallbackName !== name;
       if (hasFallback || !isQuotedString || hasHexEscape(name)) {
         params["filename*"] = name;
@@ -57567,7 +57571,7 @@ var require_content_disposition = __commonJS({
       this.type = type;
       this.parameters = parameters;
     }
-    function basename9(path38) {
+    function basename10(path38) {
       const normalized = path38.replaceAll("\\", "/");
       let end = normalized.length;
       while (end > 0 && normalized[end - 1] === "/") {
@@ -104489,7 +104493,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.16.1";
+    return "0.17.0";
   }
   return "0.0.0";
 }
@@ -105877,7 +105881,7 @@ var import_node_path5 = __toESM(require("node:path"));
 var import_semver = __toESM(require_semver2());
 
 // ../tool-server/package.json
-var version3 = "0.16.1";
+var version3 = "0.17.0";
 
 // ../tool-server/src/utils/update-checker.ts
 var import_update_core = __toESM(require_dist4());
@@ -114038,6 +114042,27 @@ function sendCommand(api, cmd) {
     ws.once("open", () => ws.send(payload));
   }
 }
+function setPointerVisible(api, show, signal) {
+  return pointerPost(api, { show }, signal);
+}
+function setPointerTrail(api, trail, signal) {
+  return pointerPost(api, { trail }, signal);
+}
+async function pointerPost(api, body, signal) {
+  try {
+    const res = await fetch(`${api.apiUrl}/api/pointer`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!res.ok) return false;
+    const parsed = await res.json().catch(() => null);
+    return parsed?.status === "ok";
+  } catch {
+    return false;
+  }
+}
 async function simulatorPost(toolLabel, api, endpoint, reqBody, signal, fallbackHint) {
   let res;
   try {
@@ -142986,6 +143011,8 @@ function clearLiveState2(state3) {
   state3.pendingChild = null;
   state3.frameStream = null;
   state3.lastFrameStreamError = null;
+  state3.pointerDisable = null;
+  state3.pointerFailed = false;
   state3.recordingTimedOut = false;
   state3.recordingExitedUnexpectedly = false;
   state3.lastExitInfo = null;
@@ -143039,6 +143066,8 @@ var screenRecordingSessionBlueprint = {
       trimStatic: true,
       framesWritten: 0,
       trimmedAnyFrames: false,
+      pointerDisable: null,
+      pointerFailed: false,
       wallClockStartMs: null,
       wallClockEndMs: null,
       timeLimitSeconds: null,
@@ -143061,6 +143090,12 @@ var screenRecordingSessionBlueprint = {
           state3.pumpTimer = null;
         }
         state3.frameStream?.close();
+        if (state3.pointerDisable) {
+          const disable = state3.pointerDisable;
+          state3.pointerDisable = null;
+          await disable().catch(() => {
+          });
+        }
         if (state3.pendingChild) {
           try {
             state3.pendingChild.kill("SIGKILL");
@@ -143593,6 +143628,12 @@ function startPump(api, stream) {
     }
   }, FRAME_INTERVAL_MS);
 }
+async function disablePointer(api) {
+  const disable = api.pointerDisable;
+  api.pointerDisable = null;
+  if (disable) await disable().catch(() => {
+  });
+}
 function stopPump(api) {
   if (api.pumpTimer) {
     clearInterval(api.pumpTimer);
@@ -143687,6 +143728,7 @@ async function startCaptureLocked(api, params) {
   api.recordingTimedOut = false;
   api.recordingExitedUnexpectedly = false;
   api.pendingRetrieval = false;
+  api.pointerFailed = false;
   api.lastExitInfo = null;
   api.lastFrameStreamError = null;
   api.outputFile = outputFile;
@@ -143702,16 +143744,6 @@ async function startCaptureLocked(api, params) {
   api.timeLimitSeconds = params.timeLimitSeconds;
   registerActiveScreenRecording(api.deviceId, api.wallClockStartMs, params.timeLimitSeconds);
   startPump(api, stream);
-  api.recordingTimeout = setTimeout(() => {
-    api.recordingTimeout = null;
-    if (api.captureProcess !== child) return;
-    api.recordingTimedOut = true;
-    api.recordingActive = false;
-    api.wallClockEndMs = Date.now();
-    api.pendingRetrieval = true;
-    markScreenRecordingFinalized(api.deviceId, `it hit its ${params.timeLimitSeconds}s time limit`);
-    finalizeCapture(api);
-  }, params.timeLimitSeconds * 1e3);
   child.on("exit", (code, signal) => {
     if (api.captureProcess !== child) return;
     api.lastExitInfo = { code, signal };
@@ -143726,9 +143758,25 @@ async function startCaptureLocked(api, params) {
       api.wallClockEndMs = Date.now();
       api.pendingRetrieval = true;
       stopPump(api);
+      void disablePointer(api);
       markScreenRecordingFinalized(api.deviceId, "the recording process exited unexpectedly");
     }
   });
+  if (params.pointer) {
+    api.pointerDisable = params.pointer.disable;
+    api.pointerFailed = !await params.pointer.enable();
+  }
+  api.recordingTimeout = setTimeout(() => {
+    api.recordingTimeout = null;
+    if (api.captureProcess !== child) return;
+    api.recordingTimedOut = true;
+    api.recordingActive = false;
+    api.wallClockEndMs = Date.now();
+    api.pendingRetrieval = true;
+    markScreenRecordingFinalized(api.deviceId, `it hit its ${params.timeLimitSeconds}s time limit`);
+    finalizeCapture(api);
+    void disablePointer(api);
+  }, params.timeLimitSeconds * 1e3);
   return {
     status: "recording",
     timeLimitSeconds: params.timeLimitSeconds,
@@ -143795,6 +143843,7 @@ async function stopCapture(api) {
   const endedEarly = api.recordingTimedOut || api.recordingExitedUnexpectedly;
   const streamError = api.frameStream?.error ?? api.lastFrameStreamError ?? null;
   const watermarkSkipped = api.watermarkSkipped;
+  const pointerFailed = api.pointerFailed;
   let warning;
   try {
     const child = api.captureProcess;
@@ -143828,6 +143877,12 @@ async function stopCapture(api) {
     if (watermarkSkipped) {
       warning = [warning, `The watermark was not applied (${watermarkSkipped}).`].filter(Boolean).join(" ");
     }
+    if (pointerFailed) {
+      warning = [
+        warning,
+        "The touch visualizer could not be enabled on simulator-server, so touches are not shown in this video."
+      ].filter(Boolean).join(" ");
+    }
     const size = await statNonEmptyOutput(outputFile, "screen_recording_stop");
     const wallClockMs = startedAtMs === null ? null : (api.wallClockEndMs ?? Date.now()) - startedAtMs;
     const durationMs = trimStatic ? Math.round(api.framesWritten / OUTPUT_FPS2 * 1e3) : wallClockMs;
@@ -143846,6 +143901,7 @@ async function stopCapture(api) {
     throw err;
   } finally {
     stopPump(api);
+    await disablePointer(api);
     api.recordingActive = false;
     api.stopPending = false;
     api.pendingRetrieval = false;
@@ -143853,6 +143909,7 @@ async function stopCapture(api) {
     api.outputFile = null;
     api.logoFile = null;
     api.watermarkSkipped = null;
+    api.pointerFailed = false;
     api.framesWritten = 0;
     api.trimmedAnyFrames = false;
     api.wallClockStartMs = null;
@@ -143871,6 +143928,8 @@ async function stopCapture(api) {
 // ../tool-server/src/tools/screen-recording/screen-recording-start.ts
 var DEFAULT_TIME_LIMIT_SECONDS = 180;
 var MAX_TIME_LIMIT_SECONDS = 600;
+var POINTER_TRAIL_LENGTH = 8;
+var POINTER_REQUEST_TIMEOUT_MS = 2e3;
 var zodSchema51 = external_exports.object({
   udid: external_exports.string().describe("Target device id from `list-devices` (iOS Simulator UDID or Android serial)."),
   timeLimitSeconds: external_exports.number().int().min(1).max(MAX_TIME_LIMIT_SECONDS).optional().describe(
@@ -143878,6 +143937,9 @@ var zodSchema51 = external_exports.object({
   ),
   trimStatic: external_exports.boolean().optional().describe(
     "Default true. Collapse stretches where the screen does not change: the first second of each still stretch is kept, then unchanged frames are dropped until something moves again, so a long recording with brief activity comes back short instead of full of dead air. The returned durationMs is the trimmed length; wallClockMs/trimmedMs report what was removed. Set false to keep a faithful real-time recording."
+  ),
+  showTouches: external_exports.boolean().optional().describe(
+    "Default true. Draw simulator-server's touch visualizer into the recording: a pulse marks each tap, a comet trail follows swipes and drags, and paired markers show two-finger pinch/rotate, so the video makes clear where every interaction landed. Set false to record the raw screen with no overlay."
   )
 });
 var capability26 = {
@@ -143890,6 +143952,7 @@ function createScreenRecordingStartTool(registry2) {
     capability: capability26,
     description: `Start recording the device screen to a video file (h264 mp4, 30fps at the device's native resolution).
 By default stretches where the screen does not change are trimmed out (see trimStatic), so a long session with only brief activity comes back as a short clip instead of minutes of dead air.
+By default every tap, swipe, drag, pinch and rotate is drawn into the video as an on-screen touch marker (see showTouches), so the recording shows where each interaction landed.
 The recording keeps running across other tool calls (every result carries a reminder) until \`screen-recording-stop\` is called or timeLimitSeconds elapses \u2014 immediately after starting, set yourself a reminder/wakeup for the expected end of the recording so it is never left running.
 Use when the user wants a video of an interaction, animation, or app behavior \u2014 for a single still frame use \`screenshot\` instead.
 Returns { status: "recording", timeLimitSeconds, outputFile } \u2014 the video is retrieved later by \`screen-recording-stop\`, not by reading outputFile directly.
@@ -143934,21 +143997,53 @@ Fails if a recording is already running on the device, the device is not booted,
           }
         );
       }
+      const showTouches = params.showTouches ?? true;
+      const pointer = showTouches ? makePointerControl(simulator) : void 0;
       return startCapture(api, {
         streamUrl,
         timeLimitSeconds,
         watermark: isFeatureEnabled("video-watermark"),
-        trimStatic: params.trimStatic ?? true
+        trimStatic: params.trimStatic ?? true,
+        pointer
       });
     }
   };
 }
+function makePointerControl(simulator) {
+  let enabling = null;
+  return {
+    async enable() {
+      const run2 = (async () => {
+        await setPointerTrail(
+          simulator,
+          POINTER_TRAIL_LENGTH,
+          AbortSignal.timeout(POINTER_REQUEST_TIMEOUT_MS)
+        );
+        return setPointerVisible(simulator, true, AbortSignal.timeout(POINTER_REQUEST_TIMEOUT_MS));
+      })();
+      enabling = run2;
+      try {
+        return await run2;
+      } finally {
+        if (enabling === run2) enabling = null;
+      }
+    },
+    async disable() {
+      const pending = enabling;
+      if (pending) await pending.catch(() => {
+      });
+      await setPointerVisible(simulator, false, AbortSignal.timeout(POINTER_REQUEST_TIMEOUT_MS));
+    }
+  };
+}
 
 // ../tool-server/src/tools/screen-recording/screen-recording-stop.ts
+var import_node_path20 = require("node:path");
 init_zod();
 var zodSchema52 = external_exports.object({
   udid: external_exports.string().describe("Target device id from `list-devices` (iOS Simulator UDID or Android serial).")
 });
+var RECORDINGS_DIR = ".argent/recordings";
 var capability27 = {
   apple: { simulator: true },
   android: { emulator: true, device: true, unknown: true }
@@ -143972,7 +144067,13 @@ Fails if no recording (running or finished-but-unretrieved) exists for the given
     assertSupported("screen-recording-stop", capability27, device);
     const stopped = await stopCapture(api);
     const artifacts = requireArtifacts(ctx);
-    const video = await artifacts.register(stopped.outputFile, { mimeType: "video/mp4" });
+    const video = await artifacts.register(stopped.outputFile, {
+      mimeType: "video/mp4",
+      // Drop the internal `argent-` temp prefix so the saved file reads cleanly
+      // as `.argent/recordings/screen-recording-<device>-<ts>.mp4`.
+      filename: (0, import_node_path20.basename)(stopped.outputFile).replace(/^argent-/, ""),
+      saveDir: RECORDINGS_DIR
+    });
     const result = { video, durationMs: stopped.durationMs };
     if (stopped.wallClockMs !== void 0) result.wallClockMs = stopped.wallClockMs;
     if (stopped.trimmedMs !== void 0) result.trimmedMs = stopped.trimmedMs;
@@ -150994,7 +151095,7 @@ init_zod();
 
 // ../tool-server/src/utils/workspace-reader.ts
 var import_promises12 = require("node:fs/promises");
-var import_node_path20 = require("node:path");
+var import_node_path21 = require("node:path");
 var import_node_child_process27 = require("node:child_process");
 var import_dotenv = __toESM(require_main());
 async function exists(path38) {
@@ -151082,7 +151183,7 @@ async function detectLockfile(workspacePath) {
   const checks = await Promise.all(
     LOCKFILES.map(async (name) => ({
       name,
-      exists: await exists((0, import_node_path20.join)(workspacePath, name))
+      exists: await exists((0, import_node_path21.join)(workspacePath, name))
     }))
   );
   return checks.find((c) => c.exists)?.name ?? null;
@@ -151101,7 +151202,7 @@ var CI_CONFIGS = [
 ];
 async function detectCiConfig(workspacePath) {
   for (const ci of CI_CONFIGS) {
-    if (await exists((0, import_node_path20.join)(workspacePath, ci.path))) return ci.label;
+    if (await exists((0, import_node_path21.join)(workspacePath, ci.path))) return ci.label;
   }
   return null;
 }
@@ -151122,7 +151223,7 @@ async function detectLintStagedConfig(workspacePath, packageJson) {
     return packageJson["lint-staged"];
   }
   for (const file2 of LINT_STAGED_FILES) {
-    const full = (0, import_node_path20.join)(workspacePath, file2);
+    const full = (0, import_node_path21.join)(workspacePath, file2);
     if (await exists(full)) {
       if (file2.endsWith(".json") || file2 === ".lintstagedrc") {
         return readJsonFile(full);
@@ -151164,7 +151265,7 @@ var CONFIG_FILES = [
 async function detectConfigFiles(workspacePath) {
   const results = await Promise.allSettled(
     CONFIG_FILES.map(async (file2) => {
-      if (await exists((0, import_node_path20.join)(workspacePath, file2))) return file2;
+      if (await exists((0, import_node_path21.join)(workspacePath, file2))) return file2;
       return null;
     })
   );
@@ -151203,7 +151304,7 @@ async function detectEnvFiles(workspacePath) {
   const envFileNames = entries.filter((e) => e === ".env" || e.startsWith(".env."));
   const results = await Promise.all(
     envFileNames.map(async (name) => {
-      const content = await readTextFile((0, import_node_path20.join)(workspacePath, name));
+      const content = await readTextFile((0, import_node_path21.join)(workspacePath, name));
       return {
         name,
         keys: content ? extractEnvKeys(content) : []
@@ -151230,34 +151331,34 @@ async function readWorkspaceSnapshot(workspacePath) {
     ciConfig,
     configFilesFound
   ] = await Promise.all([
-    readJsonFile((0, import_node_path20.join)(workspacePath, "package.json")),
-    readJsonFile((0, import_node_path20.join)(workspacePath, "app.json")),
-    readJsonFile((0, import_node_path20.join)(workspacePath, "eas.json")),
-    readJsonFile((0, import_node_path20.join)(workspacePath, "tsconfig.json")),
-    readTextFile((0, import_node_path20.join)(workspacePath, "metro.config.js")).then(
-      (r) => r ?? readTextFile((0, import_node_path20.join)(workspacePath, "metro.config.ts"))
+    readJsonFile((0, import_node_path21.join)(workspacePath, "package.json")),
+    readJsonFile((0, import_node_path21.join)(workspacePath, "app.json")),
+    readJsonFile((0, import_node_path21.join)(workspacePath, "eas.json")),
+    readJsonFile((0, import_node_path21.join)(workspacePath, "tsconfig.json")),
+    readTextFile((0, import_node_path21.join)(workspacePath, "metro.config.js")).then(
+      (r) => r ?? readTextFile((0, import_node_path21.join)(workspacePath, "metro.config.ts"))
     ),
-    readTextFile((0, import_node_path20.join)(workspacePath, "babel.config.js")).then(
-      (r) => r ?? readTextFile((0, import_node_path20.join)(workspacePath, "babel.config.cjs"))
+    readTextFile((0, import_node_path21.join)(workspacePath, "babel.config.js")).then(
+      (r) => r ?? readTextFile((0, import_node_path21.join)(workspacePath, "babel.config.cjs"))
     ),
-    isDirectory((0, import_node_path20.join)(workspacePath, "ios")),
-    isDirectory((0, import_node_path20.join)(workspacePath, "android")),
+    isDirectory((0, import_node_path21.join)(workspacePath, "ios")),
+    isDirectory((0, import_node_path21.join)(workspacePath, "android")),
     detectLockfile(workspacePath),
     detectEnvFiles(workspacePath),
     detectToolVersions(workspacePath),
-    listDir((0, import_node_path20.join)(workspacePath, "scripts")),
-    listDir((0, import_node_path20.join)(workspacePath, ".husky")),
+    listDir((0, import_node_path21.join)(workspacePath, "scripts")),
+    listDir((0, import_node_path21.join)(workspacePath, ".husky")),
     detectCiConfig(workspacePath),
     detectConfigFiles(workspacePath)
   ]);
-  const iosDir = (0, import_node_path20.join)(workspacePath, "ios");
-  const androidDir = (0, import_node_path20.join)(workspacePath, "android");
+  const iosDir = (0, import_node_path21.join)(workspacePath, "ios");
+  const androidDir = (0, import_node_path21.join)(workspacePath, "android");
   const [iosWorkspace, iosHasPodfile, makefileText, lintStagedConfig, androidHasGradle] = await Promise.all([
     hasIosDir ? findIosWorkspace(iosDir) : Promise.resolve(null),
-    exists((0, import_node_path20.join)(workspacePath, "ios", "Podfile")),
-    readTextFile((0, import_node_path20.join)(workspacePath, "Makefile")),
+    exists((0, import_node_path21.join)(workspacePath, "ios", "Podfile")),
+    readTextFile((0, import_node_path21.join)(workspacePath, "Makefile")),
     detectLintStagedConfig(workspacePath, packageJson),
-    hasAndroidDir ? exists((0, import_node_path20.join)(androidDir, "gradlew")) : Promise.resolve(false)
+    hasAndroidDir ? exists((0, import_node_path21.join)(androidDir, "gradlew")) : Promise.resolve(false)
   ]);
   const metroPort = metroConfigRaw ? extractMetroPort(metroConfigRaw) : null;
   const makefileTargets = makefileText ? extractMakefileTargets(makefileText) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.16.2-next.9",
+  "version": "0.17.0",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {

package/skills/argent-screen-recording/SKILL.md

@@ -24,14 +24,18 @@ A recording does not stop itself before its `timeLimitSeconds` cap, so a forgott
 ## 3. Workflow
 
 1. Ensure the target device is booted and the app is in the state you want the video to open on (`list-devices`, `launch-app`, `argent-device-interact`).
-2. Call `screen-recording-start` with `udid` and a `timeLimitSeconds` slightly above the expected interaction length (default 180, max 600).
+2. Call `screen-recording-start` with `udid` and a `timeLimitSeconds` slightly above the expected interaction length (default 180, max 600). Taps and swipes are drawn into the video by default (see the touch-visualizer note below); pass `showTouches: false` for a clean raw-screen capture.
 3. Set the end-of-recording reminder described in §2 — this step is not optional.
 4. Drive the interaction to capture: gestures, navigation, typing (`argent-device-interact`). Prefer `run-sequence` for tight multi-step interactions so tool-call latency does not pad the video.
-5. Call `screen-recording-stop` with the same `udid`. It returns `{ video, durationMs, wallClockMs?, trimmedMs?, warning? }`; `video` is an artifact — use its `hostPath` locally or download it via the artifacts endpoint. The video is already final when stop returns (the watermark is stamped during capture, not in a second pass), so stop takes well under a second.
+5. Call `screen-recording-stop` with the same `udid`. It returns `{ video, durationMs, wallClockMs?, trimmedMs?, warning? }`; `video` is an artifact whose resolved path points at the durably-saved file (see below). The video is already final when stop returns (the watermark is stamped during capture, not in a second pass), so stop takes well under a second.
 6. Check `warning`: it reports cap-triggered stops, early encoder exits, a dropped frame stream, and possibly-truncated containers. Verify the file plays (or at least has a sane size) before presenting it to the user.
 
+**Where the file lands (durable, not scratch).** Unlike most argent artifacts (which live in a disposable temp cache the OS reclaims), a finished recording is saved durably on the **client** into `<project>/.argent/recordings/` — the project being the nearest ancestor of the client's working directory with a `.git`/`package.json`/`.argent`, or `~/.argent/recordings/` when the client isn't inside a project. This holds even for a remote `argent link` tool-server: the mp4 is written on the client host, not the server. The saved name is `screen-recording-<device>-<timestamp>.mp4`; if that name is already taken the new file lands beside it as `… (2).mp4` rather than overwriting. Because these files persist in the working tree, mention the path to the user (and note that they are untracked — add them to `.gitignore` or clean them up if they shouldn't be committed).
+
 **Static-frame trimming (on by default).** Stretches where the screen does not change are collapsed: the first second of each still stretch is kept so pauses read naturally, then unchanged frames are dropped until something moves again (a change of even a couple of pixels counts). So you can leave a recording running across slow steps, waits, or thinking time without padding the clip with dead air — a 40-second session with 5 seconds of real activity comes back as a ~5-7 second video. When trimming removed anything, stop also returns `wallClockMs` (real elapsed time) and `trimmedMs` (how much was cut); `durationMs` is always the length of the video you actually get. Pass `trimStatic: false` to `screen-recording-start` when you want a faithful real-time recording (e.g. to measure how long something took on screen).
 
+**Touch visualizer (on by default).** Every interaction argent drives is drawn straight into the video: a pulse marks each tap, a fading comet trail follows swipes and drags, and paired markers show the two contact points of a pinch or rotate. This makes a recording self-explanatory — a viewer can see _where_ each gesture landed rather than watching the UI react to an invisible finger. It is rendered by simulator-server into the frame stream (nothing is composited host-side), so it costs nothing extra and never appears in a `screenshot`. Pass `showTouches: false` to `screen-recording-start` to record the raw screen with no overlay (e.g. when capturing exactly what the user would see). If simulator-server cannot enable it, the recording still succeeds and stop returns a `warning` saying touches are not shown.
+
 ---
 
 ## 4. Platform notes and limits