### Setup and Initial Build

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Steps to fork, clone, and set up the PDFx project locally. Includes installing dependencies, building the project, and starting the development server.

```bash
# 1. Fork on GitHub (click the Fork button on github.com/akii09/pdfx)

# 2. Clone your fork
git clone https://github.com/<your-username>/pdfx.git
cd pdfx

# 3. Add upstream so you can sync later
git remote add upstream https://github.com/akii09/pdfx.git

# 4. Install and build
pnpm install
pnpm build
pnpm dev
```

--------------------------------

### Start Development Server

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Starts the development server for the www application to preview changes locally.

```bash
pnpm dev:www
```

--------------------------------

### Initialize PDFx CLI

Source: https://github.com/akii09/pdfx/blob/main/packages/cli/README.md

Run this command to initialize the PDFx configuration and setup in your project.

```bash
npx pdfx-cli@latest init
```

--------------------------------

### PDFx Common Development Commands

Source: https://github.com/akii09/pdfx/blob/main/AGENTS.md

Lists essential command-line instructions for developing with PDFx, covering starting the documentation site, rebuilding the registry, running tests, type checking, linting, and formatting.

```bash
pnpm dev:www            # Start docs site locally
pnpm build:registry     # Rebuild all registry JSON files
pnpm test               # Run full test suite
pnpm typecheck          # TypeScript type checking
pnpm lint               # Biome lint
pnpm format             # Biome format
```

--------------------------------

### Initialize PDFx Project

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Initializes a new PDFx project, creating the necessary configuration file and theme.

```bash
npx pdfx-cli init
```

--------------------------------

### Initialize and Add Components with PDFx CLI

Source: https://github.com/akii09/pdfx/blob/main/README.md

Use the PDFx CLI to initialize a new project and add components like headings, text, and badges.

```bash
npx pdfx-cli init
npx pdfx-cli add heading text badge
```

--------------------------------

### Add All Components

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Adds all available PDFx components to your project simultaneously.

```bash
npx pdfx-cli add --all
```

--------------------------------

### List Available Components

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Displays a list of all PDFx components that can be added to your project.

```bash
npx pdfx-cli list
```

--------------------------------

### PDFx CLI Commands Overview

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

This table lists the available PDFx CLI commands and their primary functions, ranging from project initialization to component and theme management.

```bash
pdfx init
pdfx add <component>
pdfx add --all
pdfx list
pdfx diff <component>
pdfx theme init
pdfx theme switch <name>
pdfx theme validate
pdfx block add <id>
pdfx block list
```

--------------------------------

### Basic PDF Document Structure with PDFx Components

Source: https://github.com/akii09/pdfx/blob/main/README.md

Demonstrates how to create a basic PDF document using PDFx components within a React application. Ensure you have the necessary components imported.

```tsx
import { Document, Page } from '@react-pdf/renderer';
import { Heading, Text, Badge } from './components/pdfx';

export default () => (
  <Document>
    <Page>
      <Heading level={1}>Invoice #1042</Heading>
      <Badge label="Paid" variant="success" />
      <Text>Thank you for your business.</Text>
    </Page>
  </Document>
);
```

--------------------------------

### Initialize MCP AI Agent Integration

Source: https://github.com/akii09/pdfx/blob/main/packages/cli/README.md

Initialize the Model Context Protocol (MCP) for AI Agent integration with PDFx.

```bash
npx pdfx-cli@latest mcp init --client cursor
```

--------------------------------

### Common PDFx Development Commands

Source: https://github.com/akii09/pdfx/blob/main/CLAUDE.md

Provides a list of essential commands for local development, building, testing, and maintaining the PDFx project.

```bash
pnpm dev:www            # Start docs site locally
pnpm build:registry     # Rebuild all registry JSON files
pnpm test               # Run full test suite
pnpm typecheck          # TypeScript type کردن
pnpm lint               # Biome lint
pnpm format             # Biome format
```

