@odg/chemical-x 2.1.3 → 2.3.0

package/docs/crawlers.md

@@ -0,0 +1,240 @@
+## Chemical-X Crawler API - Pages, Handlers, BrowserManager
+
+Arquitetura para automação web com abstração sobre Puppeteer/Playwright. Requer driver de browser instalado separadamente.
+
+```typescript
+import { BrowserManager, BasePage, BaseHandler, Browser, Context, Page, Container } from "@odg/chemical-x";
+```
+
+---
+
+### BrowserManager
+
+Orquestrador central que cria instâncias de Browser e Context via factories injetadas pelo consumidor.
+
+**Assinatura:**
+
+```typescript
+class BrowserManager<BrowserClassEngine, ContextClassEngine, PageClassEngine> {
+    constructor(
+        $newBrowser: CreateBrowserFactoryType<BrowserClassEngine, ContextClassEngine, PageClassEngine>,
+        $newContext: CreateContextFactoryType<ContextClassEngine, PageClassEngine>,
+        $newPage: CreatePageFactoryType<PageClassEngine>,
+    )
+
+    async newBrowser(
+        browser: () => Promise<BrowserClassEngine>,
+    ): Promise<BrowserChemicalXInterface<...> & BrowserClassEngine>
+
+    async newPersistentContext(
+        context: () => Promise<ContextClassEngine>,
+    ): Promise<ContextChemicalXInterface<...> & ContextClassEngine>
+}
+```
+
+**Responsabilidades:**
+
+- Cria instâncias de `Browser` via `newBrowser()` — recebe factory que retorna engine do browser
+- Cria contextos persistentes via `newPersistentContext()` — recebe factory que retorna engine do contexto
+- **Não auto-seleciona driver**: consumer configura Puppeteer ou Playwright via factory injetada
+- Retorna objetos que combinam interface Chemical-X com o engine nativo (via `@getterAccess` proxy)
+
+**Lifecycle:**
+
+1. Consumer instancia `BrowserManager` com factories (normalmente via Container/DI)
+2. `newBrowser(() => puppeteer.launch())` → retorna `Browser` com proxy sobre Puppeteer
+3. `browser.newContext(options?)` → retorna `Context` com proxy
+4. `context.newPage()` → retorna `Page` com proxy
+
+---
+
+### Browser, Context, Page (Wrappers)
+
+Wrappers com `@getterAccess` que delegam acesso ao engine nativo de forma transparente.
+
+**Browser:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class Browser<BrowserClassEngine, ContextClassEngine, PageClassEngine>
+    implements GetterAccessInterface, BrowserChemicalXInterface<...> {
+
+    $browserInstance: BrowserClassEngine;
+    async defaultContextOptions(): Promise<ContextOptionsLibraryInterface>;
+    async newContext(options?): Promise<ContextChemicalXInterface<...> & ContextClassEngine>;
+    contexts(): Array<ContextChemicalXInterface<...> & ContextClassEngine>;
+    __get(key: PropertyKey): unknown;
+}
+```
+
+**Context:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class Context<ContextClassEngine, PageClassEngine>
+    implements GetterAccessInterface, ContextChemicalXInterface<...> {
+
+    $contextInstance: ContextClassEngine;
+    async defaultPageOptions(): Promise<PageOptionsLibraryInterface>;
+    async newPage(options?): Promise<PageChemicalXInterface<...> & PageClassEngine>;
+    pages(): Array<PageChemicalXInterface<...> & PageClassEngine>;
+    __get(key: PropertyKey): unknown;
+}
+```
+
+**Page:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class Page<ContextClassEngine, PageClassEngine>
+    implements GetterAccessInterface, PageChemicalXInterface<...> {
+
+    $pageInstance: PageClassEngine;
+    context(): ContextChemicalXInterface<...> & ContextClassEngine;
+    __get(key: PropertyKey): unknown;
+}
+```
+
+Todos usam `@getterAccess` para delegar acessos de propriedade/método ao engine subjacente. Isso permite chamar métodos nativos do Puppeteer/Playwright diretamente no wrapper.
+
+---
+
+### BasePage (Abstract)
+
+Define uma página por **intenção**, não por URL. Implementa `AttemptableInterface` com lifecycle hooks para retry via `@attemptableFlow`.
+
+**Assinatura:**
+
+```typescript
+abstract class BasePage<PageClassEngine> implements PageInterface {
+    currentAttempt: number = 0;
+    page?: PageClassEngine;
+
+    abstract readonly $s?: SelectorType;                              // Seletor principal
+    abstract readonly $$s?: Record<string | number | symbol, SelectorType>; // Mapa de seletores
+
+    setPage(page: PageClassEngine): this;
+
+    // Obrigatórios (abstract)
+    abstract execute(): Promise<void>;    // Ação principal da página
+    abstract attempt(): Promise<number>;  // Retorna número de tentativas
+
+    // Hooks opcionais (lifecycle do @attemptableFlow)
+    success?(): Promise<void>;
+    failure?(exception: Exception): Promise<void>;
+    retrying?(exception: Exception, attempt: number): Promise<RetryAction>;
+    finish?(exception?: Exception): Promise<void>;
+    sleep?(): Promise<number>;
+}
+```
+
+**Page Intent Design:**
+
+> Pages agrupam por **INTENÇÃO**, não por URL. Uma mesma URL pode ter múltiplas Pages.
+
+Exemplos:
+- `LoginPage` (intenção: autenticar) — URL: `/login`
+- `LoginVerificationPage` (intenção: verificar se login OK) — URL: `/login` ou `/dashboard`
+- `HomeContentPage` (intenção: extrair conteúdo) — URL: `/`
+- `HomeAdPage` (intenção: extrair anúncios) — URL: `/`
+
+**Lifecycle:**
+
+1. `setPage(page)` — injeta instância da page do browser
+2. `execute()` — executa ação (navegar, preencher, clicar)
+3. Se falha → `retrying(exception, attempt)` decide retry ou não
+4. Se sucesso → `success()`
+5. Se falha final → `failure(exception)`
+6. Sempre → `finish(exception?)`
+
+---
+
+### BaseHandler (Abstract)
+
+Valida transições e resultados de páginas. **Handlers validam, não executam ações.**
+
+**Assinatura:**
+
+```typescript
+abstract class BaseHandler<PageClassEngine> implements HandlerInterface {
+    currentAttempt: number = 0;
+    page?: PageClassEngine;
+
+    abstract readonly $$s: Record<string | number | symbol, SelectorType>;
+
+    setPage(page: PageClassEngine): this;
+
+    // Concrete
+    async execute(): Promise<void>;
+    async successSolution(): Promise<HandlerSolutionType>; // Retorna RetryAction.Resolve
+
+    // Obrigatórios (abstract)
+    abstract waitForHandler(): Promise<HandlerFunction>;   // Retorna Exception ou solution function
+    abstract attempt(): Promise<number>;
+
+    // Hooks opcionais
+    success?(): Promise<void>;
+    failure?(exception: Exception): Promise<void>;
+    retrying?(exception: Exception, attempt: number): Promise<RetryAction>;
+    finish?(exception?: Exception): Promise<void>;
+    sleep?(): Promise<number>;
+}
+```
+
+**Tipos de retorno de Handler:**
+
+```typescript
+type HandlerSolutionType = Exception | Exclude<RetryAction, RetryAction.Default | RetryAction.Throw>;
+type HandlerFunction = Exception | (() => Promise<HandlerSolutionType>);
+```
+
+**Handler Pattern:**
+
+> "Pages executam. Handlers validam. Handlers declaram Solution ou lançam Exception."
+
+- `waitForHandler()` retorna `Exception` → falha detectada
+- `waitForHandler()` retorna `() => Promise<HandlerSolutionType>` → solução disponível
+- Solution pode ser: `RetryAction.Resolve` (sucesso), `RetryAction.Retry` (tentar novamente)
+- Handler **NUNCA** interage com a page diretamente
+- Handler **NUNCA** chama outras Pages para resolver problemas
+- Handler **NUNCA** falha silenciosamente
+
+---
+
+### Container / DI
+
+Chemical-X usa Inversify para DI. `@ODGDecorators.injectable(name)` registra metadata; consumer deve chamar `Container.loadModule()`.
+
+**Regras:**
+
+1. `Container.loadModule()` **obrigatório** antes de executar qualquer Page/Handler registrado
+2. DI binding é **responsabilidade do consumidor** — Chemical-X não auto-wira
+3. `Container.getOptional(name)` retorna `undefined` se serviço não registrado (vs `get()` que lança)
+4. Puppeteer/Playwright deve ser injetado via Container ou passado ao `BrowserManager` constructor
+
+---
+
+### Workflow Example
+
+Fluxo completo: login em site com tratamento de 2FA.
+
+```
+1. Create LoginPage (intent: autenticar)
+   → setPage(page) → execute() (navegar, preencher credenciais, clicar login)
+
+2. Create LoginHandler (intent: validar resultado do login)
+   → setPage(page) → waitForHandler()
+   → Detecta 2FA required → return () => new TwoFaPage() as Solution
+   → Detecta login error → return new InvalidCredentialsException()
+   → Detecta sucesso → return successSolution() (RetryAction.Resolve)
+
+3. Se Solution = TwoFaPage:
+   → Create TwoFaPage (intent: resolver 2FA)
+   → setPage(page) → execute() (preencher código 2FA)
+
+4. Create DashboardHandler (intent: verificar que chegou no dashboard)
+   → setPage(page) → waitForHandler()
+   → Verifica URL/conteúdo → return successSolution()
+```
+
+See also: `tests/vitest/Handlers/` e `tests/vitest/Pages/` para exemplos reais de implementação.

package/docs/decorators.md

@@ -0,0 +1,258 @@
+## Chemical-X Decorators - @ODGDecorators.attemptableFlow, @ODGDecorators.getterAccess, @ODGDecorators.injectable
+
+DSL baseada em decorators para retry com lifecycle, interceptação de acesso e DI registration.
+
+```typescript
+import { ODGDecorators } from "@odg/chemical-x";
+```
+
+---
+
+### `@ODGDecorators.attemptableFlow()`
+
+Decorator de classe que adiciona retry com lifecycle hooks completo. Envolve `execute()` com lógica de retentativa baseada em `AttemptableInterface`.
+
+**Aplicação:**
+
+```typescript
+@ODGDecorators.attemptableFlow()
+class MyPage extends BasePage<PageEngine> {
+    // ...
+}
+```
+
+**Lifecycle Hooks:**
+
+| Hook | Obrigatório | Quando chamado |
+|---|---|---|
+| `execute()` | Sim | Ação principal; retentada até `attempt()` vezes |
+| `attempt()` | Sim | Retorna número máximo de tentativas |
+| `sleep()` | Não | Retorna ms entre tentativas (se definido) |
+| `success()` | Não | Chamado quando `execute()` sucede |
+| `failure(exception)` | Não | Chamado quando todas tentativas falham; recebe a última exceção |
+| `retrying(exception, attempt)` | Não | Chamado antes de cada retry; retorna `RetryAction` para decidir ação |
+| `finish(exception?)` | Não | Chamado sempre ao final (sucesso ou falha); recebe exceção se houve |
+
+**Propriedade:**
+
+- `currentAttempt: number` — número da tentativa atual (atualizado automaticamente pelo decorator)
+
+**Fluxo de Execução:**
+
+```
+execute() chamado
+  ├─ Sucesso → success() → finish()
+  └─ Falha → retrying(exception, attempt)?
+               ├─ RetryAction.Retry → execute() novamente
+               ├─ RetryAction.Throw → failure(exception) → finish(exception)
+               ├─ RetryAction.Resolve → finish() (sem exceção, resolve undefined)
+               └─ RetryAction.Default → se attempts restam → sleep() → execute()
+                                         └─ se esgotou → failure(exception) → finish(exception)
+```
+
+**Exemplo:**
+
+```typescript
+@ODGDecorators.attemptableFlow()
+class LoginPage extends BasePage<PuppeteerPage> {
+    readonly $s = "form#login";
+    readonly $$s = {
+        username: "input[name=username]",
+        password: "input[name=password]",
+        submit: "button[type=submit]",
+    };
+
+    async attempt(): Promise<number> {
+        return 3;
+    }
+
+    async execute(): Promise<void> {
+        await this.page!.type(this.$$s.username, "user@example.com");
+        await this.page!.type(this.$$s.password, "password123");
+        await this.page!.click(this.$$s.submit);
+    }
+
+    async sleep(): Promise<number> {
+        return 2000; // 2s entre tentativas
+    }
+
+    async success(): Promise<void> {
+        console.log("Login successful");
+    }
+
+    async failure(exception: Exception): Promise<void> {
+        console.error("Login failed after all attempts:", exception.message);
+    }
+
+    async retrying(exception: Exception, attempt: number): Promise<RetryAction> {
+        if (exception instanceof BrowserException) return RetryAction.Throw;
+        return RetryAction.Default;
+    }
+}
+```
+
+See also: `tests/vitest/Pages/` para exemplos de Pages com `@attemptableFlow`.
+
+---
+
+### `@ODGDecorators.getterAccess()`
+
+Decorator de classe que cria um Proxy interceptando **todo** acesso a propriedade/método via `__get(key, value)`.
+
+**Aplicação:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class MyWrapper implements GetterAccessInterface {
+    __get(key: PropertyKey, value: unknown): unknown {
+        // Intercepta todo acesso
+        return value;
+    }
+}
+```
+
+**Comportamento do Proxy:**
+
+- **Todo** acesso a propriedade (leitura) passa por `__get(key, value)` onde:
+  - `key` = nome da propriedade acessada
+  - `value` = valor original da propriedade (se existir)
+- Permite: delegação transparente ao engine, validação, lazy-load, tracking, logging
+
+**Uso interno no Chemical-X:**
+
+`Browser`, `Context` e `Page` usam `@getterAccess` para delegar ao engine nativo:
+
+```typescript
+@ODGDecorators.getterAccess()
+class Browser<BrowserClassEngine, ...> implements GetterAccessInterface {
+    $browserInstance: BrowserClassEngine;
+
+    __get(key: PropertyKey): unknown {
+        // Delega ao engine nativo (Puppeteer/Playwright)
+        return (this.$browserInstance as Record<PropertyKey, unknown>)[key];
+    }
+}
+```
+
+Isso permite:
+```typescript
+const browser = await manager.newBrowser(() => puppeteer.launch());
+// Acessa métodos nativos do Puppeteer diretamente no wrapper:
+await browser.close(); // Delegado via __get → puppeteerBrowser.close()
+```
+
+See also: `tests/vitest/puppeteer/` e `tests/vitest/playwright/` para exemplos de uso com drivers reais.
+
+---
+
+### `@ODGDecorators.injectable(name, scope?)`
+
+Registra classe no Container (Inversify) com `@injectable()` e `@injectFromHierarchy()`.
+
+**Aplicação:**
+
+```typescript
+@ODGDecorators.injectable("LoginPage")
+@ODGDecorators.attemptableFlow()
+class LoginPage extends BasePage<PageEngine> {
+    // ...
+}
+```
+
+**Regras:**
+
+1. Define metadata para DI — **não registra automaticamente no Container**
+2. Consumer **deve** chamar `Container.loadModule()` para efetivar os bindings
+3. Combinado com `@attemptableFlow` em Pages e Handlers
+4. O `name` é usado como identificador do binding no Container
+5. Deve sempre ficar a cima de todos os outros decorators (ex: `@attemptableFlow`) para garantir que a classe seja registrada apos de ser processada por outros decorators
+
+---
+
+### `@registerListener(eventName, containerName, options)`
+
+Registra listener de eventos em Container EventEmitter via metadata.
+
+**Aplicação:**
+
+```typescript
+@ODGDecorators.registerListener("page:loaded", "PageEventEmitter", { once: true })
+class PageLoadedListener {
+    // ...
+}
+```
+
+---
+
+### Comparison - When to Use
+
+| Cenário | Ferramenta | Motivo |
+|---|---|---|
+| Retry simples de callback | `retry()` | Função isolada, sem lifecycle, sem estado |
+| Retry de classe inteira com hooks | `@ODGDecorators.attemptableFlow` | Lifecycle completo: attempt, success, failure, retrying, finish, sleep |
+| Interceptar propriedades | `@ODGDecorators.getterAccess` | Proxy transparente para delegação/validação |
+| Registrar no Container | `@ODGDecorators.injectable` | DI via Inversify com hierarchy |
+| Callback com timeout | `timeout()` | Sem retry, apenas limite de tempo |
+| Classe retriable com timeout | `@ODGDecorators.attemptableFlow` + `timeout()` no `execute()` | Combine ambos para retry + timeout |
+
+**Regra geral:**
+- Use `retry()` quando quer retentar **uma função**
+- Use `@ODGDecorators.attemptableFlow` quando quer retentar **um comportamento de classe** com estado e lifecycle
+
+---
+
+### Common Patterns
+
+**@ODGDecorators.attemptableFlow com handler e solução:**
+
+```typescript
+@ODGDecorators.injectable("LoginHandler")
+@ODGDecorators.attemptableFlow()
+class LoginHandler extends BaseHandler<PuppeteerPage> {
+    readonly $$s = {
+        errorMsg: ".error-message",
+        dashboard: "#dashboard",
+        twoFa: "#two-fa-form",
+    };
+
+    async attempt(): Promise<number> {
+        return 5;
+    }
+
+    async waitForHandler(): Promise<HandlerFunction> {
+        // Espera por um dos seletores aparecer na página
+        const found = await this.page!.waitForSelector(
+            [this.$$s.errorMsg, this.$$s.dashboard, this.$$s.twoFa].join(", "),
+        );
+
+        if (found?.matches(this.$$s.errorMsg)) {
+            return new BrowserException("Login failed");
+        }
+
+        if (found?.matches(this.$$s.twoFa)) {
+            return async () => RetryAction.Retry; // Indica que precisa retry (2FA page)
+        }
+
+        return async () => this.successSolution(); // RetryAction.Resolve
+    }
+}
+```
+
+**@ODGDecorators.getterAccess para wrapper customizado:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class CachedPage implements GetterAccessInterface {
+    private cache = new Map<PropertyKey, unknown>();
+    private wrapped: SomeEngine;
+
+    __get(key: PropertyKey, value: unknown): unknown {
+        if (this.cache.has(key)) return this.cache.get(key);
+        const result = (this.wrapped as Record<PropertyKey, unknown>)[key];
+        this.cache.set(key, result);
+        return result;
+    }
+}
+```
+
+See also: `tests/vitest/Handlers/` e `tests/vitest/Listeners/` para exemplos reais.

package/docs/exceptions.md

@@ -0,0 +1,212 @@
+## Chemical-X Exceptions - Reference Guide
+
+Referência completa de todas as exceções públicas. Todas estendem `Exception` de `@odg/exception`.
+
+```typescript
+import {
+    BrowserException,
+    BrowserInstanceException,
+    RetryException,
+    TimeoutException,
+    InvalidArgumentException,
+    MoneyNotFoundException,
+    MoneyMultipleResultException,
+} from "@odg/chemical-x";
+```
+
+---
+
+### Exception Reference
+
+#### `BrowserException`
+
+| | |
+|---|---|
+| **Trigger** | Falha em operação do browser em runtime (crash, perda de conexão, operação inválida) |
+| **Quando** | Interações com Page/Browser via Crawler API (click, type, goto, etc.) |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Catch e retry (via `@attemptableFlow`) ou fallback |
+
+```typescript
+try {
+    await page.execute();
+} catch (exception) {
+    if (exception instanceof BrowserException) {
+        // Browser crashed ou conexão perdida — retry ou fallback
+    }
+}
+```
+
+---
+
+#### `BrowserInstanceException`
+
+| | |
+|---|---|
+| **Trigger** | Falha ao criar/inicializar instância do browser |
+| **Quando** | `BrowserManager.newBrowser()` ou `BrowserManager.newPersistentContext()` |
+| **Extends** | `BrowserException` |
+| **Handling** | Verificar setup do driver (Puppeteer/Playwright instalado?), retry init |
+
+```typescript
+try {
+    const browser = await manager.newBrowser(() => puppeteer.launch());
+} catch (exception) {
+    if (exception instanceof BrowserInstanceException) {
+        // Driver não encontrado ou falha ao iniciar — verificar instalação
+    }
+}
+```
+
+---
+
+#### `RetryException`
+
+| | |
+|---|---|
+| **Trigger** | Todas as tentativas de `retry()` esgotadas sem sucesso |
+| **Quando** | `retry()` completa todos os `times` sem callback suceder |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Fallback final ou propagar erro ao chamador |
+
+```typescript
+try {
+    await retry({ times: 3, callback: async () => { /* ... */ } });
+} catch (exception) {
+    if (exception instanceof RetryException) {
+        // Todas tentativas falharam — aplicar fallback ou logar erro final
+    }
+}
+```
+
+---
+
+#### `TimeoutException`
+
+| | |
+|---|---|
+| **Trigger** | Operação excede o limite de tempo definido em `timeout()` |
+| **Quando** | `timeout({ timeout: ms, callback })` quando callback não completa a tempo |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Catch e tratar timeout; ajustar limite se operação legitimamente lenta |
+
+```typescript
+try {
+    await timeout({
+        name: "loadPage",
+        timeout: 5000,
+        callback: async () => await page.goto(url),
+    });
+} catch (exception) {
+    if (exception instanceof TimeoutException) {
+        // Operação "loadPage" excedeu 5000ms — retry ou aumentar limite
+    }
+}
+```
+
+---
+
+#### `InvalidArgumentException`
+
+| | |
+|---|---|
+| **Trigger** | Parâmetros inválidos passados para API |
+| **Quando** | `retry({ times: -1 })`, timeout negativo, argumento obrigatório ausente |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Validar inputs antes de chamar API; este é um erro de programação |
+
+```typescript
+// Este erro indica bug no código do consumidor:
+try {
+    await retry({ times: 0, callback: async () => {} });
+} catch (exception) {
+    if (exception instanceof InvalidArgumentException) {
+        // Corrigir: times deve ser >= 1
+    }
+}
+```
+
+---
+
+#### `MoneyNotFoundException`
+
+| | |
+|---|---|
+| **Trigger** | `Str.money()` não encontra valor monetário na string |
+| **Quando** | `new Str("texto sem valor").money()` |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Verificar formato da string antes; usar try-catch ou validar conteúdo |
+
+```typescript
+try {
+    const value = new Str(rawText).money();
+} catch (exception) {
+    if (exception instanceof MoneyNotFoundException) {
+        // String não contém valor monetário reconhecível
+    }
+}
+```
+
+---
+
+#### `MoneyMultipleResultException`
+
+| | |
+|---|---|
+| **Trigger** | `Str.money()` encontra múltiplos valores monetários na string |
+| **Quando** | `new Str("R$ 10,00 e R$ 20,00").money()` — use `moneys()` |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Usar `Str.moneys()` para extrair todos os valores; `money()` espera exatamente um |
+
+```typescript
+try {
+    const value = new Str("R$ 10,00 e R$ 20,00").money();
+} catch (exception) {
+    if (exception instanceof MoneyMultipleResultException) {
+        // Múltiplos valores encontrados — usar moneys() em vez de money()
+        const values = new Str("R$ 10,00 e R$ 20,00").moneys();
+    }
+}
+```
+
+---
+
+### Handler Exception/Solution Contract
+
+`BaseHandler.waitForHandler()` retorna `HandlerFunction`:
+
+```typescript
+type HandlerSolutionType = Exception | Exclude<RetryAction, RetryAction.Default | RetryAction.Throw>;
+type HandlerFunction = Exception | (() => Promise<HandlerSolutionType>);
+```
+
+**Contrato:**
+
+1. Handler **deve** retornar `Exception` (falha) ou `() => Promise<HandlerSolutionType>` (solução)
+2. Handler **nunca** falha silenciosamente (retornar `void`/`undefined` não permitido)
+3. Solution function retorna:
+   - `RetryAction.Resolve` — sucesso (via `successSolution()`)
+   - `RetryAction.Retry` — retentar
+   - `Exception` — falha específica detectada na validação
+
+**Exemplo — Handler com contrato completo:**
+
+```typescript
+async waitForHandler(): Promise<HandlerFunction> {
+    // Espera seletores e decide
+    const errorVisible = await this.page!.$(this.$$s.error);
+    if (errorVisible) {
+        return new BrowserException("Login failed: error message visible");
+    }
+
+    const dashboardVisible = await this.page!.$(this.$$s.dashboard);
+    if (dashboardVisible) {
+        return async () => this.successSolution(); // RetryAction.Resolve
+    }
+
+    // Estado intermediário — retentar
+    return async () => RetryAction.Retry;
+}
+```
+
+See also: `tests/vitest/Exceptions/` e `tests/vitest/Handlers/` para exemplos de teste.