use-obscura

name

use-obscura

description

Iterate on Forrit's Remix/Vite frontend with the project-configured Obscura browser: inspect rendered DOM and interactive elements, exercise routes and forms, diagnose console and network failures, edit frontend code, and verify behavior after each change. Use for frontend implementation, UI behavior bugs, route-flow checks, accessibility-oriented DOM inspection, and browser-based regression work under frontend/app. Do not use Obscura alone for pixel-level visual review because it does not render screenshots.

Iterate Frontend With Obscura

Use Obscura as a persistent semantic browser while changing Forrit's frontend. Keep the browser loop focused on observable behavior: DOM content, accessible controls, navigation, forms, requests, and console output.

Prepare the environment

1. Inspect git status, the relevant route modules under frontend/app/routes, and reusable components under frontend/app/components. Preserve unrelated changes.
2. Confirm obscura is available. If it is not on PATH, enter the repository's Nix development shell with nix develop; the package comes from the locked github:George-Miao/flakes input.
3. Install existing frontend dependencies with cd frontend && pnpm install only when node_modules is absent or unusable. Do not change dependencies or lockfiles merely to drive Obscura.
4. Start just frontend in a persistent command session. Read the emitted local URL instead of assuming a port, and keep the server running throughout the loop.
5. Use the project-configured Obscura MCP tools. If they are absent immediately after this skill or .codex/config.toml was added, restart Codex in this trusted repository and verify the obscura server with /mcp.

For one-shot diagnostics when MCP tools are unavailable, run:

obscura --allow-private-network fetch "$URL" --dump text --wait-until networkidle0 --quiet
obscura --allow-private-network fetch "$URL" --eval "document.title" --quiet

Establish a baseline

1. Call browser_navigate with the dev-server URL and the target route.
2. Capture browser_snapshot and browser_interactive_elements before editing.
3. Read browser_console_messages and browser_network_requests. Separate frontend failures from expected unavailable backend/API data.
4. Use browser_detect_forms, browser_get_attribute, browser_count, browser_search, or browser_evaluate only to answer a concrete question about the page.
5. Record the exact behavior to preserve or change. Prefer user-visible assertions such as headings, labels, enabled states, route transitions, validation messages, and request outcomes.

Iterate

1. Make the smallest coherent source change with apply_patch. Keep route-level loading and composition in frontend/app/routes, reusable behavior or presentation in frontend/app/components, and API access in frontend/app/client.ts.
2. Reload or navigate again with Obscura after the dev server recompiles.
3. Exercise the affected flow with semantic evidence:
   • Use browser_click, browser_fill, browser_type, browser_press_key, and browser_select_option for interaction.
   • Use browser_wait_for or browser_wait_for_text after asynchronous transitions.
   • Prefer stable IDs, names, labels, roles, and explicit data attributes over CSS classes generated by the component library.
   • Re-read the snapshot, console, and relevant network requests after the action.
4. Patch and repeat until the requested behavior and the unaffected baseline both hold.
5. Close or reset browser state between scenarios when cookies, storage, or prior navigation could hide a regression. Never point the project MCP server at production or perform destructive account actions without explicit user direction.

Validate and hand off

Run the narrowest checks while iterating, then expand in proportion to the change:

cd frontend && pnpm typecheck
cd frontend && pnpm lint
cd frontend && pnpm build

Run the production frontend build before handoff when frontend source or public assets changed, and include the resulting tracked frontend/build/client updates when the embedded UI must remain synchronized. Do not edit hashed build assets directly.

Report the routes and interactions exercised, the observed DOM/console/network result, and the checks run. State explicitly that visual appearance was not verified if no pixel-rendering browser or user-provided screenshot was used.

Respect Obscura's boundary

Obscura runs JavaScript and exposes DOM/CDP automation, but it has no layout or pixel-rendering engine. It cannot produce screenshots, PDFs, videos, or trustworthy spacing, color, overflow, stacking, animation, or responsive-layout judgments. Do not infer those properties from DOM success. Use Obscura for semantic and functional iteration; use a pixel-rendering browser or supplied screenshots when the task requires visual evidence.