Wait for Selector

Instructions

Implementation Reference

• src/tools/navigation.ts:146-184 (registration)

  Registration of the 'pinchtab_wait_for_selector' tool via server.registerTool().

  server.registerTool(
    "pinchtab_wait_for_selector",
    {
      description:
        "Wait for a CSS selector to appear on the page. Polls every 500ms up to the timeout. Useful for waiting on dynamic content, modals, or lazy-loaded elements.",
      inputSchema: z.object({
        selector: z
          .string()
          .describe("CSS selector to wait for (e.g. '#login-form', '.loaded', '[data-ready]')"),
        timeoutMs: z
          .number()
          .optional()
          .describe("Maximum wait time in ms (default: 5000, max: 15000)."),
      }),
      title: "Wait for Selector",
    },
    async ({ selector, timeoutMs }) => {
      const timeout = Math.min(timeoutMs ?? SELECTOR_TIMEOUT_DEFAULT, SELECTOR_TIMEOUT_MAX);
      const deadline = Date.now() + timeout;
      try {
        while (Date.now() < deadline) {
          const result = await pinch("POST", "/evaluate", {
            expression: `!!document.querySelector(${JSON.stringify(selector)})`,
          });
          const found =
            result === true ||
            result === "true" ||
            (typeof result === "object" &&
              result !== null &&
              (result as Record<string, unknown>).result === true);
          if (found) return toolResult({ found: true, selector });
          await new Promise((resolve) => setTimeout(resolve, SELECTOR_POLL_MS));
        }
        return toolError(new Error(`Selector "${selector}" not found within ${timeout}ms`));
      } catch (error) {
        return toolError(error);
      }
    },
  );

• src/tools/navigation.ts:162-183 (handler)

  Handler function for pinchtab_wait_for_selector: polls document.querySelector every 500ms until selector is found or timeout.

  async ({ selector, timeoutMs }) => {
    const timeout = Math.min(timeoutMs ?? SELECTOR_TIMEOUT_DEFAULT, SELECTOR_TIMEOUT_MAX);
    const deadline = Date.now() + timeout;
    try {
      while (Date.now() < deadline) {
        const result = await pinch("POST", "/evaluate", {
          expression: `!!document.querySelector(${JSON.stringify(selector)})`,
        });
        const found =
          result === true ||
          result === "true" ||
          (typeof result === "object" &&
            result !== null &&
            (result as Record<string, unknown>).result === true);
        if (found) return toolResult({ found: true, selector });
        await new Promise((resolve) => setTimeout(resolve, SELECTOR_POLL_MS));
      }
      return toolError(new Error(`Selector "${selector}" not found within ${timeout}ms`));
    } catch (error) {
      return toolError(error);
    }
  },

• src/tools/navigation.ts:148-161 (schema)

  Input schema using zod: requires 'selector' (string), optional 'timeoutMs' (number, default 5000, max 15000).

  {
    description:
      "Wait for a CSS selector to appear on the page. Polls every 500ms up to the timeout. Useful for waiting on dynamic content, modals, or lazy-loaded elements.",
    inputSchema: z.object({
      selector: z
        .string()
        .describe("CSS selector to wait for (e.g. '#login-form', '.loaded', '[data-ready]')"),
      timeoutMs: z
        .number()
        .optional()
        .describe("Maximum wait time in ms (default: 5000, max: 15000)."),
    }),
    title: "Wait for Selector",
  },

• src/tools/navigation.ts:11-13 (helper)

  Constants used by the tool: SELECTOR_POLL_MS (500), SELECTOR_TIMEOUT_DEFAULT (5000), SELECTOR_TIMEOUT_MAX (15000).

  const SELECTOR_POLL_MS = 500;
  const SELECTOR_TIMEOUT_DEFAULT = 5000;
  const SELECTOR_TIMEOUT_MAX = 15_000;