--------------------------------

### List Available Blocks

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Displays a list of all pre-built PDF blocks that can be added to your project.

```bash
npx pdfx-cli block list
```

--------------------------------

### PDFx Package Layout

Source: https://github.com/akii09/pdfx/blob/main/ARCHITECTURE.md

Illustrates the directory structure for shared types, the CLI, and the documentation/registry website.

```treeview
packages/shared/        types, Zod schemas, theme presets
                        imported by both packages/cli and apps/www

packages/cli/           pdfx CLI (pdfx add, pdfx block add, pdfx theme ...)
                        fetches component JSON from the HTTPS registry
                        never imports from apps/www directly

apps/www/               docs site + registry server (Vite + React)
  src/
    registry/
      components/       component source — the copy-paste target
      blocks/           block template source
      index.json        registry manifest (name, type, files, deps)
    lib/
      build-registry.ts transforms registry/components/ into public/r/*.json
  public/
    r/                  HTTP-served JSON consumed by the CLI
```

--------------------------------

### PDFx Project Architecture Overview

Source: https://github.com/akii09/pdfx/blob/main/AGENTS.md

Illustrates the directory structure and main responsibilities of different packages within the PDFx project. The documentation site and registry server are in 'apps/www', the CLI is in 'packages/cli', and shared types are in 'packages/shared'.

```text
apps/www           → Documentation site + registry server (Next.js)
packages/cli       → CLI / MCP server (pdfx-cli on npm)
packages/shared    → Cross-package types & schemas (Zod)
```

--------------------------------

### Run All Tests

Source: https://github.com/akii09/pdfx/blob/main/ARCHITECTURE.md

Command to execute all tests across the project, including components, registry transforms, and CLI commands.

```bash
pnpm test
```

--------------------------------

### Pre-PR Checks and Build

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Run these commands before submitting a Pull Request to ensure code quality, type safety, and successful build.

```bash
pnpm lint && pnpm typecheck && pnpm test && pnpm build
```

--------------------------------

### Rules for New PDFx Components

Source: https://github.com/akii09/pdfx/blob/main/AGENTS.md

Provides specific guidelines for creating new components, including when to use the 'Pdf' prefix, when to omit it, the importance of not renaming existing components, and documenting naming decisions.

```markdown
1. **Use `Pdf` prefix** if the name collides with an HTML element, a React built-in, or a
   @react-pdf/renderer primitive (e.g. `Image` → `PdfImage`, `Text` exists in renderer →
   our `Text` is fine because it's the _same concept_).
2. **Skip the prefix** if the name is unique to PDFx's domain (e.g. `KeyValue`, `DataTable`).
3. **Never rename existing components** — that would be a breaking change for installed users.
4. Document the naming decision in the component's JSDoc.
```

--------------------------------

### Add Pre-Composed PDFx Blocks

Source: https://github.com/akii09/pdfx/blob/main/packages/cli/README.md

Add full, pre-composed PDFx templates like invoices or reports to your project.

```bash
npx pdfx-cli@latest block add invoice-modern
npx pdfx-cli@latest block add report-financial
```

--------------------------------

### PDFx Project Architecture Overview

Source: https://github.com/akii09/pdfx/blob/main/CLAUDE.md

Provides a high-level overview of the PDFx project's directory structure and the primary function of each package.

```text
apps/www           → Documentation site + registry server (Next.js)
packages/cli       → CLI / MCP server (pdfx-cli on npm)
packages/shared    → Cross-package types & schemas (Zod)

```

--------------------------------

### Add Specific PDFx Components

Source: https://github.com/akii09/pdfx/blob/main/packages/cli/README.md

Use these commands to add individual PDFx components directly into your local codebase.

```bash
npx pdfx-cli@latest add badge
npx pdfx-cli@latest add table form qrcode
```

--------------------------------

