pagyra-js 0.0.1

package/docs/AGENTS.md

@@ -0,0 +1,288 @@
+# AGENTS.md — Project Rules for Coding Agents
+
+> This document defines how autonomous coding agents should work in this repository:
+> goals, constraints, folder structure, coding style, tests, error handling, and
+> what you *must* do before opening a PR.
+
+---
+
+## 1) Mission & Scope
+
+- **Mission:** Convert **HTML + CSS** into **deterministic PDF** bytes via a clean pipeline:
+  `HTML → DOM → CSSOM → Cascade → StyledTree → Layout (+pagination) → DisplayList → PDF`.
+- **Out of scope:** Executing JavaScript from HTML, fetching the open internet beyond allowed inputs,
+  adding heavy dependencies without explicit instructions, or breaking determinism.
+
+---
+
+## 2) Repository Layout (authoritative)
+
+Use and keep these boundaries stable:
+
+```
+/src/core.ts          # Core exports and main types
+/src/html-to-pdf.ts   # Main HTML to PDF conversion pipeline
+/src/index.ts         # Public API entry point
+/src/html/            # HTML parsing and DOM conversion (using linkedom)
+/src/css/             # CSS parsing, cascade, shorthands, specificity
+/src/layout/          # Layout computation (block/inline layout, positioning)
+/src/dom/             # DOM node representation and manipulation
+/src/pdf/             # PDF generation, rendering, and primitives
+/src/fonts/           # Font handling, embedding, subsetting, metrics
+/src/image/           # Image decoding (PNG, JPEG, WebP), processing
+/src/svg/             # SVG parsing and rendering support
+/src/assets/          # Built-in assets (fonts, images)
+/src/compression/     # Data compression utilities (deflate, brotli)
+/src/config/          # Configuration interfaces
+/src/debug/           # Debugging and audit utilities
+/src/geometry/        # Geometric calculations (boxes, matrices)
+/src/logging/         # Logging utilities
+/src/orchestrator/    # Pipeline coordination
+/src/paint-order/     # Paint order management
+/src/render/          # Render tree operations and transformations
+/src/style/           # Style computation and inheritance
+/src/text/            # Text processing and line breaking
+/src/transform/       # Transformation utilities
+/src/types/           # Type definitions
+/src/units/           # Unit conversion and page utilities
+/tests/helpers/       # Test utilities and helpers
+/tests/layout/        # Layout-specific tests
+/tests/pdf/           # PDF-specific tests
+/scripts/             # Development scripts and utilities
+/playground/          # Interactive development server
+/playground/public/examples/ # HTML examples for testing
+/examples/            # Example files (if any)
+```
+
+Do **not** restructure without updating this file and the README.
+
+---
+
+## 3) Pipeline Contracts (inputs/outputs)
+
+### 3.1 Input Loader
+- **In:** `RenderHtmlOptions` with HTML string, CSS string, viewport/page dimensions, margins, font config
+- **Out:** `PreparedRender` with layout root, render tree, and page size in points
+- **Errors:** `E_HTML_EMPTY`, `E_FETCH_FAILED`
+
+### 3.2 HTML → DOM
+- **Library:** Uses linkedom for HTML parsing (no JS execution)
+- **Rules:** Preserve whitespace where CSS `white-space` requires; normalize HTML fragments to full documents
+- **Error:** `E_HTML_SYNTAX` (recover if possible; warn + continue).
+
+### 3.3 CSS Resolution
+- Sources: `<style>`, `style=""` attributes, linked styles, UA styles.
+- **Ordering:** UA < author < inline, specificity, `!important`.
+- **Minimum selectors:** type/class/id, **descendant `A B`**, **child `A > B`**.
+- **Shorthands:** border, margin, padding, background, font, etc.
+- **@font-face:** Support for font loading and embedding from CSS
+
+### 3.4 Style Computation (Cascade)
+- **Out:** DOM nodes with computed styles attached
+- **Normalize:** units (px internally), shorthands → longhands, inheritance, font face definitions
+
+### 3.5 Layout & Pagination
+- Flow layout, line boxes, absolute/fixed positioning, page fragments.
+- **Stacking contexts & z-index:** negative < 0 < positive; follow paint order rules.
+- **Recoverable overflow:** report `E_LAYOUT_OVERFLOW` (warn) and continue.
+
+### 3.6 Render Tree Construction
+- **Order:** backgrounds → borders → text → decorations → images/shadows.
+- Generate **deterministic** render tree per page with proper offsets and margins applied.
+
+### 3.7 PDF Writer
+- Embed/subset fonts; compress streams; valid xref; metadata/XMP if present.
+- **Out:** `Uint8Array` (PDF).
+- **No partial PDF** on fatal errors.
+
+---
+
+## 4) Determinism & Seeds
+
+- Internal units = **px**. Convert `px → pt` only in PDF writer (default `1px = 0.75pt`).
+- When `seed` is provided, **same input ⇒ same output bytes**.
+- Do not include timestamps/volatile IDs unless explicitly normalized.
+
+---
+
+## 5) Fonts & Text
+
+- Font handling via FontEmbedder with support for TTF, WOFF, and WOFF2 formats
+- Always subset embedded fonts; keep cmap/metrics consistent.
+- Support for @font-face rules with font loading from URLs or local files
+- Provide sane fallbacks for missing glyphs.
+- Respect normalized font-weight steps (100..900); snap non-integer weights to nearest step.
+- Font loading supports data URIs, HTTP URLs, and local file paths
+
+---
+
+## 6) Colors, Backgrounds & Shadows
+
+- Work in **sRGB** internally; writer maps to DeviceRGB/ICC.
+- Background shorthand may include **colors**, **images (url(...))**, and **linear-gradients**.
+- `box-shadow` layers supported; `none` disables.
+
+---
+
+## 7) CSS Conventions & Notable Rules
+
+- `z-index`: accepts **integer** values or `auto`. Non-integers (e.g., `"2.0"`) are ignored.
+- Shorthands must expand correctly (border, margin/padding, background, font).
+- **Selectors supported:** tag names, `#id`, `.class`, `[attr]`, `:first-child`, `:last-child`, `:nth-child`, `:not()`, `:root`, descendant (`A B`), child (`A > B`), adjacent sibling (`A + B`), and general sibling (`A ~ B`) combinators
+- **Display values:** `block`, `inline`, `inline-block`, `flex`, `inline-flex`, `grid`, `inline-grid`, `table`, `inline-table`, `table-row-group`, `table-header-group`, `table-footer-group`, `table-row`, `table-cell`, `table-caption`, `list-item`, `none`, `flow-root`
+- **Position values:** `static`, `relative`, `absolute`, `fixed`, `sticky`
+- **Float values:** `none`, `left`, `right`, `inline-start`, `inline-end`
+- **Table displays for `table`, `tbody/thead/tfoot`, `tr`, `td/th` are forced to canonical display types when overridden improperly.
+- Defaults approximate UA styles (headings, paragraphs, lists, inline elements, tables, etc.).
+- **CSS Variables:** Supported via `--custom-property` syntax and `var()` function with fallback support. Variables are inherited and resolved at computed style time.
+
+---
+
+## 8) Error Policy
+
+- Prefer **warn and continue** (collect `warnings: string[]`) when safe.
+- Fatal errors have stable codes `E_*` and never produce partial PDFs.
+- All thrown errors must include: `code`, brief `message`, and optional `details`.
+
+## 8.5) Logging & Debugging
+
+- **Log levels:** `trace`, `debug`, `info`, `warn`, `error` (in increasing order of severity)
+- **Log categories:** `parse`, `style`, `layout`, `paint`, `font`, `encoding`, `pdf` (case-insensitive)
+- **Debug configuration:** Use `configureDebug({ level: LogLevel, cats: string[] })` to set runtime logging
+- **Playground debugging:** Use `--debug-level` and `--debug-cats` flags with `npm run playground:render`
+- **Log output:** Colored console output with level and category prefixes for easy identification
+
+---
+
+## 9) Tooling & Scripts
+
+**Do not** reinvent commands; use these NPM scripts:
+
+```jsonc
+{
+  "scripts": {
+    "build": "tsc",
+    "start": "node ./dist/index.js",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "eslint src tests --ext .ts,.js",
+    "test": "vitest run",
+    "playground": "tsx playground/server.ts",
+    "playground:render": "tsx scripts/render-playground-example.ts",
+    "validate": "npm run lint && npm test"
+  }
+}
+```
+
+**Note:** Run `npm run build` before testing to ensure TypeScript compilation succeeds.
+
+---
+
+## 10) Coding Style
+
+- Language: **TypeScript** (ES modules).
+- Lint/format: **ESLint + Prettier**; zero warnings on CI.
+- Logging: use the provided logger; avoid raw `console.log` in src.
+- Keep modules **SRP** (Single Responsibility Principle). Split big functions.
+
+---
+
+## 10.5) Development Workflow
+
+- **Playground:** Use `npm run playground` to start interactive development server
+  - Access at `http://localhost:3000` (or configured port) for visual testing
+  - Hot reload for rapid iteration on HTML/CSS inputs
+  - Render specific examples with `npm run playground:render`
+  - Playground render supports command-line options:
+    - `npm run playground:render [example-path]` - Render a specific example from playground/public/examples/
+    - `npm run playground:render -- --debug-level debug` - Enable debug logging
+    - `npm run playground:render -- --debug-cats layout,pdf` - Enable specific debug categories (comma-separated)
+    - `npm run playground:render -- --page-width 800` - Set a custom page width in pixels
+    - `npm run playground:render -- --page-height 600` - Set a custom page height in pixels
+    - `npm run playground:render -- --margins "50"` - Set uniform margins (50px)
+    - `npm run playground:render -- --margins "20,40"` - Set vertical (20px) and horizontal (40px) margins
+    - `npm run playground:render -- --margins "20,30,40,50"` - Set top, right, bottom, and left margins individually
+    - Output PDFs are saved to `playground/exports/` directory
+  
+- **Scripts:** Development utilities in `/scripts/` directory
+  - TypeScript scripts run with `tsx` for direct execution without compilation
+  - May write output files for debugging/validation purposes
+
+- **Build & Test Cycle:**
+  1. Make changes in `/src/`
+  2. Run `npm run build` to compile TypeScript
+  3. Run `npm test` for unit and e2e tests
+  4. Use playground for visual/manual verification
+  5. Run `npm run validate` before committing (lint + test)
+
+---
+
+## 11) Tests: What You Must Cover
+
+- **Unit:** CSS parsing (shorthands/longhands), specificity, cascade, layout pieces, render tree construction, PDF primitives.
+- **Layout tests:** Inline fragments, text alignment, positioning, flexbox/grid (if implemented)
+- **PDF tests:** Alignments, header/footer rendering, page breaks, font embedding
+- **E2E:** 
+  - z-index negative vs zero/positive (3+ overlapping elements).
+  - Page breaks: `page-break-*` / `break-inside: avoid`.
+  - Fonts: accents/symbols, embedding + subset, widths/metrics accuracy.
+  - Images: PNG/JPEG/WebP with/without alpha; scaling & `object-fit`.
+  - Selectors: `A B` and `A > B` with specificity ties.
+  - Determinism: snapshot binary with `seed=42`.
+
+A PR **must** add/adjust tests that reproduce any bug or validate a new feature in the appropriate test directory (`/tests/helpers/`, `/tests/layout/`, or `/tests/pdf/`).
+
+---
+
+## 12) PR & Commits
+
+- One focused change per PR.
+- Conventional commits: `feat(...)`, `fix(...)`, `test(...)`, `refactor(...)`, etc.
+- Update `CHANGELOG.md` and, if relevant, this `AGENTS.md`.
+- CI requirement: `npm run validate` **must pass**.
+
+---
+
+## 13) Security & Supply Chain
+
+- No runtime network fetches during tests except for controlled fixtures.
+- No dynamic `eval`/Function constructors.
+- Keep dependencies minimal; justify any new runtime dep in PR description.
+
+---
+
+## 14) Inputs & Artifacts
+
+- **Inputs:** `RenderHtmlOptions` with HTML string, CSS string, viewport/page dimensions, margins, font config, resource base directory, header/footer HTML
+- **Artifacts:** PDF bytes (`Uint8Array`) + metrics (timings, page count) + warnings.
+- Never write files in library code; CLIs in `/scripts/` may write to disk.
+
+---
+
+## 15) Agent Checklists (must pass)
+
+- [ ] `npm run validate` (lint + test) succeeded.
+- [ ] Coverage ≥ 80% for changed modules.
+- [ ] Deterministic snapshots unchanged (or re-baselined with reason).
+- [ ] Added/updated e2e demonstrating the change.
+- [ ] No stray logs; no partial PDF on fatal paths.
+- [ ] Documentation (README/AGENTS) updated if behavior changed.
+
+---
+
+## 16) Glossary
+
+- **StyledTree:** DOM nodes decorated with computed CSS.
+- **DisplayList:** Ordered painting operations per page.
+- **Deterministic:** Same inputs + same seed → identical PDF bytes.
+- **RenderTree:** Tree structure representing the final layout with positioning and styling applied for PDF rendering
+- **LayoutNode:** Internal representation of DOM elements with computed layout properties
+- **FontEmbedder:** Component responsible for font loading, subsetting, and embedding in PDF output
+
+---
+
+## 17) Document Maintenance
+
+- Version: `1.1.0`
+- Last updated: 2025-11-26
+- Editors: maintainers of this repo. Update alongside code changes that alter behavior.
+- Keep synchronized with `package.json` scripts and actual repository structure.

