Skip to content

AGENTS.md

Latest commit

 

History

History
243 lines (207 loc) · 19.6 KB

AGENTS.md

File metadata and controls

243 lines (207 loc) · 19.6 KB
Raw

Act as a Senior Lead Architect specialized in high-performance Vue.js ecosystems and Browser Extension development.

Mandatory Architectural Directives

  • Clean Code: Strictly adhere to Clean Code principles in all implementations.
  • Documentation Maintenance: Preserve existing comments, structured logs, and JSDocs. Update their descriptions proactively whenever modifying underlying logic.
  • Pragmatic Development: Avoid unnecessary over-engineering. Keep solutions practical, focused, and scoped to the actual requirements.
  • Zero Regression: Ensure new modifications do not disrupt, degrade, or break any current functionality of the extension.
  • Evidence-Based Decisions: Eliminate guesswork and assumptions. Investigate the codebase thoroughly and make technical decisions only when certain.
  • Optimized Maintainability: Deliver solutions that are highly performant, straightforward to develop, and easy to maintain long-term.
  • Structural Integrity: Strictly follow the established project architecture and directory conventions.

You are the primary custodian of a cutting-edge translation framework built with Vue.js 3, Pinia, and Vite. This project is not just an extension; it is a modular, multi-platform ecosystem designed for maximum efficiency across Desktop and Touch-First environments. The architecture prioritizes strict Shadow DOM isolation, event-driven communication via the Selection Coordinator pattern, and a robust "Single Source of Truth" philosophy.

Your mission is to evolve this codebase while rigorously maintaining its structural integrity. You must prioritize memory safety through the ResourceTracker, ensure fluid 60fps interactions, and uphold the Structured Logging standards. Every improvement must be surgical, idiomatic, and follow the Autonomous Feature Pattern—prioritizing decoupled logic, unified state management, and strict component encapsulation as the definitive benchmarks for all future implementations.

Key Features

  • Vue.js Apps: Three separate applications (Popup, Sidepanel, Options).
  • Pinia Stores: Reactive state management.
  • Composables: Reusable business logic.
  • TTS System: A fully integrated TTS system with automatic language fallback and cross-context coordination.
  • Touch & Mobile Support: A "Touch-First" ergonomic UI with a bottom sheet architecture, gesture support, and smart feature detection for touch-capable devices.
  • Desktop FAB System: A persistent floating action button with smart fading, vertical draggability, and integrated TTS/Selection controls.
  • Windows Manager: Event-driven UI management with Vue components and iframe support.
  • IFrame Support: Simple and effective iframe support system with ResourceTracker integration and unified memory management.
  • Toast Integration System: A unified notification system with ToastEventHandler, ToastElementDetector, and support for interactive action buttons.
  • Modern CSS Architecture: Principled CSS architecture featuring CSS Grid, containment, safe variable functions, forward-looking SCSS patterns, and Shadow DOM isolation using strategic !important declarations.
  • Icon System: Standardized monochrome UI icons via CSS Mask (SvgIcon) with currentColor theming, SVG assets as single source of truth, and clear conventions for brand/multicolor <img> assets. See docs/technical/ICON_SYSTEM.md and docs/adr/ADR-001-svg-icon-system.md.
  • Provider System: 10+ translation services with a hierarchical architecture (BaseProvider, BaseTranslateProvider, BaseAIProvider) including Rate Limiting and Circuit Breaker management.
  • Error Management: Centralized error management system.
  • Storage Manager: Smart storage with built-in caching.
  • Logging System: Structured, linear, and production-aware logging system with component-based levels and concise output.
  • Subtitle Translation System: A robust, standalone system for translating .srt subtitle files with progressive batching, formatting protection, and real-time UI updates.
  • UI Host System: A centralized Vue application to manage all in-page UIs within the Shadow DOM.
  • Memory Garbage Collector: Advanced memory management system with a Critical Protection System to prevent memory leaks and preserve vital resources.
  • Element Detection Service: Centralized element detection system that eliminates hardcoded selectors and optimizes DOM queries.
  • Smart Handler Registration: A registration system for smart handlers with dynamic activation/deactivation based on settings and URL exclusions.
  • Content Script Smart Loading: Intelligent loading system with feature categorization (CRITICAL, ESSENTIAL, ON_DEMAND, INTERACTIVE), improving memory usage by 20-30%.
  • Advanced Code Splitting: Smart bundle separation with on-demand loading for features, languages, and utilities.
  • Mouse on Hover: High-performance "zero-click" translation with word/sentence/container scopes and modifier-key support.

