# Agent Instructions: PSP Project

This document provides essential context and guidelines for AI agents working on the PSP (Payment Service Provider) project.

## Project Purpose
A multi-module Android application for specialized POS (Point of Sale) hardware, providing a bridge between a Web-based POS interface and native hardware features (Thermal Printing & Payment Terminal).

## Architecture Overview
The project follows **Dependency Inversion** principles. Features are defined as interfaces in `:core` and implemented in hardware-specific modules like `:p3` or `:ps4`.

### Key Modules
- **`:core`**: Shared domain models (`PrintEntity`, `PaymentResultEntity`) and interfaces (`PspService`, `Printer`).
- **`:design_system`**: Contains `PspWebView` and the `PspJavaScriptInterface` (Web-Native Bridge).
- **`:p3` / `:ps4`**: Hardware SDK integrations.
- **`:app` / `:tis_app` / `:stage_app`**: Application entry points and Hilt dependency configuration.

## Critical Classes & Interfaces

### 1. Web-Native Bridge
- **`PspWebView.kt`**: The core component. Uses a `WebViewManager` for pooling and is highly optimized for weak hardware.
- **`PspJavaScriptInterface.kt`**: Defines the methods exposed to JavaScript (`pay`, `print`, `reload`, `uuid`).
  - **Important**: Methods must be annotated with `@JavascriptInterface` and `@Keep`.
  - **Note**: Numbers from JS arrive as `Double`.

### 2. Printer Implementation (`:p3`)
- **`P3Printer.kt`**: Implements the `Printer` interface.
- **`POIPrinterManager`**: The vendor SDK class.
- **Font Handling**: Use `getFontPath(resourceName: String)` to copy fonts from `res/font` to internal storage before passing the path to the SDK.
- **Logo Rendering**: Use `drawableToBitmap()` to handle VectorDrawables correctly.

### 3. Payment Service (`:p3`)
- **`Ps3Service.kt`**: Implementation of `PspService`.
- **`IapPosService.kt`**: Handles communication with the underlying POS payment application.

## Common Agent Tasks

### Adding a new Bridge Method
1. Add the method to `PspJavaScriptInterface.kt` with `@JavascriptInterface` and `@Keep`.
2. Update the constructor of `PspJavaScriptInterface` to take a lambda.
3. Update `PspWebView.kt` to pass the lambda from the UI layer.

### Optimizing for Weak Hardware
When performance issues arise in the WebView:
1. Check `WebViewManager.kt` settings.
2. Ensure `setLayerType(View.LAYER_TYPE_HARDWARE, null)` is set.
3. Keep `setOffscreenPreRaster(false)` for very weak hardware to save RAM.
4. Ensure `loadUrl` is NOT called in the `AndroidView.update` block (use `LaunchedEffect` instead).

## Development Rules
- **RTL Support**: The printer uses Persian/Arabic text. Always ensure numbers are converted to Persian digits using `toPersianDigits()` where appropriate.
- **Dependency Injection**: Use Hilt for all service injections. Do not instantiate implementation classes (`P3Printer`, `Ps3Service`) directly in the app modules.
- **WebView Lifecycle**: Always release WebViews back to the `WebViewManager` in `onDispose`.

## Mocking in `:stage_app`
- Use `StageViewModel` to return success/failure mocks for payment results without requiring physical hardware.
- Use the `PaymentResultEntity.success()` or `PaymentResultEntity.failure()` factory methods.