package/docs/BACKGROUND-REPEAT-IMPLEMENTATION.md

@@ -0,0 +1,127 @@
+# Background-Repeat Support Implementation Summary
+
+## Overview
+Successfully implemented complete support for the CSS `background-repeat` property in the pagyra-js HTML-to-PDF converter. The implementation covers both inline `background-repeat` declarations and the property within the `background` shorthand.
+
+## Changes Made
+
+### 1. **Added `applyBackgroundRepeat` Function** (`src/css/parsers/background-parser.ts`)
+- Created a new parser function that applies the `background-repeat` longhand property to background layers
+- Validates the repeat value against the allowed keywords: `repeat`, `repeat-x`, `repeat-y`, `no-repeat`, `space`, `round`
+- Applies to both image and gradient background layers
+- Follows the same pattern as existing background property parsers (`applyBackgroundSize`, `applyBackgroundOrigin`)
+
+### 2. **Exported Parser Function** (`src/css/parsers/background-parser-extended.ts`)
+- Imported `applyBackgroundRepeat` from the base parser
+- Created wrapper function `applyBackgroundRepeatDecl` following naming conventions
+- Made it available for registration
+
+### 3. **Registered the Parser** (`src/css/parsers/register-parsers.ts`)
+- Added `applyBackgroundRepeatDecl` to imports
+- Registered `background-repeat` property parser in `registerAllPropertyParsers()`
+- Placed it logically alongside other background properties
+
+### 4. **Comprehensive Test Coverage** (`tests/pdf/background-repeat.spec.ts`)
+- Created 11 test cases covering all functionality:
+  - All repeat modes: `repeat`, `no-repeat`, `repeat-x`, `repeat-y`, `space`, `round`
+  - Default behavior when not specified
+  - Parsing from background shorthand
+  - Application to gradients
+  - Property override scenarios
+  - Invalid value handling
+
+## Existing Infrastructure
+The implementation leverages existing, robust infrastructure:
+
+### Type Definitions
+- **`BackgroundRepeat`** type already defined in `src/css/background-types.ts`
+- Supports all standard CSS values: `repeat`, `repeat-x`, `repeat-y`, `no-repeat`, `space`, `round`
+
+### Background Layer Storage
+- **`ImageBackgroundLayer`** and **`GradientBackgroundLayer`** interfaces already include `repeat?` field
+- PDF types (`BackgroundImage`, `GradientBackground`) already have `repeat` property
+
+### Rendering Logic
+- **`computeBackgroundTileRects`** function (`src/pdf/utils/background-tiles.ts`) already handles all repeat modes
+- Properly calculates tile positions for:
+  - `no-repeat`: Single tile
+  - `repeat`: Tiles in both directions
+  - `repeat-x`: Horizontal tiling only
+  - `repeat-y`: Vertical tiling only
+  - `space` and `round`: Treated as `repeat` with a warning (per spec notes)
+
+### Integration
+- **`createBackgroundImage`** and **`createGradientBackground`** (`src/pdf/utils/background-layer-resolver.ts`)
+  - Already read `layer.repeat` and default to appropriate values
+  - Images default to `"repeat"`
+  - Gradients default to `"no-repeat"`
+
+## Testing Results
+✅ All 11 new tests passing
+✅ All existing tests still passing
+✅ No regressions introduced
+
+## Demonstration
+The feature can be demonstrated using the existing example file:
+`playground/public/examples/background-repeat-showcase.html`
+
+This file showcases:
+- `background-repeat: repeat` (default tiling behavior)
+- `background-repeat: no-repeat` (single image, centered)
+- `background-repeat: repeat-x` (horizontal tiling)
+- `background-repeat: repeat-y` (vertical tiling)
+
+## Compliance with AGENTS.md
+✅ Single Responsibility Principle maintained
+✅ TypeScript with proper type safety
+✅ Tests added with ≥80% coverage
+✅ No breaking changes
+✅ Follows existing code patterns
+✅ Build succeeds: `npm run build` ✓
+✅ Tests pass: `npm test` ✓
+
+## Usage Examples
+
+### Inline Property
+```html
+<div style="background-image: url(image.png); background-repeat: no-repeat;">
+  Content
+</div>
+```
+
+### Background Shorthand
+```html
+<div style="background: url(image.png) repeat-x;">
+  Content
+</div>
+```
+
+### With Gradients
+```html
+<div style="background-image: linear-gradient(red, blue); background-repeat: no-repeat;">
+  Content
+</div>
+```
+
+### CSS Rules
+```css
+.pattern {
+  background-image: url(tile.png);
+  background-repeat: repeat;
+  background-size: 50px 50px;
+}
+```
+
+## Notes
+- The `space` and `round` values are parsed and stored correctly, but render as `repeat` with a warning (as noted in existing code)
+- This is consistent with the current implementation for gradients
+- Full `space` and `round` rendering could be added in a future enhancement
+
+## Files Modified
+1. `src/css/parsers/background-parser.ts` - Added core parser function
+2. `src/css/parsers/background-parser-extended.ts` - Exported wrapper function
+3. `src/css/parsers/register-parsers.ts` - Registered the parser
+4. `tests/pdf/background-repeat.spec.ts` - Added comprehensive tests (NEW)
+
+## Conclusion
+The `background-repeat` property is now fully supported for HTML to PDF conversion, enabling precise control over how background images and gradients tile within elements. The implementation is complete, well-tested, and ready for use.