### Registry Build Process

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Details the workflow for transforming component source files into a JSON registry served by the website and consumed by the CLI. This process ensures consistency between source and distributed components.

```typescript
1. Component source lives in `apps/www/src/registry/components/<name>/`
2. `pnpm build:registry` runs `build-registry.ts` which transforms source into `public/r/<name>.json`
3. `pdfx add <name>` fetches that JSON over HTTPS and writes the files into the user's project
4. No PDFx package is installed — the user owns the code from that point
```

--------------------------------

### Switch Theme

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Switches the active theme for PDFx components to a different preset.

```bash
npx pdfx-cli theme switch modern
```

--------------------------------

### Component File Structure

Source: https://github.com/akii09/pdfx/blob/main/ARCHITECTURE.md

Shows the standard organization for individual component files, including types, styles, implementation, and tests.

```treeview
components/<name>/
  <name>.types.ts     exported TypeScript interfaces
  <name>.styles.ts    StyleSheet factory function
  <name>.tsx          component implementation
  <name>.test.tsx     smoke tests
  index.ts            barrel export
```

--------------------------------

### PDFx Repository Structure

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Illustrates the directory layout of the PDFx project, highlighting key areas such as the documentation site, component sources, CLI package, and shared utilities.

```tree
pdfx/
  apps/
    www/                     # Docs site + registry server (Vite React SPA)
      src/registry/
        components/          # 24 component source files (source of truth)
        blocks/              # 10 block template source files
        index.json           # Registry manifest
      src/lib/
        build-registry.ts    # Transforms source → public/r/*.json
      public/r/              # HTTP-served JSON consumed by the CLI
  packages/
    shared/                  # Types, theme presets, Zod schemas, errors
    cli/                     # pdfx-cli — all CLI commands
  docs/                      # Architecture and decision docs
```

--------------------------------

### Add a Pre-built Block

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Adds a complete, pre-built PDF document block, such as an invoice, to your project.

```bash
npx pdfx-cli block add invoice-modern
```

--------------------------------

### PDFx Data Flow

Source: https://github.com/akii09/pdfx/blob/main/ARCHITECTURE.md

Details the process from component source to its availability in the user's project via the CLI.

```treeview
apps/www/src/registry/components/<name>/<name>.tsx   (source of truth)
         |
         └── build-registry.ts  (pnpm build:registry)
               |  strips @pdfx/shared imports, inlines shared helpers
               v
         public/r/<name>.json                (served over HTTPS)
               |
               └── pdfx add <name>           (CLI fetches JSON, writes files)
                     v
         user-project/src/components/pdfx/<name>/   (component lives here)
```

--------------------------------

### Add Invoice Blocks

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Commands to add various pre-built invoice block types to your project.

```bash
npx pdfx-cli block add invoice-classic
npx pdfx-cli block add invoice-modern
npx pdfx-cli block add invoice-minimal
npx pdfx-cli block add invoice-corporate
npx pdfx-cli block add invoice-creative
npx pdfx-cli block add invoice-consultant
```

--------------------------------

### Add Report Blocks

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Commands to add various pre-built report block types to your project.

```bash
npx pdfx-cli block add report-financial
npx pdfx-cli block add report-marketing
npx pdfx-cli block add report-operations
npx pdfx-cli block add report-security
```

--------------------------------

### Add a Single Component

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Adds a specific PDFx component to your project. The component's source code is copied directly into your codebase.

```bash
npx pdfx-cli add table
```

--------------------------------

### PDFx Component Naming Convention Rules

Source: https://github.com/akii09/pdfx/blob/main/AGENTS.md

Explains the rules for naming new PDFx components, focusing on prefixing with 'Pdf' when names might collide with existing React, HTML, or @react-pdf/renderer exports. Unique domain names do not require a prefix.

