# .clinerules

## Project Overview
- This repository hosts the pdfme libraries, which are distributed under multiple npm packages and developed in TypeScript.
- The libraries must function in both browser and Node.js environments.
- The core libraries rely on a forked version of [pdf-lib](https://pdf-lib.js.org/) (@pdfme/pdf-lib) to handle PDF rendering, including CJK font and SVG support.
- Official documentation references http://pdfme.com/
- The codebase includes:
  - **packages** directory: Contains the main libraries classified as:
    1. **@pdfme/generator, @pdfme/schemas, @pdfme/ui** – Tools for generating PDFs from JSON templates and designing templates/UI.
    2. **@pdfme/manipulator, @pdfme/converter** – Utilities for PDF manipulation (merge, split, convert to images, etc.).
    3. **@pdfme/common** – Common logic and shared types.
  - **website** directory: Docusaurus-based site at https://pdfme.com/ for official docs.
  - **playground** directory: React SPA for e2e tests, demos, and development checks.

## Development Guidelines

1. **Minimize Maintenance Overhead**
   - Avoid adding new dependencies unless strictly necessary. Provide a strong justification if a dependency is added.
   - Write as little code as possible. Remove or unify code that is not essential.
   - Shared functionality across packages should be relocated to **@pdfme/common**.
   - Only add tests that are truly needed for coverage. Avoid redundant or trivial tests.

2. **Functions and Interfaces**
   - Prefer pure functions without side effects for ease of unit testing.
   - Keep functions minimal, focusing on clarity and testability.
   - Any public function or interface modifications must be reflected in the documentation (under `website/docs`).

3. **Browser and Node.js Support**
   - Ensure all libraries work seamlessly in both the browser and Node.js.

4. **Code Formatting**
   - Do not include unnecessary formatting changes in commits.
   - Use `npm run prettier` at the root level as the project's definitive formatting tool.

5. **Build and Test Requirements**
   - Pass `npm run build` and `npm run test` at the root level before merging changes.
   - Ensure no introduced changes break existing functionality in any package.

6. **Documentation Consistency**
   - When modifying or publishing any public API, confirm there is no conflict with existing docs in `website/docs`.
   - Update the documentation as needed to reflect interface changes.

7. **Minimal Scope Changes**
   - Keep PRs and commits scoped to the smallest functional update. 
   - Refrain from adding extraneous code or merging unrelated changes.

## Security and Maintenance
- Focus on secure implementation since many users will view and utilize this code.
- Always protect sensitive files (e.g., .env, credentials).
- Follow best practices in code organization, architecture, and testing.

## Cline Memory Bank
- Use Cline Memory Bank to track project context and progress.
- Memory Bank consists of the following Markdown files:
  - **projectbrief.md**: Defines project scope and purpose
  - **productContext.md**: Problems solved, features, UX goals
  - **activeContext.md**: Current work focus, recent changes, next steps
  - **systemPatterns.md**: Architecture, technical decisions, design patterns
  - **techContext.md**: Technologies used, development setup, constraints
  - **progress.md**: Feature status, remaining work, current status

## Memory Bank Update Guidelines
- When discovering new project patterns
- After implementing significant changes
- When context clarification is needed
- When "update memory bank" command is requested (review all files)

## Project Intelligence
- Critical implementation paths: Each package in packages/ has clearly defined responsibilities
- User settings and workflows: Provides intuitive APIs for template design and generation
- Project-specific patterns: Modularized package structure, minimal dependencies
- Known issues: Limitations with complex PDF layouts, partial support for advanced PDF features