package/docs/BACKGROUND-REPEAT-REFERENCE.md

@@ -0,0 +1,127 @@
+# Quick Reference: Background-Repeat Property
+
+## Property Support
+The `background-repeat` CSS property is fully supported for controlling how background images and gradients tile.
+
+## Syntax
+```css
+background-repeat: value;
+```
+
+## Supported Values
+| Value | Description | Support Status |
+|-------|-------------|----------------|
+| `repeat` | Tiles the image in both directions (default for images) | ✅ Full |
+| `repeat-x` | Tiles the image horizontally only | ✅ Full |
+| `repeat-y` | Tiles the image vertically only | ✅ Full |
+| `no-repeat` | Displays the image once (default for gradients) | ✅ Full |
+| `space` | Tiles with spacing to fit container | ⚠️ Renders as `repeat` (with warning) |
+| `round` | Tiles and scales to fit container | ⚠️ Renders as `repeat` (with warning) |
+
+## Usage Scenarios
+
+### 1. As an Inline Property
+```html
+<div style="background-image: url(pattern.png); background-repeat: repeat-x;">
+  Horizontal pattern
+</div>
+```
+
+### 2. Within Background Shorthand
+```html
+<div style="background: url(tile.png) no-repeat center;">
+  Centered image, no tiling
+</div>
+```
+
+### 3. In External/Internal CSS
+```html
+<style>
+  .tiled-background {
+    background-image: url(tile.png);
+    background-repeat: repeat;
+    background-size: 100px 100px;
+  }
+</style>
+<div class="tiled-background">Content</div>
+```
+
+### 4. With Gradients
+```html
+<div style="background-image: linear-gradient(to right, red, blue); background-repeat: no-repeat;">
+  Single gradient
+</div>
+```
+
+### 5. Property Override
+```html
+<!-- The background-repeat property will override the shorthand -->
+<div style="background: url(img.png) repeat; background-repeat: no-repeat;">
+  Override example
+</div>
+```
+
+## Advanced Examples
+
+### Tiled Pattern with Size Control
+```css
+.pattern {
+  background-image: url(small-tile.png);
+  background-repeat: repeat;
+  background-size: 50px 50px;
+}
+```
+
+### Horizontal Banner
+```css
+.banner {
+  background-image: url(banner-pattern.png);
+  background-repeat: repeat-x;
+  background-position: top center;
+}
+```
+
+### Vertical Sidebar
+```css
+.sidebar {
+  background-image: url(vertical-pattern.png);
+  background-repeat: repeat-y;
+  background-position: left center;
+}
+```
+
+### Single Positioned Image
+```css
+.logo-watermark {
+  background-image: url(logo.png);
+  background-repeat: no-repeat;
+  background-position: bottom right;
+  background-size: 100px auto;
+}
+```
+
+## Default Behavior
+- **Images**: Default to `repeat` if not specified
+- **Gradients**: Default to `no-repeat` if not specified
+
+## Property Cascade
+The `background-repeat` property follows standard CSS cascade rules:
+1. Inline styles have highest specificity
+2. Later declarations override earlier ones
+3. Properties override shorthand when declared after
+
+## Combining with Other Properties
+```css
+.complex-background {
+  background-image: url(texture.png);
+  background-repeat: repeat;
+  background-size: 80px 80px;
+  background-position: center;
+  background-origin: padding-box;
+}
+```
+
+## Notes
+- The `space` and `round` values are accepted but currently render as `repeat` with a console warning
+- Full implementation of `space` and `round` spacing algorithms may be added in future versions
+- Background repeat works seamlessly with other background properties