```markdown
| Category | Components |
|---|---|
| **Prefixed** (`Pdf*`) | PdfAlert, PdfCard, PdfForm, PdfGraph, PdfImage, PdfList, PdfPageNumber, PdfQRCode, PdfSignatureBlock, PdfWatermark |
| **Unprefixed** | Badge, DataTable, Divider, Heading, KeepTogether, KeyValue, Link, PageBreak, PageFooter, PageHeader, Section, Stack, Table, Text |
```

--------------------------------

### Bug-fix Workflow Steps

Source: https://github.com/akii09/pdfx/blob/main/CLAUDE.md

Details the systematic process for addressing and resolving bugs within the PDFx project, emphasizing reproduction, root cause analysis, testing, and verification.

```markdown
1. **Reproduce first.** Read the failing component, run its existing test, and confirm
 the bug exists before changing code. If you cannot reproduce, ask for a minimal repro
 instead of guessing.
2. **Locate the root cause.** Use `Explore` / grep across the registry, `packages/shared`,
 and `packages/cli` — many bugs surface in a component but originate in shared types,
 the registry transform ([build-registry.ts](apps/www/src/lib/build-registry.ts)), or
 theming.
3. **Write or extend a test** that fails because of the bug, then make it pass. Tests live
 beside the component as `<name>.test.tsx`.
4. **Rebuild the registry** with `pnpm build:registry` if the fix touches a registry
 component, and skim the resulting JSON diff to confirm only the intended files changed.
5. **Verify gates:** `pnpm test`, `pnpm typecheck`, `pnpm lint`. Report each as
 pass/fail in your summary.
6. **Hand off.** Summarize the root cause, the fix, and the test in 3–5 lines. Suggest
 the commit message and stop. **Do not commit.** (See Rule 1.)
```

--------------------------------

### PDFx Component File Structure

Source: https://github.com/akii09/pdfx/blob/main/AGENTS.md

Details the standard file organization for each PDFx component, promoting a segregated file pattern. Each component typically includes implementation, styles, types, tests, and an index file.

```text
apps/www/src/registry/components/<name>/
  <name>.tsx        — Component implementation (the main export)
  <name>.styles.ts  — StyleSheet factory function
  <name>.types.ts   — TypeScript interfaces and type aliases
  <name>.test.tsx   — Vitest unit tests
  index.ts          — Barrel re-exports
```

--------------------------------

### Create Widget Component

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Implements a reusable widget component that accepts a label and variant. It uses theme context for styling and memoization for performance.

```tsx
// my-widget.tsx
import { Text as PDFText, View } from '@react-pdf/renderer';
import type { Style } from '@react-pdf/types';
import { usePdfxTheme, useSafeMemo } from '../../lib/pdfx-theme-context';
import { resolveColor } from '../../lib/resolve-color';
import { createMyWidgetStyles } from './my-widget.styles';
import type { MyWidgetProps } from './my-widget.types';

export function MyWidget({ label, variant = 'default', style }: MyWidgetProps) {
  const theme = usePdfxTheme();
  const styles = useSafeMemo(() => createMyWidgetStyles(theme), [theme]);

  const containerStyles: Style[] = [
    styles.container,
    variant === 'primary' ? styles.variantPrimary : styles.variantDefault,
  ];
  if (style) containerStyles.push(...[style].flat());

  return (
    <View style={containerStyles}>
      <PDFText style={styles.text}>{label}</PDFText>
    </View>
  );
}
```

--------------------------------

### Keeping Fork Synced

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Commands to fetch the latest changes from the upstream repository and rebase your local branch to stay up-to-date.

```bash
git fetch upstream
git rebase upstream/main
```

--------------------------------

### Access Theme Tokens

Source: https://github.com/akii09/pdfx/blob/main/apps/www/public/llms.txt

Demonstrates how to access theme tokens within a React component using the `usePdfxTheme` hook.

```typescript
const theme = usePdfxTheme();
// theme.colors.primary, theme.spacing.md, theme.typography.body.fontSize, ...
```

--------------------------------

