Skip to content

AGENTS.md

Latest commit

 

History

History
40 lines (34 loc) · 2.31 KB

AGENTS.md

File metadata and controls

40 lines (34 loc) · 2.31 KB
Raw

OpenTUI Browser Agent Guide

Architecture

  • Read CONTEXT.md before structural work. Use its domain language: Browser Surface, Managed Browser Runtime, Shared Browser Page, Presentation, and Host Chrome.
  • Keep one exact runtime path: Electron offscreen rendering to raw RGBA files to Kitty. Do not add alternate browser backends, old API aliases, or hidden transport modes.
  • Keep public orchestration in src/<domain>.ts and supporting code in src/<domain>/. Name modules for the policy or resource they own.
  • Reuse existing seams. Do not duplicate validation, numeric option policy, timers, scheduling, frame-ring policy, or lifecycle state.
  • Decode sidecar RPC, HTTP JSON, persisted markers, and other untrusted input once at their entry seam with Effect Schema. Do not use generic response casts, isRecord, or object-property probing as validation.
  • Keep the public runtime Promise-based. Add Effect services or layers only when typed dependency composition or scoped ownership justifies them.
  • Keep host composition in src/<domain>/service.ts and expose curated namespaces from opentui-browser/effect. BrowserSurface owns scoped renderer attachment; Electron owns scoped Managed Browser Runtime cleanup. Reuse src/effect/operation.ts for Promise-to-Effect failure adaptation.
  • Make ownership and cleanup explicit for processes, profiles, pages, presentations, callbacks, sockets, timers, temporary files, and Kitty images.
  • Bound producer-driven work and prefer latest-state reconciliation for frames, pointer moves, wheel input, and presentation updates.
  • Do not create broad utils.ts or helpers.ts modules.

Tooling And Verification

  • Use Bun for dependency management and scripts.
  • Keep this a single-package repository.
  • Preserve both Bun and Node runtime paths; do not add Bun-only APIs to shared runtime modules.
  • Use oxfmt as the formatting source of truth.
  • For observable fixes, add a focused regression test first. Run the narrowest test, then bun run typecheck and bun test.
  • Run bun run check and bun run test:packed for release-facing changes. Run bun run test:electron for live Electron runtime changes.

Agent Skill

  • Use $opentui-browser-architecture from .opencode/skills/opentui-browser-architecture/SKILL.md for changes or reviews in src/ and tests/.