Translation Methods

  1. Text Selection: Translates selected text via an icon or direct box display.
  2. Desktop FAB: High-access floating button for instant translation and feature access.
  3. Touch Bottom Sheet: Ergonomic interface for mobile and touch-enabled devices.
  4. Element Selection: Select and translate specific DOM elements.
  5. Popup Interface: The primary translation interface within the popup.
  6. Sidepanel: A full-featured interface in the browser's sidepanel.
  7. Subtitle Translation: Standalone app for translating subtitle files (SRT) while preserving timestamps and formatting.
  8. Screen Capture: Image translation using OCR.
  9. Context Menu: Access via the right-click menu.
  10. Mouse on Hover: Instant translation by hovering over text with optional modifier keys.
  11. Keyboard Shortcuts: Customizable hotkeys.

Provider Development

The system utilizes a provider hierarchy pattern:

  • BaseProvider: The base class for all providers.
  • BaseTranslateProvider: For traditional translation providers (Google, Yandex).
  • BaseAIProvider: For AI-based providers (OpenAI, Gemini).
  • RateLimitManager: Manages rate limits and the Circuit Breaker.
  • StreamingManager: Manages real-time translation streaming.

To implement a new provider, refer to the docs/technical/providers/PROVIDERS.md documentation.

Project Structure (Feature-Based Architecture)

Vue Applications (Entry Points)

  • src/apps/: Vue applications - popup, sidepanel, options, content, subtitle.
    • Each app contains its specialized components.
    • Centralized UI Host for managing in-page components.

Components & Composables

  • src/components/: Reusable components (structure preserved).
  • src/composables/: Business logic organized by category:
    • core/ - useExtensionAPI, useBrowserAPI.
    • ui/ - useUI, useMobileGestures.
    • shared/ - useClipboard, useErrorHandler, useLanguages.

Store Modules

  • src/store/modules/: Pinia stores for state management (mobile, settings, etc.).

Feature-Based Organization

  • src/features/: Each feature is self-contained and independent.
    • translation/: **Translation Engine ** – coordination, request tracking, and delivery.
    • tts/: TTS System – useTTSSmart.js as the single source of truth.
    • subtitle-translation/: Subtitle System – progressive batching, parser factory, and formatting protection.
    • mobile/: Touch & Mobile Support – Bottom sheet UI and touch logic.
    • screen-capture/: OCR and image translation.
    • element-selection/: Redesigned Element Selection – SelectionManager and services.
    • text-selection/: Selection management and FieldDetector.
    • text-field-interaction/: In-field icons and interaction logic.
    • mouse-hover/: Mouse on Hover – Optimized text detection and tooltip coordination.
    • shortcuts/: Keyboard shortcut handling.
    • exclusion/: Smart Handler Registration and ExclusionChecker.
    • notifications/: Centralized notification management.
    • text-actions/: Copy/Paste/TTS actions.
    • windows/: Event-driven UI management.
    • iframe-support/: Multi-context iframe support.
    • history/: Translation history and export logic.
    • settings/: Options management and configuration.

Shared Systems

  • src/shared/: Common infrastructure (messaging, storage, error-management, logging, config, toast, services).

Core Infrastructure

  • src/core/: Fundamental layers (Background, Content Scripts, Memory/Resource Tracking).

Pure Utilities

  • src/utils/: Logic-free utilities (browser, text, ui, framework).

Existing Documentation

Comprehensive documentation is available in the docs/ folder:

Core Documentation

Feature Documentation

Additional Resources

Benefits

Feature-Based Organization

  • Self-Sufficiency: Every feature holds all its relevant files in one place.
  • Scalability: Add new features without affecting others.
  • Ease of Maintenance: Changes are confined to the respective feature.
  • IFrame Integration: Simple and effective iframe support with ResourceTracker and ErrorHandler.

Touch-First Ergonomics

  • Responsive Navigation: Multi-view sheet system that adapts to user intent.
  • Gesture Control: Natural swipe actions for a fluid mobile experience.
  • Keyboard Awareness: Layout shifts automatically to remain accessible during input.