### Create Widget Styles

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Defines styles for a custom widget using the provided theme. Ensures consistent styling across the application by leveraging theme primitives and colors.

```typescript
// my-widget.styles.ts
import type { PdfxTheme } from '@pdfx/shared';
import { StyleSheet } from '@react-pdf/renderer';

export function createMyWidgetStyles(t: PdfxTheme) {
  const { spacing } = t.primitives;

  return StyleSheet.create({
    container: {
      padding: spacing[3],
      borderRadius: t.primitives.borderRadius.md,
    },
    variantDefault: { backgroundColor: t.colors.muted },
    variantPrimary: { backgroundColor: t.colors.primary },
    text: {
      fontFamily: t.typography.body.fontFamily,
      fontSize: t.typography.body.fontSize,
      color: t.colors.foreground,
    },
  });
}
```

--------------------------------

### Create Git Branch

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Creates a new feature branch for development following the Conventional Commits standard.

```bash
git checkout -b feat/my-widget
```

--------------------------------

### Widget Smoke Tests

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Provides basic smoke tests for the MyWidget component to ensure it renders without errors and accepts different props.

```tsx
// my-widget.test.tsx
import { describe, expect, it } from 'vitest';
import { MyWidget } from './my-widget';

describe('MyWidget', () => {
  it('renders without throwing', () => {
    expect(() => MyWidget({ label: 'Hello' })).not.toThrow();
  });

  it('accepts variant prop', () => {
    expect(() => MyWidget({ label: 'Hello', variant: 'primary' })).not.toThrow();
  });
});
```

--------------------------------

### Registry Transform Function Logic

Source: https://github.com/akii09/pdfx/blob/main/AGENTS.md

Outlines the transformations applied by `transformForRegistry` in `apps/www/src/lib/build-registry.ts` to component source code before it's written to the registry JSON files. This includes inlining types, rewriting paths, and resolving colors.

```text
- Strips `@pdfx/shared` imports and inlines `PDFComponentProps`
- Injects `import type React from 'react'` when `React.*` types are used
- Rewrites workspace-relative paths to user-project paths
- Inlines `PdfxTheme` as `ReturnType<typeof usePdfxTheme>`
- Inlines `resolveColor` utility
```

--------------------------------

### Register Component in Registry

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Registers the MyWidget component in the application's component registry for use in the www app.

```typescript
export { MyWidget } from './my-widget/index';
```

```typescript
export type { MyWidgetProps, MyWidgetVariant } from './my-widget/index';
```

```json
{
  "name": "my-widget",
  "type": "registry:ui",
  "title": "MyWidget",
  "description": "Short description.",
  "files": [
    { "path": "components/my-widget/my-widget.tsx", "type": "registry:component" },
    { "path": "components/my-widget/my-widget.styles.ts", "type": "registry:component" },
    { "path": "components/my-widget/my-widget.types.ts", "type": "registry:component" }
  ],
  "dependencies": [],
  "registryDependencies": []
}
```

--------------------------------

### Barrel Export for Widget

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Exports the MyWidget component and its associated types from the index file for easier importing.

```typescript
// index.ts
export { MyWidget } from './my-widget';
export type { MyWidgetProps, MyWidgetVariant } from './my-widget.types';
```

--------------------------------

### Component Types Definition

Source: https://github.com/akii09/pdfx/blob/main/CONTRIBUTING.md

Defines TypeScript interfaces for a new component, including its props and variants. Ensures type safety and clear prop definitions.

```typescript
// my-widget.types.ts
import type { PDFComponentProps } from '@pdfx/shared';

export type MyWidgetVariant = 'default' | 'primary';

/**
 * Short description of what this component renders.
 * Props - `label` | `variant` | `style`
 * @see {@link MyWidgetProps}
 */
export interface MyWidgetProps extends Omit<PDFComponentProps, 'children'> {
  label: string;
  /**
   * @default 'default'
   */
  variant?: MyWidgetVariant;
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.