command-cmd 1.0.2 → 1.0.5

package/cmd.js

@@ -1,3 +1,135 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const { readFile, writeFile, mkdir } = fs.promises;
+const { resolve: resolvePath, dirname: dirnamePath } = path;
+
+const MODULE_DIR = dirnamePath(fileURLToPath(import.meta.url));
+
+const DEFAULT_APPS = Object.freeze({
+  spotify: {
+    launcher: { x: -2, y: 145 },
+    searchIcon: { x: 584, y: 90 }
+  },
+  chrome: {
+    launcher: { x: 20, y: 219 },
+    searchIcon: { x: 546, y: 87 }
+  },
+  youtube: {
+    launcher: { x: 20, y: 225 },
+    searchIcon: { x: 575, y: 144 }
+  }
+});
+
+const DOC_TEMPLATE_MAP = Object.freeze({
+  doc_en: Object.freeze({
+    key: 'doc_en',
+    source: 'doc.md',
+    target: 'doc.md',
+    isMapDoc: false
+  }),
+  doc_ptbr: Object.freeze({
+    key: 'doc_ptbr',
+    source: 'docPTBR.md',
+    target: 'docPTBR.md',
+    isMapDoc: false
+  }),
+  map_en: Object.freeze({
+    key: 'map_en',
+    source: 'map.md',
+    target: 'map.md',
+    isMapDoc: true
+  }),
+  map_ptbr: Object.freeze({
+    key: 'map_ptbr',
+    source: 'mapPTBR.md',
+    target: 'mapPTBR.md',
+    isMapDoc: true
+  })
+});
+
+const DOC_TEMPLATES = Object.freeze(Object.values(DOC_TEMPLATE_MAP));
+
+const ACTION_ALIASES = Object.freeze({
+  skip_ads: 'skip_ads',
+  skipads: 'skip_ads',
+  pular_ads: 'skip_ads',
+  pularads: 'skip_ads',
+  click: 'click',
+  clicar: 'click',
+  double_click: 'double_click',
+  doubleclick: 'double_click',
+  clique_duplo: 'double_click',
+  cliqueduplo: 'double_click',
+  scroll: 'scroll',
+  rolar: 'scroll',
+  move_sequence: 'move_sequence',
+  movesequence: 'move_sequence',
+  mover_sequencia: 'move_sequence',
+  moversequencia: 'move_sequence',
+  sequencia_movimento: 'move_sequence',
+  sequence_move: 'move_sequence',
+  open_app: 'open_app',
+  openapp: 'open_app',
+  abrir_app: 'open_app',
+  abrirapp: 'open_app',
+  close_app: 'close_app',
+  closeapp: 'close_app',
+  fechar_app: 'close_app',
+  fecharapp: 'close_app',
+  key_tap: 'key_tap',
+  keytap: 'key_tap',
+  tap_key: 'key_tap',
+  tapkey: 'key_tap',
+  press_key: 'key_tap',
+  pressionar_tecla: 'key_tap',
+  tecla: 'key_tap',
+  type_string_delayed: 'type_string_delayed',
+  typestringdelayed: 'type_string_delayed',
+  type_string: 'type_string_delayed',
+  typestring: 'type_string_delayed',
+  digitar: 'type_string_delayed',
+  escrever: 'type_string_delayed'
+});
+
+const BUTTON_ALIASES = Object.freeze({
+  pularads: 'pular_ads',
+  pular_ads: 'pular_ads',
+  pular_anuncio: 'pular_ads',
+  pular_anuncios: 'pular_ads',
+  skip_ads: 'pular_ads',
+  skipad: 'pular_ads',
+  search: 'barra_pesquisa',
+  searchbar: 'barra_pesquisa',
+  search_bar: 'barra_pesquisa',
+  barra_pesquisa: 'barra_pesquisa',
+  barrapesquisa: 'barra_pesquisa',
+  fechar: 'fechar',
+  close: 'fechar',
+  close_app: 'fechar'
+});
+
+const APP_ALIASES = Object.freeze({
+  google: 'chrome',
+  google_chrome: 'chrome'
+});
+
+const APP_STATE = Object.freeze({
+  OPEN: 'aberto',
+  CLOSED: 'fechado'
+});
+
+const CLICK_MODE = Object.freeze({
+  NONE: 'none',
+  BETWEEN: 'between',
+  EACH: 'each',
+  FIRST: 'first',
+  LAST: 'last'
+});
+
+let robotCache;
+
 export function cmd(message) {
   if (typeof message !== 'string') {
     return [];
@@ -11,10 +143,21 @@ export function cmd(message) {
     const inside = match[1].trim();
     if (!inside) continue;
 
-    const obj = {
+    const command = {
       type: undefined,
       command: undefined,
       extra: undefined,
+      button: undefined,
+      key: undefined,
+      modifiers: undefined,
+      text: undefined,
+      typeDelay: undefined,
+      points: undefined,
+      path: undefined,
+      interval: undefined,
+      clickDelay: undefined,
+      click: undefined,
+      doubleClick: undefined,
       seq: undefined
     };
 
@@ -24,6 +167,13 @@ export function cmd(message) {
       const part = rawPart.trim();
       if (!part) continue;
 
+      if (part.indexOf(':') === -1) {
+        if (!command.type) {
+          command.type = part;
+        }
+        continue;
+      }
+
       const [rawKey, ...rest] = part.split(':');
       if (!rawKey || rest.length === 0) continue;
 
@@ -32,28 +182,111 @@ export function cmd(message) {
       if (!value) continue;
 
       if (key === 'type' || key === 'tipo') {
-        obj.type = value;
+        command.type = value;
       } else if (key === 'command' || key === 'comando') {
-        obj.command = value;
+        command.command = value;
       } else if (key === 'extra') {
-        obj.extra = value;
+        command.extra = value;
+      } else if (key === 'button' || key === 'botao' || key === 'botão') {
+        command.button = value;
+      } else if (key === 'key' || key === 'tecla' || key === 'hotkey') {
+        command.key = value;
+        if (!command.command) {
+          command.command = value;
+        }
+      } else if (
+        key === 'modifier' ||
+        key === 'modifiers' ||
+        key === 'modificador' ||
+        key === 'modificadores'
+      ) {
+        command.modifiers = value;
+      } else if (
+        key === 'text' ||
+        key === 'texto' ||
+        key === 'string' ||
+        key === 'mensagem'
+      ) {
+        command.text = value;
+        if (!command.command) {
+          command.command = value;
+        }
+      } else if (
+        key === 'typedelay' ||
+        key === 'type_delay' ||
+        key === 'typingdelay' ||
+        key === 'typing_delay' ||
+        key === 'textdelay' ||
+        key === 'delaytexto' ||
+        key === 'delaydigitacao' ||
+        key === 'delaydigitar'
+      ) {
+        const typeDelay = toNonNegativeInteger(value);
+        if (typeDelay !== null) {
+          command.typeDelay = typeDelay;
+        }
+      } else if (
+        key === 'points' ||
+        key === 'pontos' ||
+        key === 'path' ||
+        key === 'trajeto' ||
+        key === 'caminho' ||
+        key === 'coords' ||
+        key === 'coordenadas'
+      ) {
+        command.points = value;
+        command.path = value;
+        if (!command.command) {
+          command.command = value;
+        }
+      } else if (key === 'interval' || key === 'intervalo') {
+        const interval = toNonNegativeInteger(value);
+        if (interval !== null) {
+          command.interval = interval;
+        }
+      } else if (
+        key === 'clickdelay' ||
+        key === 'delayclick' ||
+        key === 'delay_clique' ||
+        key === 'delayclique' ||
+        key === 'click_delay' ||
+        key === 'delay'
+      ) {
+        const clickDelay = toNonNegativeInteger(value);
+        if (clickDelay !== null) {
+          command.clickDelay = clickDelay;
+        }
+      } else if (key === 'click' || key === 'clique') {
+        command.click = value;
+      } else if (
+        key === 'doubleclick' ||
+        key === 'double_click' ||
+        key === 'double' ||
+        key === 'duplo' ||
+        key === 'cliqueduplo' ||
+        key === 'clique_duplo'
+      ) {
+        const doubleClick = parseBooleanValue(value);
+        if (doubleClick !== null) {
+          command.doubleClick = doubleClick;
+        }
       } else if (key === 'seq') {
-        const seq = Number(value);
-        if (Number.isInteger(seq) && seq >= 0) {
-          obj.seq = seq;
+        const seq = toNonNegativeInteger(value);
+        if (seq !== null) {
+          command.seq = seq;
         }
-      } else if (!obj.type) {
-        obj.type = rawKey.trim();
-        obj.command = value;
-      } else if (!obj.command) {
-        obj.command = value;
-      } else if (!obj.extra) {
-        obj.extra = value;
+      } else if (!command.type) {
+        command.type = rawKey.trim();
+        command.command = value;
+      } else if (!command.command) {
+        command.command = value;
+      } else if (!command.extra) {
+        command.extra = value;
       }
     }
 
-    if (obj.type && obj.command) {
-      results.push(obj);
+    if (hasCommandPayload(command)) {
+      results.push(command);
     }
   }
 
@@ -64,3 +297,1919 @@ export function extractFirstCommand(message) {
   const [first] = cmd(message);
   return first || null;
 }
+
+export async function initMap(options = {}) {
+  const config = buildCursorConfig(options);
+  const mapAlreadyExists = await pathExists(config.mapPath);
+  const store = await createMapStore(config);
+
+  const persistMerged =
+    parseBooleanValue(options && options.persistMerged) === true ||
+    parseBooleanValue(options && options.writeMerged) === true;
+
+  if (!mapAlreadyExists && config.persistMap) {
+    // already persisted by createMapStore when file is missing
+  } else if (persistMerged && config.persistMap) {
+    await persistMapStore(store);
+  }
+
+  return {
+    path: store.path,
+    created: !mapAlreadyExists,
+    persisted: (!mapAlreadyExists || persistMerged) && config.persistMap,
+    version: store.map.version,
+    appCount: Object.keys(store.map.apps || {}).length,
+    map: store.map
+  };
+}
+
+export async function initDoc(options = {}) {
+  const raw = options && typeof options === 'object' ? options : {};
+  const outputDir = resolveDocOutputDir(raw);
+  const overwrite = parseBooleanValue(raw.overwrite) === true;
+  const includeMapDocs = shouldIncludeMapDocs(raw.includeMapDocs);
+  const templates = resolveDocTemplates(raw.files, includeMapDocs);
+
+  await mkdir(outputDir, { recursive: true });
+
+  const created = [];
+  const updated = [];
+  const skipped = [];
+
+  for (const template of templates) {
+    const sourcePath = resolvePath(MODULE_DIR, template.source);
+    const targetPath = resolvePath(outputDir, template.target);
+    const targetExists = await pathExists(targetPath);
+
+    if (targetExists && !overwrite) {
+      skipped.push({
+        key: template.key,
+        path: targetPath,
+        reason: 'exists'
+      });
+      continue;
+    }
+
+    let content;
+    try {
+      content = await readFile(sourcePath, 'utf8');
+    } catch (error) {
+      if (error && error.code === 'ENOENT') {
+        throw new Error(`doc_template_not_found:${template.source}`);
+      }
+      throw error;
+    }
+
+    await writeFile(targetPath, content, 'utf8');
+
+    if (targetExists) {
+      updated.push({ key: template.key, path: targetPath });
+    } else {
+      created.push({ key: template.key, path: targetPath });
+    }
+  }
+
+  return {
+    outputDir,
+    overwrite,
+    created,
+    updated,
+    skipped
+  };
+}
+
+export async function cursor(input, options = {}) {
+  const commands = normalizeCursorInput(input);
+  if (commands.length === 0) {
+    return {
+      executed: [],
+      skipped: [{ reason: 'no_commands' }],
+      totalCommands: 0,
+      totalExecutions: 0
+    };
+  }
+
+  const runtime = createCursorRuntime(options);
+  let actions;
+  const executed = [];
+  const skipped = [];
+
+  async function getActions() {
+    if (actions) {
+      return actions;
+    }
+    const robot = await getRobot();
+    actions = createActionHandlers(robot, runtime);
+    return actions;
+  }
+
+  for (let commandIndex = 0; commandIndex < commands.length; commandIndex++) {
+    const command = commands[commandIndex];
+    const actionKey = resolveActionKey(command.type);
+
+    if (!actionKey) {
+      skipped.push({
+        commandIndex,
+        type: command.type,
+        command: command.command,
+        reason: 'unknown_type'
+      });
+      continue;
+    }
+
+    const repeatCount = getRepeatCount(command.seq);
+    if (repeatCount === 0) {
+      skipped.push({
+        commandIndex,
+        type: command.type,
+        command: command.command,
+        reason: 'seq_zero'
+      });
+      continue;
+    }
+
+    if (isMapAwareAction(actionKey)) {
+      try {
+        await runtime.getMapStore();
+      } catch (error) {
+        skipped.push({
+          commandIndex,
+          type: command.type,
+          command: command.command,
+          reason: 'map_unavailable',
+          detail: error instanceof Error ? error.message : String(error)
+        });
+        continue;
+      }
+    }
+
+    let action;
+    try {
+      const actionHandlers = await getActions();
+      action = actionHandlers[actionKey];
+    } catch (error) {
+      skipped.push({
+        commandIndex,
+        type: command.type,
+        command: command.command,
+        reason: 'robot_unavailable',
+        detail: error instanceof Error ? error.message : String(error)
+      });
+      continue;
+    }
+
+    if (!action) {
+      skipped.push({
+        commandIndex,
+        type: command.type,
+        command: command.command,
+        reason: 'unknown_type'
+      });
+      continue;
+    }
+
+    for (let iteration = 1; iteration <= repeatCount; iteration++) {
+      try {
+        await action(command);
+        executed.push({
+          commandIndex,
+          iteration,
+          type: command.type,
+          command: command.command,
+          extra: command.extra,
+          button: command.button,
+          key: command.key,
+          modifiers: command.modifiers,
+          text: command.text,
+          typeDelay: command.typeDelay,
+          points: command.points,
+          path: command.path,
+          interval: command.interval,
+          clickDelay: command.clickDelay,
+          click: command.click,
+          doubleClick: command.doubleClick,
+          seq: command.seq
+        });
+      } catch (error) {
+        skipped.push({
+          commandIndex,
+          iteration,
+          type: command.type,
+          command: command.command,
+          reason: 'action_error',
+          detail: error instanceof Error ? error.message : String(error)
+        });
+        break;
+      }
+    }
+  }
+
+  return {
+    executed,
+    skipped,
+    totalCommands: commands.length,
+    totalExecutions: executed.length
+  };
+}
+
+function createCursorRuntime(options) {
+  const config = buildCursorConfig(options);
+  let mapStorePromise;
+
+  return {
+    config,
+    async getMapStore() {
+      if (mapStorePromise) {
+        return mapStorePromise;
+      }
+      mapStorePromise = createMapStore(config);
+      return mapStorePromise;
+    }
+  };
+}
+
+function buildCursorConfig(options) {
+  const raw = options && typeof options === 'object' ? options : {};
+  const mapPath =
+    typeof raw.mapPath === 'string' && raw.mapPath.trim()
+      ? raw.mapPath.trim()
+      : 'map.json';
+
+  return {
+    mapPath: resolvePath(mapPath),
+    persistMap: raw.persistMap !== false,
+    createMapIfMissing: raw.createMapIfMissing !== false,
+    apps: mergeOptionApps(raw.apps),
+    launchKey:
+      raw.launchKey === false || raw.launchKey === null
+        ? undefined
+        : typeof raw.launchKey === 'string' && raw.launchKey.trim()
+          ? raw.launchKey.trim()
+          : 'command',
+    typeDelay: parseIntegerOption(raw.typeDelay, 50, 0),
+    moveSteps: parseIntegerOption(raw.moveSteps, 50, 1),
+    moveDelay: parseIntegerOption(raw.moveDelay, 8, 0),
+    scrollSteps: parseIntegerOption(raw.scrollSteps, 10, 1),
+    scrollDelay: parseIntegerOption(raw.scrollDelay, 20, 0),
+    sequenceInterval: parseIntegerOption(raw.sequenceInterval, 250, 0),
+    sequenceClickMode: normalizeClickMode(raw.sequenceClick, CLICK_MODE.NONE),
+    sequenceDoubleClick:
+      parseBooleanValue(raw.sequenceDoubleClick) === true,
+    defaultClosePoint: parsePoint(raw.defaultClosePoint) || { x: 1888, y: 16 },
+    skipAdsPoint: parsePoint(raw.skipAdsPoint) || { x: 808, y: 569 }
+  };
+}
+
+function mergeOptionApps(customApps) {
+  const merged = {};
+
+  for (const [appName, appConfig] of Object.entries(DEFAULT_APPS)) {
+    merged[appName] = cloneAppMap(appConfig);
+  }
+
+  if (!customApps || typeof customApps !== 'object') {
+    return merged;
+  }
+
+  for (const [rawName, rawConfig] of Object.entries(customApps)) {
+    const appName = resolveAppName(rawName);
+    const normalized = normalizeAppConfig(rawConfig);
+    if (!normalized) continue;
+
+    const current = merged[appName] || {
+      launcher: undefined,
+      searchIcon: undefined,
+      state: APP_STATE.CLOSED,
+      buttons: {}
+    };
+
+    merged[appName] = {
+      launcher: normalized.launcher || current.launcher,
+      searchIcon: normalized.searchIcon || current.searchIcon,
+      state: normalized.state || current.state || APP_STATE.CLOSED,
+      buttons: {
+        ...(current.buttons || {}),
+        ...(normalized.buttons || {})
+      }
+    };
+  }
+
+  return merged;
+}
+
+function toCommandText(value) {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed || '';
+  }
+
+  if (Number.isFinite(value)) {
+    return String(value);
+  }
+
+  return '';
+}
+
+function hasCommandPayload(command) {
+  if (!command || !command.type) {
+    return false;
+  }
+
+  const actionKey = resolveActionKey(command.type);
+
+  if (actionKey === 'key_tap') {
+    return Boolean(toCommandText(command.key) || toCommandText(command.command));
+  }
+
+  if (actionKey === 'type_string_delayed') {
+    return Boolean(
+      toCommandText(command.text) ||
+        toCommandText(command.command) ||
+        toCommandText(command.extra)
+    );
+  }
+
+  if (actionKey === 'move_sequence') {
+    return Boolean(command.points || command.path || toCommandText(command.command));
+  }
+
+  return Boolean(toCommandText(command.command));
+}
+
+function normalizeCommandObject(value) {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+
+  const rawType = value.type !== undefined ? value.type : value.tipo;
+  const rawCommand = value.command !== undefined ? value.command : value.comando;
+  const rawKey =
+    value.key !== undefined
+      ? value.key
+      : value.tecla !== undefined
+        ? value.tecla
+        : value.hotkey;
+  const rawModifiers =
+    value.modifiers !== undefined
+      ? value.modifiers
+      : value.modifier !== undefined
+        ? value.modifier
+        : value.modificadores !== undefined
+          ? value.modificadores
+          : value.modificador;
+  const rawText =
+    value.text !== undefined
+      ? value.text
+      : value.texto !== undefined
+        ? value.texto
+        : value.string !== undefined
+          ? value.string
+          : value.mensagem;
+  const rawButton =
+    value.button !== undefined
+      ? value.button
+      : value.botao !== undefined
+        ? value.botao
+        : value['botão'];
+  const rawPoints =
+    value.points !== undefined
+      ? value.points
+      : value.pontos !== undefined
+        ? value.pontos
+        : value.path !== undefined
+          ? value.path
+          : value.trajeto !== undefined
+            ? value.trajeto
+            : value.caminho !== undefined
+              ? value.caminho
+              : value.coords !== undefined
+                ? value.coords
+                : value.coordenadas;
+  const rawPath =
+    value.path !== undefined
+      ? value.path
+      : value.caminho !== undefined
+        ? value.caminho
+        : value.trajeto;
+  const rawInterval =
+    value.interval !== undefined ? value.interval : value.intervalo;
+  const rawClickDelay =
+    value.clickDelay !== undefined
+      ? value.clickDelay
+      : value.delayClick !== undefined
+        ? value.delayClick
+        : value.delayClique !== undefined
+          ? value.delayClique
+          : value.delay;
+  const rawClick = value.click !== undefined ? value.click : value.clique;
+  const rawDoubleClick =
+    value.doubleClick !== undefined
+      ? value.doubleClick
+      : value.double_click !== undefined
+        ? value.double_click
+        : value.duplo !== undefined
+          ? value.duplo
+          : value.cliqueDuplo !== undefined
+            ? value.cliqueDuplo
+            : value.clique_duplo;
+  const rawTypeDelay =
+    value.typeDelay !== undefined
+      ? value.typeDelay
+      : value.type_delay !== undefined
+        ? value.type_delay
+        : value.typingDelay !== undefined
+          ? value.typingDelay
+          : value.typing_delay !== undefined
+            ? value.typing_delay
+            : value.textDelay !== undefined
+              ? value.textDelay
+              : value.delayTexto !== undefined
+                ? value.delayTexto
+                : value.delayDigitacao !== undefined
+                  ? value.delayDigitacao
+                  : value.delayDigitar;
+
+  const type =
+    typeof rawType === 'string' ? rawType.trim() : String(rawType || '').trim();
+  const actionKey = resolveActionKey(type);
+
+  const normalizedPoints = normalizePointsValue(
+    rawPoints !== undefined ? rawPoints : rawPath
+  );
+
+  const key = toCommandText(rawKey);
+  const text = toCommandText(rawText);
+
+  let command = toCommandText(rawCommand);
+
+  if (!command && normalizedPoints) {
+    command = serializePoints(normalizedPoints);
+  }
+
+  if (!command && text) {
+    command = text;
+  }
+
+  if (!command && key) {
+    command = key;
+  }
+
+  const extra =
+    value.extra === undefined || value.extra === null
+      ? undefined
+      : toCommandText(value.extra) || String(value.extra);
+
+  if (!command && actionKey === 'type_string_delayed' && extra) {
+    command = extra;
+  }
+
+  const normalized = {
+    type,
+    command,
+    extra,
+    button: undefined,
+    key: undefined,
+    modifiers: undefined,
+    text: undefined,
+    typeDelay: undefined,
+    points: undefined,
+    path: undefined,
+    interval: undefined,
+    clickDelay: undefined,
+    click: undefined,
+    doubleClick: undefined,
+    seq: undefined
+  };
+
+  if (rawButton !== undefined && rawButton !== null) {
+    const buttonText = String(rawButton).trim();
+    if (buttonText) {
+      normalized.button = buttonText;
+    }
+  }
+
+  if (key) {
+    normalized.key = key;
+  }
+
+  const modifiers = parseKeyModifiers(rawModifiers);
+  if (modifiers && modifiers.length > 0) {
+    normalized.modifiers = modifiers;
+  }
+
+  if (text) {
+    normalized.text = text;
+  }
+
+  const typeDelay = toNonNegativeInteger(rawTypeDelay);
+  if (typeDelay !== null) {
+    normalized.typeDelay = typeDelay;
+  }
+
+  if (normalizedPoints) {
+    normalized.points = normalizedPoints;
+    normalized.path = normalizedPoints;
+  }
+
+  const interval = toNonNegativeInteger(rawInterval);
+  if (interval !== null) {
+    normalized.interval = interval;
+  }
+
+  const clickDelay = toNonNegativeInteger(rawClickDelay);
+  if (clickDelay !== null) {
+    normalized.clickDelay = clickDelay;
+  }
+
+  if (rawClick !== undefined && rawClick !== null) {
+    const clickMode = String(rawClick).trim();
+    if (clickMode) {
+      normalized.click = clickMode;
+    }
+  }
+
+  const doubleClick = parseBooleanValue(rawDoubleClick);
+  if (doubleClick !== null) {
+    normalized.doubleClick = doubleClick;
+  }
+
+  const rawSeq = value.seq !== undefined ? value.seq : value.sequencia;
+  const seq = toNonNegativeInteger(rawSeq);
+  if (seq !== null) {
+    normalized.seq = seq;
+  }
+
+  return hasCommandPayload(normalized) ? normalized : null;
+}
+
+function normalizeCursorInput(input) {
+  if (typeof input === 'string') {
+    return cmd(input);
+  }
+
+  if (Array.isArray(input)) {
+    return input.map(normalizeCommandObject).filter(Boolean);
+  }
+
+  const single = normalizeCommandObject(input);
+  return single ? [single] : [];
+}
+
+function getRepeatCount(seq) {
+  const parsed = toNonNegativeInteger(seq);
+  if (parsed === null) {
+    return 1;
+  }
+  return parsed;
+}
+
+function toNonNegativeInteger(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return null;
+  }
+  return parsed;
+}
+
+function parseIntegerOption(value, fallback, min) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function parseBooleanValue(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  const token = canonicalToken(value);
+  if (
+    token === 'true' ||
+    token === '1' ||
+    token === 'sim' ||
+    token === 'yes' ||
+    token === 'on'
+  ) {
+    return true;
+  }
+
+  if (
+    token === 'false' ||
+    token === '0' ||
+    token === 'nao' ||
+    token === 'no' ||
+    token === 'off'
+  ) {
+    return false;
+  }
+
+  return null;
+}
+
+function normalizeClickMode(value, fallback) {
+  if (value === true) {
+    return CLICK_MODE.BETWEEN;
+  }
+
+  if (value === false) {
+    return CLICK_MODE.NONE;
+  }
+
+  const token = canonicalToken(value);
+
+  if (
+    token === CLICK_MODE.EACH ||
+    token === 'cada' ||
+    token === 'todos' ||
+    token === 'todas'
+  ) {
+    return CLICK_MODE.EACH;
+  }
+
+  if (token === CLICK_MODE.BETWEEN || token === 'entre') {
+    return CLICK_MODE.BETWEEN;
+  }
+
+  if (token === CLICK_MODE.FIRST || token === 'primeiro') {
+    return CLICK_MODE.FIRST;
+  }
+
+  if (token === CLICK_MODE.LAST || token === 'ultimo' || token === 'final') {
+    return CLICK_MODE.LAST;
+  }
+
+  if (
+    token === CLICK_MODE.NONE ||
+    token === 'sem' ||
+    token === 'nenhum' ||
+    token === 'desligado'
+  ) {
+    return CLICK_MODE.NONE;
+  }
+
+  return fallback || CLICK_MODE.NONE;
+}
+
+function parsePointToken(token) {
+  const value = String(token || '').trim();
+  if (!value) return null;
+
+  const match = value.match(/^(-?\d+)\s*(?:x|:|,)\s*(-?\d+)$/i);
+  if (!match) return null;
+
+  return {
+    x: Number(match[1]),
+    y: Number(match[2])
+  };
+}
+
+function normalizePointsValue(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  if (Array.isArray(value)) {
+    const points = [];
+    for (const item of value) {
+      const point = parsePoint(item) || parsePointToken(item);
+      if (!point) {
+        return undefined;
+      }
+      points.push(point);
+    }
+    return points.length > 0 ? points : undefined;
+  }
+
+  if (typeof value === 'string') {
+    const parts = value
+      .split(/[|;>]/g)
+      .map((part) => part.trim())
+      .filter(Boolean);
+
+    if (parts.length === 0) {
+      return undefined;
+    }
+
+    const points = [];
+    for (const part of parts) {
+      const point = parsePointToken(part);
+      if (!point) {
+        return undefined;
+      }
+      points.push(point);
+    }
+    return points.length > 0 ? points : undefined;
+  }
+
+  const singlePoint = parsePoint(value);
+  if (singlePoint) {
+    return [singlePoint];
+  }
+
+  return undefined;
+}
+
+function serializePoints(points) {
+  if (!Array.isArray(points) || points.length === 0) {
+    return '';
+  }
+
+  return points.map((point) => `${point.x}x${point.y}`).join('|');
+}
+
+function normalizePathConfig(rawPath) {
+  if (rawPath === undefined || rawPath === null) {
+    return undefined;
+  }
+
+  let points;
+  let clickMode = CLICK_MODE.NONE;
+  let interval = 0;
+  let clickDelay = 0;
+  let doubleClick = false;
+
+  if (typeof rawPath === 'string' || Array.isArray(rawPath)) {
+    points = normalizePointsValue(rawPath);
+  } else if (typeof rawPath === 'object') {
+    points = normalizePointsValue(
+      rawPath.points !== undefined
+        ? rawPath.points
+        : rawPath.pontos !== undefined
+          ? rawPath.pontos
+          : rawPath.path !== undefined
+            ? rawPath.path
+            : rawPath.caminho !== undefined
+              ? rawPath.caminho
+              : rawPath.coords !== undefined
+                ? rawPath.coords
+                : rawPath.coordenadas
+    );
+
+    clickMode = normalizeClickMode(
+      rawPath.click !== undefined ? rawPath.click : rawPath.clique,
+      CLICK_MODE.NONE
+    );
+
+    interval =
+      toNonNegativeInteger(
+        rawPath.interval !== undefined ? rawPath.interval : rawPath.intervalo
+      ) || 0;
+
+    clickDelay =
+      toNonNegativeInteger(
+        rawPath.clickDelay !== undefined
+          ? rawPath.clickDelay
+          : rawPath.delayClick !== undefined
+            ? rawPath.delayClick
+            : rawPath.delayClique !== undefined
+              ? rawPath.delayClique
+              : rawPath.delay
+      ) || 0;
+
+    doubleClick =
+      parseBooleanValue(
+        rawPath.doubleClick !== undefined
+          ? rawPath.doubleClick
+          : rawPath.double_click !== undefined
+            ? rawPath.double_click
+            : rawPath.duplo
+      ) === true;
+  } else {
+    return undefined;
+  }
+
+  if (!points || points.length === 0) {
+    return undefined;
+  }
+
+  return {
+    points,
+    clickMode,
+    interval,
+    clickDelay,
+    doubleClick
+  };
+}
+
+function normalizeTargetConfig(rawTarget) {
+  if (rawTarget === undefined || rawTarget === null) {
+    return undefined;
+  }
+
+  if (typeof rawTarget !== 'object') {
+    const directPoint = parsePoint(rawTarget);
+    return directPoint ? { position: directPoint } : undefined;
+  }
+
+  let position =
+    parsePoint(
+      rawTarget.position !== undefined
+        ? rawTarget.position
+        : rawTarget.posicao !== undefined
+          ? rawTarget.posicao
+          : rawTarget.destino !== undefined
+            ? rawTarget.destino
+            : rawTarget.target !== undefined
+              ? rawTarget.target
+              : rawTarget
+    ) || undefined;
+
+  const pathConfig = normalizePathConfig(
+    rawTarget.caminho !== undefined ? rawTarget.caminho : rawTarget.path
+  );
+
+  if (!position && pathConfig && pathConfig.points.length > 0) {
+    const lastPoint = pathConfig.points[pathConfig.points.length - 1];
+    position = { x: lastPoint.x, y: lastPoint.y };
+  }
+
+  if (!position) {
+    return undefined;
+  }
+
+  return {
+    position,
+    ...(pathConfig ? { path: pathConfig } : {})
+  };
+}
+
+function shouldClickOnStep(mode, index, totalPoints) {
+  if (mode === CLICK_MODE.EACH) {
+    return true;
+  }
+
+  if (mode === CLICK_MODE.BETWEEN) {
+    return index < totalPoints - 1;
+  }
+
+  if (mode === CLICK_MODE.FIRST) {
+    return index === 0;
+  }
+
+  if (mode === CLICK_MODE.LAST) {
+    return index === totalPoints - 1;
+  }
+
+  return false;
+}
+
+function removeDiacritics(value) {
+  return String(value || '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '');
+}
+
+function canonicalToken(value) {
+  return removeDiacritics(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_\-\s]/g, '')
+    .replace(/[-\s]+/g, '_');
+}
+
+function normalizeKeyTapToken(value) {
+  const token = canonicalToken(value);
+  if (!token) {
+    return undefined;
+  }
+
+  if (
+    token === 'cmd' ||
+    token === 'command' ||
+    token === 'meta' ||
+    token === 'super' ||
+    token === 'win' ||
+    token === 'windows'
+  ) {
+    return 'command';
+  }
+
+  if (token === 'ctrl' || token === 'control' || token === 'ctl') {
+    return 'control';
+  }
+
+  if (token === 'option' || token === 'opt') {
+    return 'alt';
+  }
+
+  if (token === 'spacebar') {
+    return 'space';
+  }
+
+  return token;
+}
+
+function parseKeyModifiers(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  const list = Array.isArray(value) ? value : [value];
+  const modifiers = [];
+
+  for (const item of list) {
+    if (item === undefined || item === null) {
+      continue;
+    }
+
+    const chunks =
+      typeof item === 'string'
+        ? item.split(/[+|,\s]+/g)
+        : [String(item)];
+
+    for (const chunk of chunks) {
+      const modifier = normalizeKeyTapToken(chunk);
+      if (!modifier) continue;
+      modifiers.push(modifier);
+    }
+  }
+
+  if (modifiers.length === 0) {
+    return undefined;
+  }
+
+  return Array.from(new Set(modifiers));
+}
+
+function resolveActionKey(type) {
+  const key = canonicalToken(type);
+  return ACTION_ALIASES[key];
+}
+
+function isMapAwareAction(actionKey) {
+  return (
+    actionKey === 'open_app' ||
+    actionKey === 'close_app' ||
+    actionKey === 'skip_ads'
+  );
+}
+
+function resolveAppName(name) {
+  const key = canonicalToken(name);
+  return APP_ALIASES[key] || key;
+}
+
+function resolveButtonKey(name) {
+  const key = canonicalToken(name);
+  return BUTTON_ALIASES[key] || key;
+}
+
+function normalizeState(value) {
+  const key = canonicalToken(value);
+  if (key === 'aberto' || key === 'open' || key === 'opened') {
+    return APP_STATE.OPEN;
+  }
+  if (key === 'fechado' || key === 'closed') {
+    return APP_STATE.CLOSED;
+  }
+  return undefined;
+}
+
+function parsePoint(value) {
+  if (Array.isArray(value) && value.length === 2) {
+    const x = Number(value[0]);
+    const y = Number(value[1]);
+    if (Number.isFinite(x) && Number.isFinite(y)) {
+      return { x, y };
+    }
+  }
+
+  if (value && typeof value === 'object') {
+    const x = Number(value.x);
+    const y = Number(value.y);
+    if (Number.isFinite(x) && Number.isFinite(y)) {
+      return { x, y };
+    }
+  }
+
+  return null;
+}
+
+function clonePoint(value) {
+  if (!value) return undefined;
+  return { x: value.x, y: value.y };
+}
+
+function clonePathConfig(pathConfig) {
+  if (!pathConfig || typeof pathConfig !== 'object') {
+    return undefined;
+  }
+
+  return {
+    points: (pathConfig.points || []).map((point) => clonePoint(point)),
+    clickMode: pathConfig.clickMode || CLICK_MODE.NONE,
+    interval: toNonNegativeInteger(pathConfig.interval) || 0,
+    clickDelay: toNonNegativeInteger(pathConfig.clickDelay) || 0,
+    doubleClick: pathConfig.doubleClick === true
+  };
+}
+
+function cloneTargetConfig(targetConfig) {
+  if (!targetConfig || typeof targetConfig !== 'object') {
+    return undefined;
+  }
+
+  const position = targetConfig.position
+    ? clonePoint(targetConfig.position)
+    : clonePoint(parsePoint(targetConfig));
+
+  if (!position) {
+    return undefined;
+  }
+
+  return {
+    position,
+    ...(targetConfig.path ? { path: clonePathConfig(targetConfig.path) } : {})
+  };
+}
+
+function cloneButtonMap(buttons) {
+  const cloned = {};
+  if (!buttons || typeof buttons !== 'object') {
+    return cloned;
+  }
+
+  for (const [buttonName, buttonConfig] of Object.entries(buttons)) {
+    if (!buttonConfig || typeof buttonConfig !== 'object') continue;
+    if (!buttonConfig.position) continue;
+    cloned[buttonName] = {
+      position: clonePoint(buttonConfig.position),
+      ...(buttonConfig.path ? { path: clonePathConfig(buttonConfig.path) } : {}),
+      ...(buttonConfig.setState ? { setState: buttonConfig.setState } : {})
+    };
+  }
+
+  return cloned;
+}
+
+function cloneAppMap(app) {
+  return {
+    launcher: cloneTargetConfig(app.launcher),
+    searchIcon: cloneTargetConfig(app.searchIcon),
+    state: app.state || APP_STATE.CLOSED,
+    buttons: cloneButtonMap(app.buttons)
+  };
+}
+
+async function pathExists(filePath) {
+  try {
+    await readFile(filePath, 'utf8');
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function shouldIncludeMapDocs(value) {
+  const parsed = parseBooleanValue(value);
+  if (parsed === null) {
+    return value !== false;
+  }
+  return parsed;
+}
+
+function resolveDocTemplateByName(value) {
+  const token = canonicalToken(value);
+  if (!token) {
+    return null;
+  }
+
+  if (
+    token === 'doc' ||
+    token === 'doc_en' ||
+    token === 'docmd' ||
+    token === 'en' ||
+    token === 'english'
+  ) {
+    return DOC_TEMPLATE_MAP.doc_en;
+  }
+
+  if (
+    token === 'doc_ptbr' ||
+    token === 'docptbr' ||
+    token === 'ptbr' ||
+    token === 'pt_br' ||
+    token === 'pt'
+  ) {
+    return DOC_TEMPLATE_MAP.doc_ptbr;
+  }
+
+  if (
+    token === 'map' ||
+    token === 'map_en' ||
+    token === 'mapmd' ||
+    token === 'map_doc' ||
+    token === 'mapdoc'
+  ) {
+    return DOC_TEMPLATE_MAP.map_en;
+  }
+
+  if (
+    token === 'map_ptbr' ||
+    token === 'mapptbr' ||
+    token === 'map_pt' ||
+    token === 'map_ptbr_md'
+  ) {
+    return DOC_TEMPLATE_MAP.map_ptbr;
+  }
+
+  return null;
+}
+
+function resolveDocTemplates(filesOption, includeMapDocs) {
+  const defaultTemplates = includeMapDocs
+    ? DOC_TEMPLATES
+    : DOC_TEMPLATES.filter((template) => !template.isMapDoc);
+
+  if (filesOption === undefined || filesOption === null) {
+    return defaultTemplates;
+  }
+
+  const values = Array.isArray(filesOption) ? filesOption : [filesOption];
+  const selected = [];
+  const invalid = [];
+
+  for (const value of values) {
+    const template = resolveDocTemplateByName(value);
+    if (!template) {
+      invalid.push(String(value));
+      continue;
+    }
+    if (!includeMapDocs && template.isMapDoc) {
+      continue;
+    }
+    if (!selected.find((item) => item.key === template.key)) {
+      selected.push(template);
+    }
+  }
+
+  if (selected.length === 0 && invalid.length > 0) {
+    throw new Error(`invalid_doc_templates:${invalid.join('|')}`);
+  }
+
+  return selected.length > 0 ? selected : defaultTemplates;
+}
+
+function resolveDocOutputDir(options) {
+  const rawOutput =
+    options.outputDir !== undefined
+      ? options.outputDir
+      : options.dir !== undefined
+        ? options.dir
+        : options.path;
+
+  const output = typeof rawOutput === 'string' ? rawOutput.trim() : '';
+  if (!output) {
+    return resolvePath(process.cwd());
+  }
+
+  return resolvePath(output);
+}
+
+function normalizeButtonConfig(rawConfig) {
+  if (rawConfig === undefined || rawConfig === null) {
+    return null;
+  }
+
+  const target = normalizeTargetConfig(rawConfig);
+  if (!target) {
+    return null;
+  }
+
+  const rawState =
+    rawConfig && typeof rawConfig === 'object'
+      ? rawConfig.setState !== undefined
+        ? rawConfig.setState
+        : rawConfig.stateAfter !== undefined
+          ? rawConfig.stateAfter
+          : rawConfig.estadoDepois !== undefined
+            ? rawConfig.estadoDepois
+            : undefined
+      : undefined;
+
+  const state = normalizeState(rawState);
+
+  return {
+    position: target.position,
+    ...(target.path ? { path: target.path } : {}),
+    ...(state ? { setState: state } : {})
+  };
+}
+
+function mergeTargetPath(target, rawPath) {
+  if (!target || target.path) {
+    return target;
+  }
+
+  const pathConfig = normalizePathConfig(rawPath);
+  if (!pathConfig) {
+    return target;
+  }
+
+  return {
+    ...target,
+    path: pathConfig
+  };
+}
+
+function normalizeButtons(rawButtons) {
+  const buttons = {};
+  if (!rawButtons || typeof rawButtons !== 'object') {
+    return buttons;
+  }
+
+  for (const [rawName, rawConfig] of Object.entries(rawButtons)) {
+    const button = normalizeButtonConfig(rawConfig);
+    if (!button) continue;
+
+    const buttonName = resolveButtonKey(rawName);
+    buttons[buttonName] = button;
+  }
+
+  return buttons;
+}
+
+function normalizeAppConfig(rawConfig) {
+  if (!rawConfig || typeof rawConfig !== 'object') {
+    return null;
+  }
+
+  const rawLauncher =
+    rawConfig.launcher !== undefined
+      ? rawConfig.launcher
+      : rawConfig.position !== undefined
+        ? rawConfig.position
+        : rawConfig.posicao;
+
+  let launcher = normalizeTargetConfig(rawLauncher);
+  launcher = mergeTargetPath(
+    launcher,
+    rawConfig.caminho !== undefined ? rawConfig.caminho : rawConfig.path
+  );
+
+  const rawSearchIcon =
+    rawConfig.searchIcon !== undefined
+      ? rawConfig.searchIcon
+      : rawConfig.lupa !== undefined
+        ? rawConfig.lupa
+        : rawConfig.search;
+
+  const searchIcon = normalizeTargetConfig(rawSearchIcon);
+
+  const state = normalizeState(
+    rawConfig.state !== undefined ? rawConfig.state : rawConfig.estado
+  );
+
+  const buttons = normalizeButtons(
+    rawConfig.buttons !== undefined ? rawConfig.buttons : rawConfig.botoes
+  );
+
+  return {
+    ...(launcher ? { launcher } : {}),
+    ...(searchIcon ? { searchIcon } : {}),
+    ...(state ? { state } : {}),
+    buttons
+  };
+}
+
+function buildFallbackMap(config) {
+  const apps = {};
+
+  for (const [appName, appConfig] of Object.entries(config.apps)) {
+    const normalizedApp = cloneAppMap({
+      ...appConfig,
+      state: appConfig.state || APP_STATE.CLOSED
+    });
+    const buttons = normalizedApp.buttons || {};
+    if (!buttons.fechar) {
+      buttons.fechar = {
+        position: clonePoint(config.defaultClosePoint),
+        setState: APP_STATE.CLOSED
+      };
+    }
+    normalizedApp.buttons = buttons;
+    apps[appName] = normalizedApp;
+  }
+
+  if (apps.youtube) {
+    const buttons = apps.youtube.buttons || {};
+    if (!buttons.pular_ads) {
+      buttons.pular_ads = {
+        position: clonePoint(config.skipAdsPoint)
+      };
+    }
+    apps.youtube.buttons = buttons;
+  }
+
+  return {
+    version: 1,
+    apps
+  };
+}
+
+function normalizeMapObject(rawMap) {
+  const result = {
+    version: 1,
+    apps: {}
+  };
+
+  if (!rawMap || typeof rawMap !== 'object') {
+    return result;
+  }
+
+  if (Number.isFinite(rawMap.version)) {
+    result.version = Number(rawMap.version);
+  }
+
+  const rawApps =
+    rawMap.apps !== undefined
+      ? rawMap.apps
+      : rawMap.aplicativos !== undefined
+        ? rawMap.aplicativos
+        : undefined;
+
+  if (!rawApps || typeof rawApps !== 'object') {
+    return result;
+  }
+
+  for (const [rawAppName, rawAppConfig] of Object.entries(rawApps)) {
+    const appName = resolveAppName(rawAppName);
+    const appConfig = normalizeAppConfig(rawAppConfig);
+    if (!appConfig) continue;
+
+    result.apps[appName] = {
+      launcher: appConfig.launcher,
+      searchIcon: appConfig.searchIcon,
+      state: appConfig.state || APP_STATE.CLOSED,
+      buttons: appConfig.buttons || {}
+    };
+  }
+
+  return result;
+}
+
+function mergeMaps(baseMap, overrideMap) {
+  const merged = {
+    version:
+      overrideMap && Number.isFinite(overrideMap.version)
+        ? overrideMap.version
+        : baseMap.version,
+    apps: {}
+  };
+
+  for (const [appName, appConfig] of Object.entries(baseMap.apps || {})) {
+    merged.apps[appName] = cloneAppMap(appConfig);
+  }
+
+  for (const [appName, appConfig] of Object.entries(overrideMap.apps || {})) {
+    const current = merged.apps[appName] || {
+      launcher: undefined,
+      searchIcon: undefined,
+      state: APP_STATE.CLOSED,
+      buttons: {}
+    };
+
+    merged.apps[appName] = {
+      launcher: appConfig.launcher || current.launcher,
+      searchIcon: appConfig.searchIcon || current.searchIcon,
+      state: appConfig.state || current.state || APP_STATE.CLOSED,
+      buttons: {
+        ...(current.buttons || {}),
+        ...(appConfig.buttons || {})
+      }
+    };
+  }
+
+  return merged;
+}
+
+async function createMapStore(config) {
+  const fallbackMap = buildFallbackMap(config);
+  let fromFileMap = null;
+  let mapCreatedFromMissing = false;
+
+  try {
+    const content = await readFile(config.mapPath, 'utf8');
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch (error) {
+      throw new Error(`invalid_map_json:${config.mapPath}`);
+    }
+    fromFileMap = normalizeMapObject(parsed);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      if (!config.createMapIfMissing) {
+        throw new Error(
+          `map_not_found:${config.mapPath}. Crie o arquivo map.json ou use { createMapIfMissing: true }.`
+        );
+      }
+      fromFileMap = { version: 1, apps: {} };
+      mapCreatedFromMissing = true;
+    } else if (error instanceof Error) {
+      throw error;
+    } else {
+      throw new Error(`map_read_error:${config.mapPath}`);
+    }
+  }
+
+  const map = mergeMaps(fallbackMap, fromFileMap);
+  const store = {
+    path: config.mapPath,
+    persistMap: config.persistMap,
+    map
+  };
+
+  if (config.createMapIfMissing && mapCreatedFromMissing) {
+    await persistMapStore(store);
+  }
+
+  return store;
+}
+
+function resolveAppInMap(store, rawAppName) {
+  const appName = resolveAppName(rawAppName);
+  return {
+    appName,
+    app: store.map.apps[appName]
+  };
+}
+
+function resolveMappedButton(appConfig, rawButtonName) {
+  if (!rawButtonName) return null;
+  const buttonName = resolveButtonKey(rawButtonName);
+  return appConfig.buttons && appConfig.buttons[buttonName]
+    ? appConfig.buttons[buttonName]
+    : null;
+}
+
+async function updateAppState(store, appName, nextState) {
+  const state = normalizeState(nextState);
+  if (!state) return;
+
+  const app = store.map.apps[appName];
+  if (!app) return;
+  if (app.state === state) return;
+
+  app.state = state;
+  await persistMapStore(store);
+}
+
+async function persistMapStore(store) {
+  if (!store.persistMap) return;
+  await mkdir(dirnamePath(store.path), { recursive: true });
+  const serialized = JSON.stringify(store.map, null, 2) + '\n';
+  await writeFile(store.path, serialized, 'utf8');
+}
+
+function getAppState(appConfig) {
+  return normalizeState(appConfig && appConfig.state) || APP_STATE.CLOSED;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function smoothMove(robot, xFinal, yFinal, steps, delay) {
+  const current = robot.getMousePos();
+  const totalSteps = Math.max(1, parseIntegerOption(steps, 50, 1));
+
+  for (let i = 1; i <= totalSteps; i++) {
+    const progress = i / totalSteps;
+    const x = Math.round(current.x + (xFinal - current.x) * progress);
+    const y = Math.round(current.y + (yFinal - current.y) * progress);
+    robot.moveMouse(x, y);
+    await sleep(delay);
+  }
+}
+
+async function smoothScroll(robot, amount, steps, delay) {
+  const totalSteps = Math.max(1, parseIntegerOption(steps, 10, 1));
+  let applied = 0;
+
+  for (let i = 1; i <= totalSteps; i++) {
+    const target = Math.round((amount * i) / totalSteps);
+    const delta = target - applied;
+    if (delta !== 0) {
+      robot.scrollMouse(0, delta);
+      applied = target;
+    }
+    await sleep(delay);
+  }
+}
+
+function clickCurrentPosition(robot, doubleClick) {
+  if (doubleClick) {
+    robot.mouseClick('left', true);
+    return;
+  }
+  robot.mouseClick();
+}
+
+async function clickPoint(robot, point, config, clickOptions = {}) {
+  await smoothMove(robot, point.x, point.y, config.moveSteps, config.moveDelay);
+  clickCurrentPosition(robot, clickOptions.doubleClick === true);
+}
+
+async function runConfiguredPath(robot, pathConfig, config) {
+  if (!pathConfig || !Array.isArray(pathConfig.points) || pathConfig.points.length === 0) {
+    return;
+  }
+
+  const clickMode = normalizeClickMode(pathConfig.clickMode, CLICK_MODE.NONE);
+  const interval = toNonNegativeInteger(pathConfig.interval) || 0;
+  const clickDelay = toNonNegativeInteger(pathConfig.clickDelay) || 0;
+  const doubleClick = pathConfig.doubleClick === true;
+
+  for (let index = 0; index < pathConfig.points.length; index++) {
+    const point = pathConfig.points[index];
+    await smoothMove(robot, point.x, point.y, config.moveSteps, config.moveDelay);
+
+    if (shouldClickOnStep(clickMode, index, pathConfig.points.length)) {
+      if (clickDelay > 0) {
+        await sleep(clickDelay);
+      }
+      clickCurrentPosition(robot, doubleClick);
+    }
+
+    if (index < pathConfig.points.length - 1 && interval > 0) {
+      await sleep(interval);
+    }
+  }
+}
+
+async function clickTarget(robot, target, config, clickOptions = {}) {
+  if (!target || !target.position) {
+    throw new Error('invalid_target_config');
+  }
+
+  if (target.path) {
+    await runConfiguredPath(robot, target.path, config);
+  }
+
+  await clickPoint(robot, target.position, config, clickOptions);
+}
+
+function createActionHandlers(robot, runtime) {
+  const config = runtime.config;
+  let mapStorePromise;
+
+  async function getMapStore() {
+    if (mapStorePromise) {
+      return mapStorePromise;
+    }
+    mapStorePromise = runtime.getMapStore();
+    return mapStorePromise;
+  }
+
+  async function openAppIfNeeded(appName, appConfig, mapStore) {
+    if (getAppState(appConfig) === APP_STATE.OPEN) {
+      return;
+    }
+
+    if (!appConfig.launcher || !appConfig.launcher.position) {
+      throw new Error(`missing_launcher:${appName}`);
+    }
+
+    if (appConfig.launcher.path) {
+      await clickTarget(robot, appConfig.launcher, config);
+    } else {
+      await smoothMove(robot, 0, 0, config.moveSteps, config.moveDelay);
+      await smoothMove(
+        robot,
+        appConfig.launcher.position.x,
+        appConfig.launcher.position.y,
+        config.moveSteps,
+        config.moveDelay
+      );
+      await smoothMove(
+        robot,
+        appConfig.launcher.position.x + 20,
+        appConfig.launcher.position.y + 10,
+        config.moveSteps,
+        config.moveDelay
+      );
+      await smoothMove(
+        robot,
+        appConfig.launcher.position.x - 20,
+        appConfig.launcher.position.y - 10,
+        config.moveSteps,
+        config.moveDelay
+      );
+      robot.mouseClick();
+    }
+
+    await updateAppState(mapStore, appName, APP_STATE.OPEN);
+  }
+
+  function resolveSequencePoints(command) {
+    const points = normalizePointsValue(
+      command.points !== undefined
+        ? command.points
+        : command.path !== undefined
+          ? command.path
+          : command.command
+    );
+
+    if (!points || points.length < 2) {
+      throw new Error('move_sequence_requires_at_least_2_points');
+    }
+
+    return points;
+  }
+
+  function resolveSequenceInterval(command) {
+    const interval = toNonNegativeInteger(command.interval);
+    if (interval !== null) {
+      return interval;
+    }
+    return config.sequenceInterval;
+  }
+
+  function resolveSequenceClickMode(command) {
+    return normalizeClickMode(command.click, config.sequenceClickMode);
+  }
+
+  function resolveSequenceClickDelay(command) {
+    const clickDelay = toNonNegativeInteger(command.clickDelay);
+    if (clickDelay !== null) {
+      return clickDelay;
+    }
+    return 0;
+  }
+
+  function resolveSequenceDoubleClick(command) {
+    const value = parseBooleanValue(command.doubleClick);
+    if (value !== null) {
+      return value;
+    }
+    return config.sequenceDoubleClick;
+  }
+
+  async function tapKey(key, modifiers) {
+    if (modifiers && modifiers.length > 0) {
+      robot.keyTap(key, modifiers);
+      return;
+    }
+    robot.keyTap(key);
+  }
+
+  function resolveKeyTapPayload(command) {
+    const key = normalizeKeyTapToken(
+      command.key !== undefined ? command.key : command.command
+    );
+
+    if (!key) {
+      throw new Error('key_tap_requires_key');
+    }
+
+    const modifiers =
+      command.modifiers !== undefined
+        ? parseKeyModifiers(command.modifiers)
+        : parseKeyModifiers(command.extra);
+
+    return {
+      key,
+      modifiers
+    };
+  }
+
+  function resolveTypeStringPayload(command) {
+    const text =
+      command.text !== undefined && command.text !== null
+        ? String(command.text)
+        : command.command !== undefined && command.command !== null
+          ? String(command.command)
+          : command.extra !== undefined && command.extra !== null
+            ? String(command.extra)
+            : '';
+
+    if (!text.trim()) {
+      throw new Error('type_string_delayed_requires_text');
+    }
+
+    const customDelay = toNonNegativeInteger(
+      command.typeDelay !== undefined ? command.typeDelay : command.interval
+    );
+
+    return {
+      text,
+      typeDelay: customDelay !== null ? customDelay : config.typeDelay
+    };
+  }
+
+  return {
+    async skip_ads(command) {
+      let point = config.skipAdsPoint;
+
+      if (command.command) {
+        try {
+          const mapStore = await getMapStore();
+          const appRef = resolveAppInMap(mapStore, command.command);
+          const appConfig = appRef.app;
+          if (appConfig) {
+            const button = resolveMappedButton(
+              appConfig,
+              command.button || 'pular_ads'
+            );
+            if (button && button.position) {
+              if (button.path) {
+                await clickTarget(robot, button, config);
+                point = null;
+              } else {
+                point = button.position;
+              }
+              if (button.setState) {
+                await updateAppState(mapStore, appRef.appName, button.setState);
+              }
+            }
+          }
+        } catch (error) {
+          // keep fallback point when map is unavailable for skip_ads
+        }
+      }
+
+      if (point) {
+        await clickPoint(robot, point, config);
+      }
+    },
+
+    async click() {
+      const size = robot.getScreenSize();
+      const centerX = Math.floor(size.width / 2);
+      const centerY = Math.floor(size.height / 2);
+      await clickPoint(robot, { x: centerX, y: centerY }, config);
+    },
+
+    async double_click() {
+      const size = robot.getScreenSize();
+      const centerX = Math.floor(size.width / 2);
+      const centerY = Math.floor(size.height / 2);
+      await clickPoint(
+        robot,
+        { x: centerX, y: centerY },
+        config,
+        { doubleClick: true }
+      );
+    },
+
+    async scroll(command) {
+      const amount = Number(command.command);
+      if (!Number.isFinite(amount)) {
+        throw new Error('scroll_requires_numeric_command');
+      }
+
+      const size = robot.getScreenSize();
+      const centerX = Math.floor(size.width / 2);
+      const centerY = Math.floor(size.height / 2);
+
+      await smoothMove(robot, centerX, centerY, config.moveSteps, config.moveDelay);
+      await smoothScroll(robot, amount, config.scrollSteps, config.scrollDelay);
+    },
+
+    async move_sequence(command) {
+      const points = resolveSequencePoints(command);
+      const interval = resolveSequenceInterval(command);
+      const clickMode = resolveSequenceClickMode(command);
+      const clickDelay = resolveSequenceClickDelay(command);
+      const doubleClick = resolveSequenceDoubleClick(command);
+
+      for (let index = 0; index < points.length; index++) {
+        const point = points[index];
+        await smoothMove(
+          robot,
+          point.x,
+          point.y,
+          config.moveSteps,
+          config.moveDelay
+        );
+
+        if (shouldClickOnStep(clickMode, index, points.length)) {
+          if (clickDelay > 0) {
+            await sleep(clickDelay);
+          }
+          clickCurrentPosition(robot, doubleClick);
+        }
+
+        if (index < points.length - 1 && interval > 0) {
+          await sleep(interval);
+        }
+      }
+    },
+
+    async key_tap(command) {
+      const payload = resolveKeyTapPayload(command);
+      await tapKey(payload.key, payload.modifiers);
+    },
+
+    async type_string_delayed(command) {
+      const payload = resolveTypeStringPayload(command);
+      robot.typeStringDelayed(payload.text, payload.typeDelay);
+    },
+
+    async open_app(command) {
+      await tapKey('command');
+
+      const mapStore = await getMapStore();
+      const appRef = resolveAppInMap(mapStore, command.command);
+      if (!appRef.app) {
+        throw new Error(`unknown_app:${appRef.appName}`);
+      }
+
+      await openAppIfNeeded(appRef.appName, appRef.app, mapStore);
+
+      if (command.button) {
+        const mappedButton = resolveMappedButton(appRef.app, command.button);
+        if (!mappedButton) {
+          throw new Error(
+            `unknown_button:${appRef.appName}:${resolveButtonKey(command.button)}`
+          );
+        }
+
+        await clickTarget(robot, mappedButton, config);
+        if (mappedButton.setState) {
+          await updateAppState(mapStore, appRef.appName, mappedButton.setState);
+        }
+        return;
+      }
+
+      if (command.extra) {
+        if (appRef.app.searchIcon && appRef.app.searchIcon.position) {
+          await clickTarget(robot, appRef.app.searchIcon, config);
+        }
+
+        const customTypeDelay = toNonNegativeInteger(command.typeDelay);
+        const typeDelay =
+          customTypeDelay !== null ? customTypeDelay : config.typeDelay;
+
+        robot.typeStringDelayed(String(command.extra), typeDelay);
+      }
+    },
+
+    async close_app(command) {
+      const mapStore = await getMapStore();
+      const appRef = resolveAppInMap(mapStore, command.command);
+      if (!appRef.app) {
+        throw new Error(`unknown_app:${appRef.appName}`);
+      }
+
+      if (getAppState(appRef.app) === APP_STATE.CLOSED) {
+        return;
+      }
+
+      const mappedButton = resolveMappedButton(
+        appRef.app,
+        command.button || 'fechar'
+      );
+
+      if (mappedButton) {
+        await clickTarget(robot, mappedButton, config);
+        await updateAppState(
+          mapStore,
+          appRef.appName,
+          mappedButton.setState || APP_STATE.CLOSED
+        );
+        return;
+      }
+
+      const modifier =
+        config.launchKey === 'command' ? 'command' : config.launchKey || 'command';
+      robot.keyTap('w', modifier);
+      await updateAppState(mapStore, appRef.appName, APP_STATE.CLOSED);
+    }
+  };
+}
+
+async function getRobot() {
+  if (robotCache) {
+    return robotCache;
+  }
+
+  let module;
+  try {
+    module = await import('robotjs');
+  } catch (error) {
+    throw new Error(
+      'robotjs_not_available: install dependencies and run in a supported desktop environment.'
+    );
+  }
+
+  const robot = module && module.default ? module.default : module;
+  if (!robot || typeof robot.mouseClick !== 'function') {
+    throw new Error(
+      'robotjs_not_available: install dependencies and run in a supported desktop environment.'
+    );
+  }
+
+  robotCache = robot;
+  return robot;
+}