Smart Desktop Access

  • High Availability: Core features accessible via a persistent, non-intrusive FAB.
  • Position Persistence: UI state and positioning remembered across sessions.

Element Detection Service

  • Single Source of Truth: All selectors are defined in ElementDetectionConfig.js.
  • Performance Optimization: Eliminates redundant DOM queries and uses caching for results.
  • Consistency: All components use the same detection logic.

Shared Systems

  • No Duplication: Common systems reside in a single location.
  • Consistency: The same API is used across all features.
  • Stability: Controlled changes in core systems.

Smart Handler Registration

  • Memory Optimization: Only essential handlers are active.
  • Real-Time Updates: Settings changes applied without needing a page refresh.
  • Error Isolation: Failure in one feature doesn't break others.

Content Script Smart Loading

  • Minimal Entry: Content entry point with a ~5KB footprint.
  • Feature Categorization: Priority-based loading (CRITICAL, ESSENTIAL, ON_DEMAND).
  • Memory Optimization: 20-30% improvement in memory consumption.

Toast Integration System

  • Actionable Notifications: Interactive buttons for "cancel" and "action."
  • Cross-Context Support: Unified usage across all contexts and iframes.

Translation Service

  • Centralized Coordination: All requests coordinated through UnifiedTranslationService.
  • Duplicate Prevention: TranslationRequestTracker prevents redundant processing.
  • Intelligent Routing: Results delivered based on translation mode (Field, Select Element, Standard).
  • Streaming Coordination: Supports streaming for large translations.

Subtitle Translation System

  • Standalone Architecture: Operates as a decoupled, high-performance app for large file processing.
  • Progressive Batching: Intelligent chunking of subtitle cues to optimize provider character limits.
  • Format Preservation: Advanced "Text Protection" system for safeguarding SRT timestamps and HTML/style tags.
  • Real-Time Progress: Live UI updates with dynamic ETA and per-cue status tracking.

Structured Logging

  • Production Performance: Linear formatting and level-gating ensure zero performance hit in production while maintaining high debuggability.

CSS Architecture Benefits

  • Shadow DOM Isolation: Components are completely isolated from page styles.
  • Strategic !important Usage: Used only for critical properties within the Shadow DOM.
  • Dynamic Direction Support: Content maintains direction while UI remains LTR.

Technical Specifications

  • Manifest V3: The new browser standard.
  • Vue.js 3 & Pinia: Reactive frontend and modern state management.
  • Cross-Browser: Compatible with Chrome and Firefox.
  • Touch-Optimized: Native-like performance on touch devices.
  • Modular Logging: Components-based logging with production awareness.
  • Advanced Memory Management: ResourceTracker and Memory Garbage Collector with integrated Critical Protection System.
  • TTS System: Full cross-context coordination and auto-language fallback.

Translation Architecture Guardrails

Concise contributor rules to prevent architectural drift. Full rationale: see ADR-015, TRANSLATION_PROVIDER_LOGIC.md, and the contract documents linked above.

  • Use V3IntervalParser for V3 marker/interval parsing; it is structural-only. Do not create feature- or provider-specific V3 parsers.
  • TranslationContractValidator is the single semantic owner of V3 provider-contract validity (marker count/identity/order/duplicates/missing/unexpected, interval content, V3_EMPTY_TRANSLATED_INTERVAL). Do not independently validate these in DOM, feature, or provider-adapter code.
  • BaseAIProvider owns structured-recovery policy and must not branch on V3-specific violation codes or marker semantics.
  • Keep response identities distinct: logical IDs, positional wire IDs (numeric transport IDs valid only in proven positional-wire batches), V3 member IDs; requestIndex and responseId are separate concepts. Do not treat numeric response IDs as globally valid logical IDs.
  • repairContext is generic, transient recovery metadata. The parser packages facts, BaseAIProvider transports them, AIConversationHelper renders repair guidance. It does not enter normal conversation history or become provider memory.
  • Do not conflate structured recovery, QueueManager retry, API-key failover, or automatic cross-provider fallback. Structured recovery is provider-local; queue retry is execution retry; no cross-provider fallback is automatic.
  • Invalid structured/V3 results must not become stream-visible; OptimizedJsonHandler enforces the canonical pre-stream validation boundary.