`
-- `
`
-- ``
-- `
`
-- `![]()
`
-
-Not supported (examples): tables, lists, semantic formatting tags like ``.
-
-## CSS properties used by renderer
-
-Common supported properties include:
-
-- Typography: `font-size`, `font-family`, `font-weight`, `line-height`, `color`, `text-align`, `hyphens`, `white-space`
-- Layout/box: `margin`, `padding`, `width`, `height`, `overflow`, `text-overflow`
-- Decoration: `background-color`, `border-color`, `border-width`, `border-radius`
-- Flex subset: `display:flex`, `flex-direction`, `justify-content`, `align-items`, `gap`
-- Absolute positioning: `position:absolute`, `top`, `right`, `bottom`, `left`
-
-## Units and values
-
-- Unitless numeric values are accepted for many properties.
-- `px` is accepted and converted to PDF points.
-- `%` is supported for dimensions/offsets in current layout implementation.
-- Unknown or invalid declarations are ignored, not fatal.
-
-## Practical notes
-
-- Font alias mapping targets built-in Helvetica/Times/Courier variants.
-- Overflow clipping uses PDF clipping paths (`overflow:hidden`).
-- The behavior is deterministic and intentionally scoped for overlays/stamps, not browser parity.
-
-See [Limitations](limitations.md) before designing production templates.
diff --git a/docs/reference/supported-svg.md b/docs/reference/supported-svg.md
deleted file mode 100644
index 95e339c..0000000
--- a/docs/reference/supported-svg.md
+++ /dev/null
@@ -1,91 +0,0 @@
-
-
-
-# Supported SVG
-
-SVG support is intentionally scoped and deterministic.
-
-## Supported usage pattern
-
-- SVG is consumed through image source input (for example `
`).
-- `.svg` and `.svgz` extension detection is supported.
-- Content-based SVG detection is also supported (` `f`
-- stroke only -> `S`
-- fill + stroke -> `B`
-
-`stroke-width` is supported (style attribute takes precedence over presentation attribute).
-
-## ViewBox and dimensions
-
-- `viewBox` is supported and takes precedence over `width`/`height`.
-- If no valid `viewBox` is present, positive `width` and `height` are required.
-- Non-positive viewport dimensions are rejected.
-
-## Unsupported or intentionally out-of-scope
-
-- Full SVG text layout support.
-- Filters, masks, gradients, patterns, and full SVG compositing model.
-- Browser-equivalent SVG rendering semantics.
-
-## Error behavior
-
-Common error cases include:
-
-- invalid SVG root/empty payload,
-- malformed path data,
-- unsupported path command,
-- invalid or non-positive viewport definitions.
-
-If this package helps your project generate reliable PDF signature appearances, consider starring the repository, contributing a fixture, or sponsoring maintenance.
diff --git a/docs/use-cases/libresign.md b/docs/use-cases/libresign.md
deleted file mode 100644
index bba7d58..0000000
--- a/docs/use-cases/libresign.md
+++ /dev/null
@@ -1,23 +0,0 @@
-
-
-
-# LibreSign use case
-
-LibreSign is the flagship real-world use case for this package.
-
-`xobject-template` helps generate deterministic visual signature appearances, stamps, and overlays. LibreSign uses this kind of appearance generation inside a broader digital-signature workflow.
-
-## Scope split
-
-- `xobject-template`: appearance generation (Form XObject-oriented rendering).
-- LibreSign: end-to-end digital-signature workflow and platform integration.
-
-## Official links
-
-- LibreSign website:
-- LibreSign GitHub repository:
-- LibreSign documentation:
-
-If you need a complete digital-signature solution, evaluate LibreSign.
-
-If this package helps your project generate reliable PDF signature appearances, consider starring the repository, contributing a fixture, or sponsoring maintenance.
diff --git a/mkdocs.yml b/mkdocs.yml
deleted file mode 100644
index 8bb7b09..0000000
--- a/mkdocs.yml
+++ /dev/null
@@ -1,44 +0,0 @@
-# SPDX-FileCopyrightText: 2026 LibreSign
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
-site_name: xobject-template
-site_description: Minimal HTML+CSS to PDF Form XObject compiler for visible signature appearances
-repo_url: https://github.com/LibreSign/xobject-template
-repo_name: LibreSign/xobject-template
-strict: true
-theme:
- name: material
-plugins:
- - search
-markdown_extensions:
- - admonition
- - tables
- - toc:
- permalink: true
-nav:
- - Home:
- - Overview: index.md
- - Installation: installation.md
- - Getting started: getting-started.md
- - Guides:
- - Basic template: guides/basic-template.md
- - Preview PDF: guides/preview-pdf.md
- - Images: guides/images.md
- - SVG: guides/svg.md
- - Placement and scaling: guides/placement.md
- - Context interpolation: guides/interpolation.md
- - PDF signer integration: guides/signer-integration.md
- - Reference:
- - Public API: reference/public-api.md
- - Output contract: reference/output-contract.md
- - Supported HTML and CSS: reference/supported-html-css.md
- - Supported SVG: reference/supported-svg.md
- - Errors and exceptions: reference/errors.md
- - Limitations: reference/limitations.md
- - Use cases:
- - LibreSign: use-cases/libresign.md
- - Community:
- - Contributing: community/contributing.md
- - Sustainability: community/sustainability.md
- - Roadmap: community/roadmap.md
- - Maintainer notes: community/maintainer-notes.md
diff --git a/requirements-docs.txt b/requirements-docs.txt
deleted file mode 100644
index f4a88ee..0000000
--- a/requirements-docs.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-# SPDX-FileCopyrightText: 2026 LibreSign
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
-mkdocs>=1.6,<2
-mkdocs-material>=9.6,<10
diff --git a/scripts/check-docs-drift.php b/scripts/check-docs-drift.php
deleted file mode 100644
index 39d61eb..0000000
--- a/scripts/check-docs-drift.php
+++ /dev/null
@@ -1,113 +0,0 @@
-isFile()) {
- continue;
- }
-
- if (strtolower($docEntry->getExtension()) !== 'md') {
- continue;
- }
-
- $docsFiles[] = $docEntry->getPathname();
-}
-
-$allDocContent = '';
-foreach ($docsFiles as $docFile) {
- $content = file_get_contents($docFile);
- if (is_string($content)) {
- $allDocContent .= "\n" . $content;
- }
-}
-
-preg_match_all('/examples\/[a-z0-9\-]+\.php/', $allDocContent, $exampleMatches);
-$referencedExamples = array_values(array_unique($exampleMatches[0] ?? []));
-foreach ($referencedExamples as $exampleReference) {
- $examplePath = $projectRoot . '/' . $exampleReference;
- if (!is_file($examplePath)) {
- $errors[] = sprintf('Documented example does not exist: %s', $exampleReference);
- }
-}
-
-$examplesTestPath = $projectRoot . '/tests/Documentation/ExamplesTest.php';
-$examplesTest = file_get_contents($examplesTestPath);
-if (!is_string($examplesTest)) {
- $errors[] = 'Could not read tests/Documentation/ExamplesTest.php';
-} else {
- $allExamples = glob($projectRoot . '/examples/*.php');
- if (!is_array($allExamples)) {
- $allExamples = [];
- }
-
- foreach ($allExamples as $exampleFile) {
- $base = basename($exampleFile);
- if (!str_contains($examplesTest, "'" . $base . "'")) {
- $errors[] = sprintf('Example not declared in ExamplesTest::documentedExamples(): %s', $base);
- }
- }
-}
-
-$subsetParserPath = $projectRoot . '/src/Html/SubsetHtmlParser.php';
-$subsetParser = file_get_contents($subsetParserPath);
-$supportedHtmlDoc = file_get_contents($projectRoot . '/docs/reference/supported-html-css.md');
-if (is_string($subsetParser) && is_string($supportedHtmlDoc)) {
- if (preg_match('/private array \$allowedTags\s*=\s*\[(.*?)\];/s', $subsetParser, $allowedTagsMatch) === 1) {
- preg_match_all("/'([a-z]+)'\\s*=>\\s*true/", $allowedTagsMatch[1], $tagMatches);
- $tags = array_values(array_unique($tagMatches[1] ?? []));
- foreach ($tags as $tag) {
- if (!str_contains($supportedHtmlDoc, '<' . $tag . '>')) {
- $errors[] = sprintf('Supported HTML tag missing from docs/reference/supported-html-css.md: <%s>', $tag);
- }
- }
- }
-}
-
-$svgParserPath = $projectRoot . '/src/Pdf/Svg/SvgPathCommandParser.php';
-$svgParser = file_get_contents($svgParserPath);
-$supportedSvgDoc = file_get_contents($projectRoot . '/docs/reference/supported-svg.md');
-if (is_string($svgParser) && is_string($supportedSvgDoc)) {
- preg_match_all("/'([A-Z])'\s*=>/", $svgParser, $cmdMatches);
- $commands = array_values(array_unique($cmdMatches[1] ?? []));
- foreach ($commands as $command) {
- if (!str_contains($supportedSvgDoc, '`' . $command . '`,') && !str_contains($supportedSvgDoc, '`' . $command . '`')) {
- $errors[] = sprintf('SVG path command missing from docs/reference/supported-svg.md: %s', $command);
- }
- }
-}
-
-if ($errors !== []) {
- foreach ($errors as $error) {
- fwrite(STDERR, '- ' . $error . PHP_EOL);
- }
-
- exit(1);
-}
-
-fwrite(STDOUT, "Documentation drift checks passed.\n");
From 1e061a929c2b8290a8d7df80b059df52a38c4f75 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 01:59:19 -0300
Subject: [PATCH 04/31] docs: isolate sources under docs/source and ignore
docs/site outputs
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.gitignore | 2 ++
docs/README.md | 19 +++++++++++++++++++
docs/source/README.md | 12 ++++++++++++
3 files changed, 33 insertions(+)
create mode 100644 docs/README.md
create mode 100644 docs/source/README.md
diff --git a/.gitignore b/.gitignore
index 29c30da..0d25515 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,8 @@
/vendor-bin/**/composer.lock
/composer.lock
/build/
+/site/
+/docs/site/
/.phpunit.result.cache
/.infection.cache
/.idea/
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..91e4377
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,19 @@
+
+
+
+# Documentation folder layout
+
+This folder is intentionally split to isolate source content from generated output.
+
+## Structure
+
+- `docs/source/`: documentation source files maintained by contributors.
+- `docs/site/`: generated static site output (build artifact, not versioned).
+
+## Rules
+
+- Keep hand-written documentation in `docs/source/`.
+- Never commit generated files under `docs/site/`.
+- Build outputs in root `site/` are also ignored to reduce accidental commits.
+
+If a docs tool is reintroduced in the future, configure it to read from `docs/source/` and write to `docs/site/`.
diff --git a/docs/source/README.md b/docs/source/README.md
new file mode 100644
index 0000000..d014dfd
--- /dev/null
+++ b/docs/source/README.md
@@ -0,0 +1,12 @@
+
+
+
+# Documentation sources
+
+Place documentation source files in this directory.
+
+Suggested future convention:
+
+- one page per topic,
+- short user-focused sections,
+- examples that map to runnable files under `examples/`.
From 34bc1b096644e7773c4ee0b120c8412c37a50a51 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 02:03:36 -0300
Subject: [PATCH 05/31] docs: move examples to docs/source/examples with
updated path references
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.github/.performance/baseline.json | 16 ++++++++++++++++
.../source/examples}/assets/sample.svg | 0
.../source/examples}/assets/tiny-jpeg.base64 | 0
.../source/examples}/assets/tiny-png.base64 | 0
.../source/examples}/basic-template.php | 4 ++--
{examples => docs/source/examples}/images.php | 6 +++---
.../source/examples}/interpolation.php | 4 ++--
{examples => docs/source/examples}/placement.php | 4 ++--
.../source/examples}/preview-pdf.php | 4 ++--
{examples => docs/source/examples}/svg.php | 6 +++---
tests/Documentation/ExamplesTest.php | 4 ++--
11 files changed, 32 insertions(+), 16 deletions(-)
create mode 100644 .github/.performance/baseline.json
rename {examples => docs/source/examples}/assets/sample.svg (100%)
rename {examples => docs/source/examples}/assets/tiny-jpeg.base64 (100%)
rename {examples => docs/source/examples}/assets/tiny-png.base64 (100%)
rename {examples => docs/source/examples}/basic-template.php (93%)
rename {examples => docs/source/examples}/images.php (93%)
rename {examples => docs/source/examples}/interpolation.php (93%)
rename {examples => docs/source/examples}/placement.php (93%)
rename {examples => docs/source/examples}/preview-pdf.php (92%)
rename {examples => docs/source/examples}/svg.php (90%)
diff --git a/.github/.performance/baseline.json b/.github/.performance/baseline.json
new file mode 100644
index 0000000..68d5a90
--- /dev/null
+++ b/.github/.performance/baseline.json
@@ -0,0 +1,16 @@
+{
+ "version": "1.0.0",
+ "created_at": "2026-06-01",
+ "allowed_regression_pct": 25.0,
+ "stale_threshold_pct": 35.0,
+ "benchmarks": {
+ "LibreSign\\XObjectTemplate\\Benchmarks\\CompilerBench::benchSimpleHtml": {
+ "mean": 0.356085,
+ "memory_real": 768
+ },
+ "LibreSign\\XObjectTemplate\\Benchmarks\\CompilerBench::benchComplexHtml": {
+ "mean": 1.366,
+ "memory_real": 1024
+ }
+ }
+}
diff --git a/examples/assets/sample.svg b/docs/source/examples/assets/sample.svg
similarity index 100%
rename from examples/assets/sample.svg
rename to docs/source/examples/assets/sample.svg
diff --git a/examples/assets/tiny-jpeg.base64 b/docs/source/examples/assets/tiny-jpeg.base64
similarity index 100%
rename from examples/assets/tiny-jpeg.base64
rename to docs/source/examples/assets/tiny-jpeg.base64
diff --git a/examples/assets/tiny-png.base64 b/docs/source/examples/assets/tiny-png.base64
similarity index 100%
rename from examples/assets/tiny-png.base64
rename to docs/source/examples/assets/tiny-png.base64
diff --git a/examples/basic-template.php b/docs/source/examples/basic-template.php
similarity index 93%
rename from examples/basic-template.php
rename to docs/source/examples/basic-template.php
index 057f581..6f19f74 100644
--- a/examples/basic-template.php
+++ b/docs/source/examples/basic-template.php
@@ -8,9 +8,9 @@
use LibreSign\XObjectTemplate\Dto\CompileRequest;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/examples/images.php b/docs/source/examples/images.php
similarity index 93%
rename from examples/images.php
rename to docs/source/examples/images.php
index 3933beb..dd7cf12 100644
--- a/examples/images.php
+++ b/docs/source/examples/images.php
@@ -9,10 +9,10 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__);
-$assetDir = $projectRoot . '/examples/assets';
+$projectRoot = dirname(__DIR__, 3);
+$assetDir = $projectRoot . '/docs/source/examples/assets';
$outputDir = $projectRoot . '/build/examples';
$outputAssetDir = $outputDir . '/assets';
diff --git a/examples/interpolation.php b/docs/source/examples/interpolation.php
similarity index 93%
rename from examples/interpolation.php
rename to docs/source/examples/interpolation.php
index 09380b7..eef92eb 100644
--- a/examples/interpolation.php
+++ b/docs/source/examples/interpolation.php
@@ -8,9 +8,9 @@
use LibreSign\XObjectTemplate\Dto\CompileRequest;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/examples/placement.php b/docs/source/examples/placement.php
similarity index 93%
rename from examples/placement.php
rename to docs/source/examples/placement.php
index 3c9578e..8613911 100644
--- a/examples/placement.php
+++ b/docs/source/examples/placement.php
@@ -9,9 +9,9 @@
use LibreSign\XObjectTemplate\Integration\XObjectPlacementCalculator;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/examples/preview-pdf.php b/docs/source/examples/preview-pdf.php
similarity index 92%
rename from examples/preview-pdf.php
rename to docs/source/examples/preview-pdf.php
index 95c3ab1..25f7f17 100644
--- a/examples/preview-pdf.php
+++ b/docs/source/examples/preview-pdf.php
@@ -9,9 +9,9 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/examples/svg.php b/docs/source/examples/svg.php
similarity index 90%
rename from examples/svg.php
rename to docs/source/examples/svg.php
index 233d4b5..1801994 100644
--- a/examples/svg.php
+++ b/docs/source/examples/svg.php
@@ -9,11 +9,11 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
-$svgPath = $projectRoot . '/examples/assets/sample.svg';
+$svgPath = $projectRoot . '/docs/source/examples/assets/sample.svg';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/tests/Documentation/ExamplesTest.php b/tests/Documentation/ExamplesTest.php
index 8a7ad7b..d8b630d 100644
--- a/tests/Documentation/ExamplesTest.php
+++ b/tests/Documentation/ExamplesTest.php
@@ -41,7 +41,7 @@ public static function exampleProvider(): iterable
public function testExampleScriptsExecuteAndGenerateExpectedArtifacts(string $exampleFile): void
{
$projectRoot = dirname(__DIR__, 2);
- $examplePath = $projectRoot . '/examples/' . $exampleFile;
+ $examplePath = $projectRoot . '/docs/source/examples/' . $exampleFile;
self::assertFileExists($examplePath);
$result = require $examplePath;
@@ -87,7 +87,7 @@ public function testExampleScriptsExecuteAndGenerateExpectedArtifacts(string $ex
public function testEveryPhpExampleFileIsCoveredByTheProvider(): void
{
$projectRoot = dirname(__DIR__, 2);
- $allPhpExamples = glob($projectRoot . '/examples/*.php');
+ $allPhpExamples = glob($projectRoot . '/docs/source/examples/*.php');
self::assertIsArray($allPhpExamples);
$actual = array_map(static fn (string $path): string => basename($path), $allPhpExamples);
From 8bfdcbe7f7bed6e316b569d135e6cba577dbe359 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:32:37 -0300
Subject: [PATCH 06/31] chore: remove unecessary template
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.github/ISSUE_TEMPLATE/commercial_support.yml | 36 -------------------
1 file changed, 36 deletions(-)
delete mode 100644 .github/ISSUE_TEMPLATE/commercial_support.yml
diff --git a/.github/ISSUE_TEMPLATE/commercial_support.yml b/.github/ISSUE_TEMPLATE/commercial_support.yml
deleted file mode 100644
index 32ea6b9..0000000
--- a/.github/ISSUE_TEMPLATE/commercial_support.yml
+++ /dev/null
@@ -1,36 +0,0 @@
-# SPDX-FileCopyrightText: 2026 LibreSign
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
-name: Commercial support
-description: Ask about paid support or sponsored prioritization
-labels: [support]
-body:
- - type: markdown
- attributes:
- value: |
- Thanks for your interest in commercial support.
-
- This template does not guarantee free consulting. Sponsored or paid work can help prioritize compatibility, features, and long-term maintenance.
-
- Current public funding channel: https://github.com/sponsors/LibreSign
- - type: textarea
- id: context
- attributes:
- label: Project context
- description: Describe your use case, expected timeline, and technical scope.
- validations:
- required: true
- - type: textarea
- id: requested_scope
- attributes:
- label: Requested support scope
- description: Include expected deliverables (for example SVG compatibility work, integration support, QA hardening).
- validations:
- required: true
- - type: input
- id: contact
- attributes:
- label: Preferred contact method
- placeholder: email or issue-based follow-up
- validations:
- required: true
From f06ecb02c3370f6635f132c9b91ff3e73b053ad1 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:40:45 -0300
Subject: [PATCH 07/31] docs: restore minimal public documentation pages
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/README.md | 4 +-
docs/index.md | 49 +++++++++++++++++++++
docs/source/README.md | 15 ++++++-
docs/source/guides/getting-started.md | 45 +++++++++++++++++++
docs/source/guides/index.md | 6 +++
docs/source/index.md | 43 ++++++++++++++++++
docs/source/reference/examples.md | 30 +++++++++++++
docs/source/reference/index.md | 6 +++
docs/source/use-cases/index.md | 6 +++
docs/source/use-cases/visible-signatures.md | 27 ++++++++++++
10 files changed, 228 insertions(+), 3 deletions(-)
create mode 100644 docs/index.md
create mode 100644 docs/source/guides/getting-started.md
create mode 100644 docs/source/guides/index.md
create mode 100644 docs/source/index.md
create mode 100644 docs/source/reference/examples.md
create mode 100644 docs/source/reference/index.md
create mode 100644 docs/source/use-cases/index.md
create mode 100644 docs/source/use-cases/visible-signatures.md
diff --git a/docs/README.md b/docs/README.md
index 91e4377..6083d98 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,9 +7,11 @@ This folder is intentionally split to isolate source content from generated outp
## Structure
-- `docs/source/`: documentation source files maintained by contributors.
+- `docs/source/`: documentation source files maintained by contributors and intended for publication.
- `docs/site/`: generated static site output (build artifact, not versioned).
+The public entry page is `docs/index.md`.
+
## Rules
- Keep hand-written documentation in `docs/source/`.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..6021511
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,49 @@
+
+
+
+# xobject-template documentation
+
+This is the public documentation landing page for the repository.
+The full hand-written source lives under `docs/source/`.
+
+## What this library does
+
+`xobject-template` compiles a constrained HTML/CSS subset into reusable PDF Form XObject output.
+It is designed for predictable signature appearances, labels, stamps, overlays, and other compact PDF decorations.
+
+## Start here
+
+- [Getting started](source/guides/)
+- [Examples](source/reference/)
+- [Visible signature use case](source/use-cases/)
+
+## Highlights
+
+- deterministic rendering for PDF workflows,
+- a focused PHP API,
+- runnable examples covered by tests,
+- a small documentation surface that is easier to maintain.
+
+## Repository layout
+
+- `src/` — library code
+- `tests/` — unit, integration, and documentation tests
+- `docs/` — public documentation pages
+- `docs/source/` — source pages and example files
+
+## Quick example
+
+```php
+use LibreSign\XObjectTemplate\Dto\CompileRequest;
+use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
+
+$compiler = new XObjectTemplateCompiler();
+$result = $compiler->compile(new CompileRequest(
+ html: 'Signed by {{ name }}
',
+ width: 240.0,
+ height: 84.0,
+ context: ['name' => 'Alice'],
+));
+```
+
+For executable samples, see the [examples page](source/reference/).
diff --git a/docs/source/README.md b/docs/source/README.md
index d014dfd..d20190b 100644
--- a/docs/source/README.md
+++ b/docs/source/README.md
@@ -3,10 +3,21 @@
# Documentation sources
-Place documentation source files in this directory.
+This directory contains the hand-written documentation pages that are meant to be published.
-Suggested future convention:
+## Entry point
+
+- `index.md` — documentation home
+
+## Suggested structure
- one page per topic,
- short user-focused sections,
- examples that map to runnable files under `examples/`.
+
+## Published pages
+
+- `guides/getting-started.md`
+- `reference/examples.md`
+- `use-cases/visible-signatures.md`
+- `examples/` — runnable example sources and fixtures
diff --git a/docs/source/guides/getting-started.md b/docs/source/guides/getting-started.md
new file mode 100644
index 0000000..fe47d2f
--- /dev/null
+++ b/docs/source/guides/getting-started.md
@@ -0,0 +1,45 @@
+
+
+
+# Getting started
+
+## Install
+
+```bash
+composer require libresign/xobject-template
+```
+
+## Render a template
+
+```php
+compile(new CompileRequest(
+ html: 'Signed by {{ name }}
',
+ width: 240.0,
+ height: 84.0,
+ context: ['name' => 'Alice'],
+));
+
+// $result->contentStream
+// $result->resources
+// $result->bbox
+```
+
+## Validate the examples
+
+Run the documentation test suite to execute every example file and verify the generated artifacts:
+
+```bash
+composer run examples:test
+```
+
+## Where to look next
+
+- [Examples](../reference/examples.md)
+- [Visible signature use case](../use-cases/visible-signatures.md)
diff --git a/docs/source/guides/index.md b/docs/source/guides/index.md
new file mode 100644
index 0000000..06410a6
--- /dev/null
+++ b/docs/source/guides/index.md
@@ -0,0 +1,6 @@
+
+
+
+# Guides
+
+- [Getting started](getting-started.md)
diff --git a/docs/source/index.md b/docs/source/index.md
new file mode 100644
index 0000000..db167e5
--- /dev/null
+++ b/docs/source/index.md
@@ -0,0 +1,43 @@
+
+
+
+# xobject-template documentation
+
+`xobject-template` turns a constrained HTML/CSS subset into reusable PDF Form XObject output for signatures, stamps, labels, and overlays.
+
+## Start here
+
+- [Getting started](guides/)
+- [Examples](reference/)
+- [Visible signature use case](use-cases/)
+
+## What you get
+
+- deterministic rendering for PDF workflows,
+- a focused PHP API,
+- runnable examples that are covered by tests,
+- a small documentation footprint that is easier to maintain.
+
+## Repository layout
+
+- `src/` — library code
+- `tests/` — unit, integration, and documentation tests
+- `docs/source/` — documentation pages intended for publication
+- `docs/source/examples/` — executable examples with fixtures
+
+## Quick preview
+
+```php
+use LibreSign\XObjectTemplate\Dto\CompileRequest;
+use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
+
+$compiler = new XObjectTemplateCompiler();
+$result = $compiler->compile(new CompileRequest(
+ html: 'Signed by {{ name }}
',
+ width: 240.0,
+ height: 84.0,
+ context: ['name' => 'Alice'],
+));
+```
+
+For executable samples, see the [examples page](reference/).
diff --git a/docs/source/reference/examples.md b/docs/source/reference/examples.md
new file mode 100644
index 0000000..9bc4af1
--- /dev/null
+++ b/docs/source/reference/examples.md
@@ -0,0 +1,30 @@
+
+
+
+# Examples
+
+The examples are executable PHP files under `docs/source/examples/`.
+Each one is covered by `tests/Documentation/ExamplesTest.php`.
+
+## Included examples
+
+- `basic-template.php` — compile a simple template with a context variable
+- `preview-pdf.php` — export a single-page PDF preview
+- `images.php` — embed PNG and JPEG assets from base64 fixtures
+- `svg.php` — render SVG content as an image source
+- `placement.php` — demonstrate placement calculations
+- `interpolation.php` — interpolate context variables in text
+
+## How to run them
+
+```bash
+composer run examples:test
+```
+
+## Output files
+
+The examples write their generated artifacts to `build/examples/` so the repository stays clean and the outputs remain disposable.
+
+## Assets
+
+Supporting fixtures live in `docs/source/examples/assets/`.
diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md
new file mode 100644
index 0000000..b5deb52
--- /dev/null
+++ b/docs/source/reference/index.md
@@ -0,0 +1,6 @@
+
+
+
+# Reference
+
+- [Examples](examples.md)
diff --git a/docs/source/use-cases/index.md b/docs/source/use-cases/index.md
new file mode 100644
index 0000000..7b52953
--- /dev/null
+++ b/docs/source/use-cases/index.md
@@ -0,0 +1,6 @@
+
+
+
+# Use cases
+
+- [Visible signature appearances](visible-signatures.md)
diff --git a/docs/source/use-cases/visible-signatures.md b/docs/source/use-cases/visible-signatures.md
new file mode 100644
index 0000000..d23b425
--- /dev/null
+++ b/docs/source/use-cases/visible-signatures.md
@@ -0,0 +1,27 @@
+
+
+
+# Visible signature appearances
+
+This library exists to support cases where a PDF needs a predictable visible appearance:
+
+- signature labels,
+- approval stamps,
+- overlay annotations,
+- status blocks,
+- other compact PDF decorations.
+
+## Why this matters
+
+PDF pipelines usually need stable layout more than browser-grade rendering. `xobject-template` keeps the surface area small so the output is easier to test and reason about.
+
+## Typical flow
+
+1. Build a `CompileRequest`.
+2. Pass HTML, dimensions, and context to `XObjectTemplateCompiler`.
+3. Consume the generated `contentStream`, `resources`, and `bbox` in downstream PDF tooling.
+
+## Related pages
+
+- [Getting started](../guides/getting-started.md)
+- [Examples](../reference/examples.md)
From 39f9b0807796eebf494705a7ccfbe1d60850f906 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:46:13 -0300
Subject: [PATCH 08/31] docs: simplify documentation landing pages
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/index.md | 17 ++++-------------
docs/source/index.md | 13 ++++---------
2 files changed, 8 insertions(+), 22 deletions(-)
diff --git a/docs/index.md b/docs/index.md
index 6021511..d094503 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,13 +3,11 @@
# xobject-template documentation
-This is the public documentation landing page for the repository.
-The full hand-written source lives under `docs/source/`.
+Public docs for `xobject-template`.
-## What this library does
+Source pages live in `docs/source/`.
-`xobject-template` compiles a constrained HTML/CSS subset into reusable PDF Form XObject output.
-It is designed for predictable signature appearances, labels, stamps, overlays, and other compact PDF decorations.
+`xobject-template` compiles a constrained HTML/CSS subset into PDF Form XObject output.
## Start here
@@ -17,19 +15,12 @@ It is designed for predictable signature appearances, labels, stamps, overlays,
- [Examples](source/reference/)
- [Visible signature use case](source/use-cases/)
-## Highlights
-
-- deterministic rendering for PDF workflows,
-- a focused PHP API,
-- runnable examples covered by tests,
-- a small documentation surface that is easier to maintain.
-
## Repository layout
- `src/` — library code
- `tests/` — unit, integration, and documentation tests
- `docs/` — public documentation pages
-- `docs/source/` — source pages and example files
+- `docs/source/` — editable source pages and examples
## Quick example
diff --git a/docs/source/index.md b/docs/source/index.md
index db167e5..4982af8 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -3,7 +3,9 @@
# xobject-template documentation
-`xobject-template` turns a constrained HTML/CSS subset into reusable PDF Form XObject output for signatures, stamps, labels, and overlays.
+Editable source for the public docs.
+
+`xobject-template` compiles a constrained HTML/CSS subset into PDF Form XObject output.
## Start here
@@ -11,13 +13,6 @@
- [Examples](reference/)
- [Visible signature use case](use-cases/)
-## What you get
-
-- deterministic rendering for PDF workflows,
-- a focused PHP API,
-- runnable examples that are covered by tests,
-- a small documentation footprint that is easier to maintain.
-
## Repository layout
- `src/` — library code
@@ -25,7 +20,7 @@
- `docs/source/` — documentation pages intended for publication
- `docs/source/examples/` — executable examples with fixtures
-## Quick preview
+## Quick example
```php
use LibreSign\XObjectTemplate\Dto\CompileRequest;
From c3f1666f273d5c579ea4e66094f488badd6fe73f Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:47:30 -0300
Subject: [PATCH 09/31] docs: clarify documentation landing pages
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/index.md | 4 ++--
docs/source/index.md | 4 +++-
2 files changed, 5 insertions(+), 3 deletions(-)
diff --git a/docs/index.md b/docs/index.md
index d094503..88aa00e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,9 +3,9 @@
# xobject-template documentation
-Public docs for `xobject-template`.
+This is the front door for the public docs site.
-Source pages live in `docs/source/`.
+If you're a developer trying to use `xobject-template`, start with the install guide, then open an example, then check a real use case.
`xobject-template` compiles a constrained HTML/CSS subset into PDF Form XObject output.
diff --git a/docs/source/index.md b/docs/source/index.md
index 4982af8..8d1344f 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -3,7 +3,9 @@
# xobject-template documentation
-Editable source for the public docs.
+Editable source for the public docs site.
+
+Use this folder when you want to update the pages that get published.
`xobject-template` compiles a constrained HTML/CSS subset into PDF Form XObject output.
From 14367f41cc8d9717cc98e6f2aa3fef44cdb177d8 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:49:09 -0300
Subject: [PATCH 10/31] docs: remove architecture-heavy landing page text
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/README.md | 15 ---------------
docs/index.md | 11 +----------
docs/source/index.md | 11 +----------
3 files changed, 2 insertions(+), 35 deletions(-)
diff --git a/docs/README.md b/docs/README.md
index 6083d98..9179016 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,18 +4,3 @@
# Documentation folder layout
This folder is intentionally split to isolate source content from generated output.
-
-## Structure
-
-- `docs/source/`: documentation source files maintained by contributors and intended for publication.
-- `docs/site/`: generated static site output (build artifact, not versioned).
-
-The public entry page is `docs/index.md`.
-
-## Rules
-
-- Keep hand-written documentation in `docs/source/`.
-- Never commit generated files under `docs/site/`.
-- Build outputs in root `site/` are also ignored to reduce accidental commits.
-
-If a docs tool is reintroduced in the future, configure it to read from `docs/source/` and write to `docs/site/`.
diff --git a/docs/index.md b/docs/index.md
index 88aa00e..7b73376 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,9 +3,7 @@
# xobject-template documentation
-This is the front door for the public docs site.
-
-If you're a developer trying to use `xobject-template`, start with the install guide, then open an example, then check a real use case.
+Read the docs.
`xobject-template` compiles a constrained HTML/CSS subset into PDF Form XObject output.
@@ -15,13 +13,6 @@ If you're a developer trying to use `xobject-template`, start with the install g
- [Examples](source/reference/)
- [Visible signature use case](source/use-cases/)
-## Repository layout
-
-- `src/` — library code
-- `tests/` — unit, integration, and documentation tests
-- `docs/` — public documentation pages
-- `docs/source/` — editable source pages and examples
-
## Quick example
```php
diff --git a/docs/source/index.md b/docs/source/index.md
index 8d1344f..61eebf8 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -3,9 +3,7 @@
# xobject-template documentation
-Editable source for the public docs site.
-
-Use this folder when you want to update the pages that get published.
+Docs content.
`xobject-template` compiles a constrained HTML/CSS subset into PDF Form XObject output.
@@ -15,13 +13,6 @@ Use this folder when you want to update the pages that get published.
- [Examples](reference/)
- [Visible signature use case](use-cases/)
-## Repository layout
-
-- `src/` — library code
-- `tests/` — unit, integration, and documentation tests
-- `docs/source/` — documentation pages intended for publication
-- `docs/source/examples/` — executable examples with fixtures
-
## Quick example
```php
From c09655fda5054372d8c3ae176b14a54c136e7122 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:49:47 -0300
Subject: [PATCH 11/31] docs: trim examples reference page
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/source/reference/examples.md | 4 ----
1 file changed, 4 deletions(-)
diff --git a/docs/source/reference/examples.md b/docs/source/reference/examples.md
index 9bc4af1..4740a7b 100644
--- a/docs/source/reference/examples.md
+++ b/docs/source/reference/examples.md
@@ -24,7 +24,3 @@ composer run examples:test
## Output files
The examples write their generated artifacts to `build/examples/` so the repository stays clean and the outputs remain disposable.
-
-## Assets
-
-Supporting fixtures live in `docs/source/examples/assets/`.
From 5e95e93089ac23eb73587ae037a5b7688a828f63 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:50:19 -0300
Subject: [PATCH 12/31] docs: simplify public docs summary
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/index.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/index.md b/docs/index.md
index 7b73376..50df52d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,7 +5,7 @@
Read the docs.
-`xobject-template` compiles a constrained HTML/CSS subset into PDF Form XObject output.
+`xobject-template` compiles a HTML/CSS template into PDF Form XObject output.
## Start here
From fbbedae9c88400167f4d00ba3e2c1f144f815949 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:52:39 -0300
Subject: [PATCH 13/31] docs: remove redundant reference index page
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/index.md | 6 ++----
docs/source/README.md | 15 +--------------
docs/source/index.md | 4 ++--
docs/source/reference/index.md | 6 ------
4 files changed, 5 insertions(+), 26 deletions(-)
delete mode 100644 docs/source/reference/index.md
diff --git a/docs/index.md b/docs/index.md
index 50df52d..9bd2354 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,14 +3,12 @@
# xobject-template documentation
-Read the docs.
-
`xobject-template` compiles a HTML/CSS template into PDF Form XObject output.
## Start here
- [Getting started](source/guides/)
-- [Examples](source/reference/)
+- [Examples](source/reference/examples.md)
- [Visible signature use case](source/use-cases/)
## Quick example
@@ -28,4 +26,4 @@ $result = $compiler->compile(new CompileRequest(
));
```
-For executable samples, see the [examples page](source/reference/).
+For executable samples, see the [examples page](source/reference/examples.md).
diff --git a/docs/source/README.md b/docs/source/README.md
index d20190b..ae3be7b 100644
--- a/docs/source/README.md
+++ b/docs/source/README.md
@@ -3,21 +3,8 @@
# Documentation sources
-This directory contains the hand-written documentation pages that are meant to be published.
+Hand-written docs live here.
## Entry point
- `index.md` — documentation home
-
-## Suggested structure
-
-- one page per topic,
-- short user-focused sections,
-- examples that map to runnable files under `examples/`.
-
-## Published pages
-
-- `guides/getting-started.md`
-- `reference/examples.md`
-- `use-cases/visible-signatures.md`
-- `examples/` — runnable example sources and fixtures
diff --git a/docs/source/index.md b/docs/source/index.md
index 61eebf8..c7da7b4 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -10,7 +10,7 @@ Docs content.
## Start here
- [Getting started](guides/)
-- [Examples](reference/)
+- [Examples](reference/examples.md)
- [Visible signature use case](use-cases/)
## Quick example
@@ -28,4 +28,4 @@ $result = $compiler->compile(new CompileRequest(
));
```
-For executable samples, see the [examples page](reference/).
+For executable samples, see the [examples page](reference/examples.md).
diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md
deleted file mode 100644
index b5deb52..0000000
--- a/docs/source/reference/index.md
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-
-# Reference
-
-- [Examples](examples.md)
From 2649c765bb7f62acc63a1e1f9b88c51bc5543379 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 10:53:24 -0300
Subject: [PATCH 14/31] docs: remove redundant use-cases index page
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/index.md | 2 +-
docs/source/index.md | 2 +-
docs/source/use-cases/index.md | 6 ------
3 files changed, 2 insertions(+), 8 deletions(-)
delete mode 100644 docs/source/use-cases/index.md
diff --git a/docs/index.md b/docs/index.md
index 9bd2354..0a98899 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -9,7 +9,7 @@
- [Getting started](source/guides/)
- [Examples](source/reference/examples.md)
-- [Visible signature use case](source/use-cases/)
+- [Visible signature use case](source/use-cases/visible-signatures.md)
## Quick example
diff --git a/docs/source/index.md b/docs/source/index.md
index c7da7b4..508e456 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -11,7 +11,7 @@ Docs content.
- [Getting started](guides/)
- [Examples](reference/examples.md)
-- [Visible signature use case](use-cases/)
+- [Visible signature use case](use-cases/visible-signatures.md)
## Quick example
diff --git a/docs/source/use-cases/index.md b/docs/source/use-cases/index.md
deleted file mode 100644
index 7b52953..0000000
--- a/docs/source/use-cases/index.md
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-
-# Use cases
-
-- [Visible signature appearances](visible-signatures.md)
From 8650dae4d06155eaaf68ba898be3351df8f2f2f8 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:07:03 -0300
Subject: [PATCH 15/31] docs: remove redundant guides index page
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/index.md | 2 +-
docs/source/guides/index.md | 6 ------
docs/source/index.md | 2 +-
3 files changed, 2 insertions(+), 8 deletions(-)
delete mode 100644 docs/source/guides/index.md
diff --git a/docs/index.md b/docs/index.md
index 0a98899..1195ead 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,7 +7,7 @@
## Start here
-- [Getting started](source/guides/)
+- [Getting started](source/guides/getting-started.md)
- [Examples](source/reference/examples.md)
- [Visible signature use case](source/use-cases/visible-signatures.md)
diff --git a/docs/source/guides/index.md b/docs/source/guides/index.md
deleted file mode 100644
index 06410a6..0000000
--- a/docs/source/guides/index.md
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-
-# Guides
-
-- [Getting started](getting-started.md)
diff --git a/docs/source/index.md b/docs/source/index.md
index 508e456..e456b25 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -9,7 +9,7 @@ Docs content.
## Start here
-- [Getting started](guides/)
+- [Getting started](guides/getting-started.md)
- [Examples](reference/examples.md)
- [Visible signature use case](use-cases/visible-signatures.md)
From 4c0ae06188421b261412e63e8e12e9f57a9c53df Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:08:49 -0300
Subject: [PATCH 16/31] docs: remove duplicate source/index.md
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/source/index.md | 31 -------------------------------
1 file changed, 31 deletions(-)
delete mode 100644 docs/source/index.md
diff --git a/docs/source/index.md b/docs/source/index.md
deleted file mode 100644
index e456b25..0000000
--- a/docs/source/index.md
+++ /dev/null
@@ -1,31 +0,0 @@
-
-
-
-# xobject-template documentation
-
-Docs content.
-
-`xobject-template` compiles a constrained HTML/CSS subset into PDF Form XObject output.
-
-## Start here
-
-- [Getting started](guides/getting-started.md)
-- [Examples](reference/examples.md)
-- [Visible signature use case](use-cases/visible-signatures.md)
-
-## Quick example
-
-```php
-use LibreSign\XObjectTemplate\Dto\CompileRequest;
-use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-
-$compiler = new XObjectTemplateCompiler();
-$result = $compiler->compile(new CompileRequest(
- html: 'Signed by {{ name }}
',
- width: 240.0,
- height: 84.0,
- context: ['name' => 'Alice'],
-));
-```
-
-For executable samples, see the [examples page](reference/examples.md).
From 9b48b27c2475de8a895a40d7cad95b7e0642ffdb Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:13:00 -0300
Subject: [PATCH 17/31] docs: add MkDocs build and GitHub Pages deployment
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.github/workflows/docs.yml | 52 ++++++++++++++++++++++++++++++++++++++
mkdocs.yml | 34 +++++++++++++++++++++++++
requirements-docs.txt | 2 ++
3 files changed, 88 insertions(+)
create mode 100644 .github/workflows/docs.yml
create mode 100644 mkdocs.yml
create mode 100644 requirements-docs.txt
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..6d8fdff
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2026 LibreSign
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: docs
+
+on:
+ push:
+ branches:
+ - main
+ paths:
+ - 'docs/**'
+ - 'mkdocs.yml'
+ - 'requirements-docs.txt'
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: pages
+ cancel-in-progress: true
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.12'
+
+ - name: Install docs dependencies
+ run: pip install -r requirements-docs.txt
+
+ - name: Build docs
+ run: mkdocs build --strict
+
+ - uses: actions/upload-pages-artifact@v3
+ with:
+ path: docs/site
+
+ deploy:
+ needs: build
+ runs-on: ubuntu-latest
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ steps:
+ - id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..64c9e83
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2026 LibreSign
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+site_name: xobject-template
+site_description: Minimal HTML+CSS to reusable PDF Form XObject compiler.
+site_url: https://libresign.github.io/xobject-template/
+repo_url: https://github.com/LibreSign/xobject-template
+repo_name: LibreSign/xobject-template
+edit_uri: edit/main/docs/
+
+docs_dir: docs
+site_dir: docs/site
+
+theme:
+ name: material
+ palette:
+ scheme: default
+ primary: indigo
+ features:
+ - navigation.instant
+ - navigation.top
+ - content.code.copy
+
+nav:
+ - Home: index.md
+ - Getting started: source/guides/getting-started.md
+ - Examples: source/reference/examples.md
+ - Visible signature use case: source/use-cases/visible-signatures.md
+
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ - pymdownx.superfences
+ - pymdownx.inlinehilite
diff --git a/requirements-docs.txt b/requirements-docs.txt
new file mode 100644
index 0000000..372ffe2
--- /dev/null
+++ b/requirements-docs.txt
@@ -0,0 +1,2 @@
+mkdocs>=1.6
+mkdocs-material>=9.5
From 6226768cf89a9c1003eb16b2db7d05c134de83a6 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:28:49 -0300
Subject: [PATCH 18/31] docs: flatten docs/source/ into docs/ root
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/{source => }/examples/assets/sample.svg | 0
docs/{source => }/examples/assets/tiny-jpeg.base64 | 0
docs/{source => }/examples/assets/tiny-png.base64 | 0
docs/{source => }/examples/basic-template.php | 4 ++--
docs/{source => }/examples/images.php | 6 +++---
docs/{source => }/examples/interpolation.php | 4 ++--
docs/{source => }/examples/placement.php | 4 ++--
docs/{source => }/examples/preview-pdf.php | 4 ++--
docs/{source => }/examples/svg.php | 6 +++---
docs/{source => }/guides/getting-started.md | 0
docs/index.md | 8 ++++----
docs/{source => }/reference/examples.md | 2 +-
docs/source/README.md | 10 ----------
docs/{source => }/use-cases/visible-signatures.md | 0
mkdocs.yml | 6 +++---
tests/Documentation/ExamplesTest.php | 4 ++--
16 files changed, 24 insertions(+), 34 deletions(-)
rename docs/{source => }/examples/assets/sample.svg (100%)
rename docs/{source => }/examples/assets/tiny-jpeg.base64 (100%)
rename docs/{source => }/examples/assets/tiny-png.base64 (100%)
rename docs/{source => }/examples/basic-template.php (93%)
rename docs/{source => }/examples/images.php (93%)
rename docs/{source => }/examples/interpolation.php (93%)
rename docs/{source => }/examples/placement.php (93%)
rename docs/{source => }/examples/preview-pdf.php (92%)
rename docs/{source => }/examples/svg.php (90%)
rename docs/{source => }/guides/getting-started.md (100%)
rename docs/{source => }/reference/examples.md (91%)
delete mode 100644 docs/source/README.md
rename docs/{source => }/use-cases/visible-signatures.md (100%)
diff --git a/docs/source/examples/assets/sample.svg b/docs/examples/assets/sample.svg
similarity index 100%
rename from docs/source/examples/assets/sample.svg
rename to docs/examples/assets/sample.svg
diff --git a/docs/source/examples/assets/tiny-jpeg.base64 b/docs/examples/assets/tiny-jpeg.base64
similarity index 100%
rename from docs/source/examples/assets/tiny-jpeg.base64
rename to docs/examples/assets/tiny-jpeg.base64
diff --git a/docs/source/examples/assets/tiny-png.base64 b/docs/examples/assets/tiny-png.base64
similarity index 100%
rename from docs/source/examples/assets/tiny-png.base64
rename to docs/examples/assets/tiny-png.base64
diff --git a/docs/source/examples/basic-template.php b/docs/examples/basic-template.php
similarity index 93%
rename from docs/source/examples/basic-template.php
rename to docs/examples/basic-template.php
index 6f19f74..e317945 100644
--- a/docs/source/examples/basic-template.php
+++ b/docs/examples/basic-template.php
@@ -8,9 +8,9 @@
use LibreSign\XObjectTemplate\Dto\CompileRequest;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 3) . '/vendor/autoload.php';
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 3);
+$projectRoot = dirname(__DIR__, 2);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/source/examples/images.php b/docs/examples/images.php
similarity index 93%
rename from docs/source/examples/images.php
rename to docs/examples/images.php
index dd7cf12..4f21abc 100644
--- a/docs/source/examples/images.php
+++ b/docs/examples/images.php
@@ -9,10 +9,10 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 3) . '/vendor/autoload.php';
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 3);
-$assetDir = $projectRoot . '/docs/source/examples/assets';
+$projectRoot = dirname(__DIR__, 2);
+$assetDir = $projectRoot . '/docs/examples/assets';
$outputDir = $projectRoot . '/build/examples';
$outputAssetDir = $outputDir . '/assets';
diff --git a/docs/source/examples/interpolation.php b/docs/examples/interpolation.php
similarity index 93%
rename from docs/source/examples/interpolation.php
rename to docs/examples/interpolation.php
index eef92eb..77b23d3 100644
--- a/docs/source/examples/interpolation.php
+++ b/docs/examples/interpolation.php
@@ -8,9 +8,9 @@
use LibreSign\XObjectTemplate\Dto\CompileRequest;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 3) . '/vendor/autoload.php';
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 3);
+$projectRoot = dirname(__DIR__, 2);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/source/examples/placement.php b/docs/examples/placement.php
similarity index 93%
rename from docs/source/examples/placement.php
rename to docs/examples/placement.php
index 8613911..fbb9cd4 100644
--- a/docs/source/examples/placement.php
+++ b/docs/examples/placement.php
@@ -9,9 +9,9 @@
use LibreSign\XObjectTemplate\Integration\XObjectPlacementCalculator;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 3) . '/vendor/autoload.php';
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 3);
+$projectRoot = dirname(__DIR__, 2);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/source/examples/preview-pdf.php b/docs/examples/preview-pdf.php
similarity index 92%
rename from docs/source/examples/preview-pdf.php
rename to docs/examples/preview-pdf.php
index 25f7f17..d14ad03 100644
--- a/docs/source/examples/preview-pdf.php
+++ b/docs/examples/preview-pdf.php
@@ -9,9 +9,9 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 3) . '/vendor/autoload.php';
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 3);
+$projectRoot = dirname(__DIR__, 2);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/source/examples/svg.php b/docs/examples/svg.php
similarity index 90%
rename from docs/source/examples/svg.php
rename to docs/examples/svg.php
index 1801994..36d5561 100644
--- a/docs/source/examples/svg.php
+++ b/docs/examples/svg.php
@@ -9,11 +9,11 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 3) . '/vendor/autoload.php';
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 3);
+$projectRoot = dirname(__DIR__, 2);
$outputDir = $projectRoot . '/build/examples';
-$svgPath = $projectRoot . '/docs/source/examples/assets/sample.svg';
+$svgPath = $projectRoot . '/docs/examples/assets/sample.svg';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/source/guides/getting-started.md b/docs/guides/getting-started.md
similarity index 100%
rename from docs/source/guides/getting-started.md
rename to docs/guides/getting-started.md
diff --git a/docs/index.md b/docs/index.md
index 1195ead..a30198b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,9 +7,9 @@
## Start here
-- [Getting started](source/guides/getting-started.md)
-- [Examples](source/reference/examples.md)
-- [Visible signature use case](source/use-cases/visible-signatures.md)
+- [Getting started](guides/getting-started.md)
+- [Examples](reference/examples.md)
+- [Visible signature use case](use-cases/visible-signatures.md)
## Quick example
@@ -26,4 +26,4 @@ $result = $compiler->compile(new CompileRequest(
));
```
-For executable samples, see the [examples page](source/reference/examples.md).
+For executable samples, see the [examples page](reference/examples.md).
diff --git a/docs/source/reference/examples.md b/docs/reference/examples.md
similarity index 91%
rename from docs/source/reference/examples.md
rename to docs/reference/examples.md
index 4740a7b..2321388 100644
--- a/docs/source/reference/examples.md
+++ b/docs/reference/examples.md
@@ -3,7 +3,7 @@
# Examples
-The examples are executable PHP files under `docs/source/examples/`.
+The examples are executable PHP files under `docs/examples/`.
Each one is covered by `tests/Documentation/ExamplesTest.php`.
## Included examples
diff --git a/docs/source/README.md b/docs/source/README.md
deleted file mode 100644
index ae3be7b..0000000
--- a/docs/source/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-
-# Documentation sources
-
-Hand-written docs live here.
-
-## Entry point
-
-- `index.md` — documentation home
diff --git a/docs/source/use-cases/visible-signatures.md b/docs/use-cases/visible-signatures.md
similarity index 100%
rename from docs/source/use-cases/visible-signatures.md
rename to docs/use-cases/visible-signatures.md
diff --git a/mkdocs.yml b/mkdocs.yml
index 64c9e83..dde31c4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -23,9 +23,9 @@ theme:
nav:
- Home: index.md
- - Getting started: source/guides/getting-started.md
- - Examples: source/reference/examples.md
- - Visible signature use case: source/use-cases/visible-signatures.md
+ - Getting started: guides/getting-started.md
+ - Examples: reference/examples.md
+ - Visible signature use case: use-cases/visible-signatures.md
markdown_extensions:
- pymdownx.highlight:
diff --git a/tests/Documentation/ExamplesTest.php b/tests/Documentation/ExamplesTest.php
index d8b630d..2f8fae0 100644
--- a/tests/Documentation/ExamplesTest.php
+++ b/tests/Documentation/ExamplesTest.php
@@ -41,7 +41,7 @@ public static function exampleProvider(): iterable
public function testExampleScriptsExecuteAndGenerateExpectedArtifacts(string $exampleFile): void
{
$projectRoot = dirname(__DIR__, 2);
- $examplePath = $projectRoot . '/docs/source/examples/' . $exampleFile;
+ $examplePath = $projectRoot . '/docs/examples/' . $exampleFile;
self::assertFileExists($examplePath);
$result = require $examplePath;
@@ -87,7 +87,7 @@ public function testExampleScriptsExecuteAndGenerateExpectedArtifacts(string $ex
public function testEveryPhpExampleFileIsCoveredByTheProvider(): void
{
$projectRoot = dirname(__DIR__, 2);
- $allPhpExamples = glob($projectRoot . '/docs/source/examples/*.php');
+ $allPhpExamples = glob($projectRoot . '/docs/examples/*.php');
self::assertIsArray($allPhpExamples);
$actual = array_map(static fn (string $path): string => basename($path), $allPhpExamples);
From 305aa5d8cb53878cb0d4f27b2b14e73a39dd28fc Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:37:41 -0300
Subject: [PATCH 19/31] docs: move mkdocs config to docs/ and deploy to
gh-pages branch
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.github/workflows/docs.yml | 30 +++++--------------
mkdocs.yml => docs/mkdocs.yml | 4 +--
.../requirements-docs.txt | 0
3 files changed, 9 insertions(+), 25 deletions(-)
rename mkdocs.yml => docs/mkdocs.yml (95%)
rename requirements-docs.txt => docs/requirements-docs.txt (100%)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 6d8fdff..37706a6 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -9,20 +9,18 @@ on:
- main
paths:
- 'docs/**'
- - 'mkdocs.yml'
- - 'requirements-docs.txt'
+ - 'docs/mkdocs.yml'
+ - 'docs/requirements-docs.txt'
permissions:
- contents: read
- pages: write
- id-token: write
+ contents: write
concurrency:
group: pages
cancel-in-progress: true
jobs:
- build:
+ deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
@@ -32,21 +30,7 @@ jobs:
python-version: '3.12'
- name: Install docs dependencies
- run: pip install -r requirements-docs.txt
-
- - name: Build docs
- run: mkdocs build --strict
-
- - uses: actions/upload-pages-artifact@v3
- with:
- path: docs/site
+ run: pip install -r docs/requirements-docs.txt
- deploy:
- needs: build
- runs-on: ubuntu-latest
- environment:
- name: github-pages
- url: ${{ steps.deployment.outputs.page_url }}
- steps:
- - id: deployment
- uses: actions/deploy-pages@v4
+ - name: Deploy to gh-pages
+ run: mkdocs gh-deploy --force --config-file docs/mkdocs.yml
diff --git a/mkdocs.yml b/docs/mkdocs.yml
similarity index 95%
rename from mkdocs.yml
rename to docs/mkdocs.yml
index dde31c4..0bf2a0f 100644
--- a/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -8,8 +8,8 @@ repo_url: https://github.com/LibreSign/xobject-template
repo_name: LibreSign/xobject-template
edit_uri: edit/main/docs/
-docs_dir: docs
-site_dir: docs/site
+docs_dir: .
+site_dir: site
theme:
name: material
diff --git a/requirements-docs.txt b/docs/requirements-docs.txt
similarity index 100%
rename from requirements-docs.txt
rename to docs/requirements-docs.txt
From 5e43208e3b2841fccb1c658e2b7949ea6b8c3be2 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:41:15 -0300
Subject: [PATCH 20/31] chore: remove stale /site/ entry from .gitignore
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.gitignore | 1 -
1 file changed, 1 deletion(-)
diff --git a/.gitignore b/.gitignore
index 0d25515..c489f4d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,6 @@
/vendor-bin/**/composer.lock
/composer.lock
/build/
-/site/
/docs/site/
/.phpunit.result.cache
/.infection.cache
From 3be90d06efaa2a5e1efcb349bcf468b998d8af85 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:43:00 -0300
Subject: [PATCH 21/31] docs: fix site_dir outside docs_dir and remove
conflicting README
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.gitignore | 1 -
docs/README.md | 6 ------
docs/mkdocs.yml | 2 +-
3 files changed, 1 insertion(+), 8 deletions(-)
delete mode 100644 docs/README.md
diff --git a/.gitignore b/.gitignore
index c489f4d..29c30da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,6 @@
/vendor-bin/**/composer.lock
/composer.lock
/build/
-/docs/site/
/.phpunit.result.cache
/.infection.cache
/.idea/
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 9179016..0000000
--- a/docs/README.md
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-
-# Documentation folder layout
-
-This folder is intentionally split to isolate source content from generated output.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 0bf2a0f..96090eb 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -9,7 +9,7 @@ repo_name: LibreSign/xobject-template
edit_uri: edit/main/docs/
docs_dir: .
-site_dir: site
+site_dir: ../build/docs-site
theme:
name: material
From 60aafd21f61168666907fb721fbc460fae1fbdc3 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:50:25 -0300
Subject: [PATCH 22/31] docs: enable pygments syntax highlighting
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/mkdocs.yml | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 96090eb..4931ff6 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -30,5 +30,7 @@ nav:
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
+ use_pygments: true
+ pygments_lang_class: true
- pymdownx.superfences
- pymdownx.inlinehilite
From 87805e33f639e7cd6b3c6ac864de6d9d1587acff Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:52:03 -0300
Subject: [PATCH 23/31] docs: move mkdocs config back to project root
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.github/workflows/docs.yml | 8 ++++----
docs/mkdocs.yml => mkdocs.yml | 4 ++--
docs/requirements-docs.txt => requirements-docs.txt | 0
3 files changed, 6 insertions(+), 6 deletions(-)
rename docs/mkdocs.yml => mkdocs.yml (95%)
rename docs/requirements-docs.txt => requirements-docs.txt (100%)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 37706a6..d92eddf 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -9,8 +9,8 @@ on:
- main
paths:
- 'docs/**'
- - 'docs/mkdocs.yml'
- - 'docs/requirements-docs.txt'
+ - 'mkdocs.yml'
+ - 'requirements-docs.txt'
permissions:
contents: write
@@ -30,7 +30,7 @@ jobs:
python-version: '3.12'
- name: Install docs dependencies
- run: pip install -r docs/requirements-docs.txt
+ run: pip install -r requirements-docs.txt
- name: Deploy to gh-pages
- run: mkdocs gh-deploy --force --config-file docs/mkdocs.yml
+ run: mkdocs gh-deploy --force
diff --git a/docs/mkdocs.yml b/mkdocs.yml
similarity index 95%
rename from docs/mkdocs.yml
rename to mkdocs.yml
index 4931ff6..66139c5 100644
--- a/docs/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,8 +8,8 @@ repo_url: https://github.com/LibreSign/xobject-template
repo_name: LibreSign/xobject-template
edit_uri: edit/main/docs/
-docs_dir: .
-site_dir: ../build/docs-site
+docs_dir: docs
+site_dir: build/docs-site
theme:
name: material
diff --git a/docs/requirements-docs.txt b/requirements-docs.txt
similarity index 100%
rename from docs/requirements-docs.txt
rename to requirements-docs.txt
From 51a0439f6d0c7bcbbec3616312837d181e478d92 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:56:33 -0300
Subject: [PATCH 24/31] docs: reorganize to docs/source/ structure for cleaner
separation
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.github/workflows/docs.yml | 7 ++--
docs/mkdocs.yml | 36 +++++++++++++++++++
.../requirements-docs.txt | 0
docs/{ => source}/examples/assets/sample.svg | 0
.../examples/assets/tiny-jpeg.base64 | 0
.../examples/assets/tiny-png.base64 | 0
docs/{ => source}/examples/basic-template.php | 4 +--
docs/{ => source}/examples/images.php | 6 ++--
docs/{ => source}/examples/interpolation.php | 4 +--
docs/{ => source}/examples/placement.php | 4 +--
docs/{ => source}/examples/preview-pdf.php | 4 +--
docs/{ => source}/examples/svg.php | 6 ++--
docs/{ => source}/guides/getting-started.md | 0
docs/{ => source}/index.md | 0
docs/{ => source}/reference/examples.md | 2 +-
.../use-cases/visible-signatures.md | 0
tests/Documentation/ExamplesTest.php | 4 +--
17 files changed, 56 insertions(+), 21 deletions(-)
create mode 100644 docs/mkdocs.yml
rename requirements-docs.txt => docs/requirements-docs.txt (100%)
rename docs/{ => source}/examples/assets/sample.svg (100%)
rename docs/{ => source}/examples/assets/tiny-jpeg.base64 (100%)
rename docs/{ => source}/examples/assets/tiny-png.base64 (100%)
rename docs/{ => source}/examples/basic-template.php (93%)
rename docs/{ => source}/examples/images.php (93%)
rename docs/{ => source}/examples/interpolation.php (93%)
rename docs/{ => source}/examples/placement.php (93%)
rename docs/{ => source}/examples/preview-pdf.php (92%)
rename docs/{ => source}/examples/svg.php (90%)
rename docs/{ => source}/guides/getting-started.md (100%)
rename docs/{ => source}/index.md (100%)
rename docs/{ => source}/reference/examples.md (91%)
rename docs/{ => source}/use-cases/visible-signatures.md (100%)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index d92eddf..f8a5bf1 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -9,8 +9,7 @@ on:
- main
paths:
- 'docs/**'
- - 'mkdocs.yml'
- - 'requirements-docs.txt'
+ - '.github/workflows/docs.yml'
permissions:
contents: write
@@ -30,7 +29,7 @@ jobs:
python-version: '3.12'
- name: Install docs dependencies
- run: pip install -r requirements-docs.txt
+ run: pip install -r docs/requirements-docs.txt
- name: Deploy to gh-pages
- run: mkdocs gh-deploy --force
+ run: mkdocs gh-deploy --force --config-file docs/mkdocs.yml
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
new file mode 100644
index 0000000..b39cc79
--- /dev/null
+++ b/docs/mkdocs.yml
@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2026 LibreSign
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+site_name: xobject-template
+site_description: Minimal HTML+CSS to reusable PDF Form XObject compiler.
+site_url: https://libresign.github.io/xobject-template/
+repo_url: https://github.com/LibreSign/xobject-template
+repo_name: LibreSign/xobject-template
+edit_uri: edit/main/docs/source/
+
+docs_dir: source
+site_dir: ../../build/docs-site
+
+theme:
+ name: material
+ palette:
+ scheme: default
+ primary: indigo
+ features:
+ - navigation.instant
+ - navigation.top
+ - content.code.copy
+
+nav:
+ - Home: index.md
+ - Getting started: guides/getting-started.md
+ - Examples: reference/examples.md
+ - Visible signature use case: use-cases/visible-signatures.md
+
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ use_pygments: true
+ pygments_lang_class: true
+ - pymdownx.superfences
+ - pymdownx.inlinehilite
diff --git a/requirements-docs.txt b/docs/requirements-docs.txt
similarity index 100%
rename from requirements-docs.txt
rename to docs/requirements-docs.txt
diff --git a/docs/examples/assets/sample.svg b/docs/source/examples/assets/sample.svg
similarity index 100%
rename from docs/examples/assets/sample.svg
rename to docs/source/examples/assets/sample.svg
diff --git a/docs/examples/assets/tiny-jpeg.base64 b/docs/source/examples/assets/tiny-jpeg.base64
similarity index 100%
rename from docs/examples/assets/tiny-jpeg.base64
rename to docs/source/examples/assets/tiny-jpeg.base64
diff --git a/docs/examples/assets/tiny-png.base64 b/docs/source/examples/assets/tiny-png.base64
similarity index 100%
rename from docs/examples/assets/tiny-png.base64
rename to docs/source/examples/assets/tiny-png.base64
diff --git a/docs/examples/basic-template.php b/docs/source/examples/basic-template.php
similarity index 93%
rename from docs/examples/basic-template.php
rename to docs/source/examples/basic-template.php
index e317945..6f19f74 100644
--- a/docs/examples/basic-template.php
+++ b/docs/source/examples/basic-template.php
@@ -8,9 +8,9 @@
use LibreSign\XObjectTemplate\Dto\CompileRequest;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 2) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 2);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/examples/images.php b/docs/source/examples/images.php
similarity index 93%
rename from docs/examples/images.php
rename to docs/source/examples/images.php
index 4f21abc..dd7cf12 100644
--- a/docs/examples/images.php
+++ b/docs/source/examples/images.php
@@ -9,10 +9,10 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 2) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 2);
-$assetDir = $projectRoot . '/docs/examples/assets';
+$projectRoot = dirname(__DIR__, 3);
+$assetDir = $projectRoot . '/docs/source/examples/assets';
$outputDir = $projectRoot . '/build/examples';
$outputAssetDir = $outputDir . '/assets';
diff --git a/docs/examples/interpolation.php b/docs/source/examples/interpolation.php
similarity index 93%
rename from docs/examples/interpolation.php
rename to docs/source/examples/interpolation.php
index 77b23d3..eef92eb 100644
--- a/docs/examples/interpolation.php
+++ b/docs/source/examples/interpolation.php
@@ -8,9 +8,9 @@
use LibreSign\XObjectTemplate\Dto\CompileRequest;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 2) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 2);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/examples/placement.php b/docs/source/examples/placement.php
similarity index 93%
rename from docs/examples/placement.php
rename to docs/source/examples/placement.php
index fbb9cd4..8613911 100644
--- a/docs/examples/placement.php
+++ b/docs/source/examples/placement.php
@@ -9,9 +9,9 @@
use LibreSign\XObjectTemplate\Integration\XObjectPlacementCalculator;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 2) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 2);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/examples/preview-pdf.php b/docs/source/examples/preview-pdf.php
similarity index 92%
rename from docs/examples/preview-pdf.php
rename to docs/source/examples/preview-pdf.php
index d14ad03..25f7f17 100644
--- a/docs/examples/preview-pdf.php
+++ b/docs/source/examples/preview-pdf.php
@@ -9,9 +9,9 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 2) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 2);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/examples/svg.php b/docs/source/examples/svg.php
similarity index 90%
rename from docs/examples/svg.php
rename to docs/source/examples/svg.php
index 36d5561..1801994 100644
--- a/docs/examples/svg.php
+++ b/docs/source/examples/svg.php
@@ -9,11 +9,11 @@
use LibreSign\XObjectTemplate\Pdf\SinglePagePdfExporter;
use LibreSign\XObjectTemplate\XObjectTemplateCompiler;
-require dirname(__DIR__, 2) . '/vendor/autoload.php';
+require dirname(__DIR__, 3) . '/vendor/autoload.php';
-$projectRoot = dirname(__DIR__, 2);
+$projectRoot = dirname(__DIR__, 3);
$outputDir = $projectRoot . '/build/examples';
-$svgPath = $projectRoot . '/docs/examples/assets/sample.svg';
+$svgPath = $projectRoot . '/docs/source/examples/assets/sample.svg';
if (!is_dir($outputDir)) {
mkdir($outputDir, 0777, true);
diff --git a/docs/guides/getting-started.md b/docs/source/guides/getting-started.md
similarity index 100%
rename from docs/guides/getting-started.md
rename to docs/source/guides/getting-started.md
diff --git a/docs/index.md b/docs/source/index.md
similarity index 100%
rename from docs/index.md
rename to docs/source/index.md
diff --git a/docs/reference/examples.md b/docs/source/reference/examples.md
similarity index 91%
rename from docs/reference/examples.md
rename to docs/source/reference/examples.md
index 2321388..4740a7b 100644
--- a/docs/reference/examples.md
+++ b/docs/source/reference/examples.md
@@ -3,7 +3,7 @@
# Examples
-The examples are executable PHP files under `docs/examples/`.
+The examples are executable PHP files under `docs/source/examples/`.
Each one is covered by `tests/Documentation/ExamplesTest.php`.
## Included examples
diff --git a/docs/use-cases/visible-signatures.md b/docs/source/use-cases/visible-signatures.md
similarity index 100%
rename from docs/use-cases/visible-signatures.md
rename to docs/source/use-cases/visible-signatures.md
diff --git a/tests/Documentation/ExamplesTest.php b/tests/Documentation/ExamplesTest.php
index 2f8fae0..d8b630d 100644
--- a/tests/Documentation/ExamplesTest.php
+++ b/tests/Documentation/ExamplesTest.php
@@ -41,7 +41,7 @@ public static function exampleProvider(): iterable
public function testExampleScriptsExecuteAndGenerateExpectedArtifacts(string $exampleFile): void
{
$projectRoot = dirname(__DIR__, 2);
- $examplePath = $projectRoot . '/docs/examples/' . $exampleFile;
+ $examplePath = $projectRoot . '/docs/source/examples/' . $exampleFile;
self::assertFileExists($examplePath);
$result = require $examplePath;
@@ -87,7 +87,7 @@ public function testExampleScriptsExecuteAndGenerateExpectedArtifacts(string $ex
public function testEveryPhpExampleFileIsCoveredByTheProvider(): void
{
$projectRoot = dirname(__DIR__, 2);
- $allPhpExamples = glob($projectRoot . '/docs/examples/*.php');
+ $allPhpExamples = glob($projectRoot . '/docs/source/examples/*.php');
self::assertIsArray($allPhpExamples);
$actual = array_map(static fn (string $path): string => basename($path), $allPhpExamples);
From 69716760b01fdb155741a3ed59ea50f3baa4f1ab Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 12:57:33 -0300
Subject: [PATCH 25/31] docs: fix site_dir path for docs/ config location
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
docs/mkdocs.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index b39cc79..374347b 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -9,7 +9,7 @@ repo_name: LibreSign/xobject-template
edit_uri: edit/main/docs/source/
docs_dir: source
-site_dir: ../../build/docs-site
+site_dir: ../build/docs-site
theme:
name: material
From d7f26b0d5bd0bcb7ea611866b9a336f17dcc141c Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 14:28:31 -0300
Subject: [PATCH 26/31] docs: refine govbr visible stamp example to match
official appearance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- Adjust GovBR layout dimensions from 190px to 210px height for better spacing
- Fine-tune typography: font sizes, colors (#666666 for labels, #000000 for name)
- Improve padding/margins distribution (18px vertical, 20px horizontal)
- Increase logo section width proportion (30% → 28%) and metadata width (70% → 72%)
- Adjust line-height and margins between text elements for official alignment
- Regenerate example artifacts with new dimensions and styling
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.docker/Dockerfile | 8 +-
composer.json | 3 +-
docker-compose.yml | 2 +
docs/mkdocs.yml | 22 +-
docs/source/guides/getting-started.md | 8 +-
docs/source/index.md | 2 +
docs/source/reference/examples.md | 62 ++-
mkdocs.yml | 36 --
tests/Documentation/ExamplesTest.php | 101 -----
.../ExamplesOutputScenarioTest.php | 406 ++++++++++++++++++
.../VisibleStampPreviewFactory.php | 318 ++++++++++++++
.../VisibleStampTemplateScenarioTest.php | 377 +++-------------
.../XObjectRenderingScenarioTest.php | 12 +-
13 files changed, 893 insertions(+), 464 deletions(-)
delete mode 100644 mkdocs.yml
delete mode 100644 tests/Documentation/ExamplesTest.php
create mode 100644 tests/Integration/ExamplesOutputScenarioTest.php
create mode 100644 tests/Integration/VisibleStampPreviewFactory.php
diff --git a/.docker/Dockerfile b/.docker/Dockerfile
index 3adb176..d80bc9f 100644
--- a/.docker/Dockerfile
+++ b/.docker/Dockerfile
@@ -7,9 +7,15 @@ ARG UID=1000
ARG GID=1000
RUN apt-get update \
- && apt-get install -y --no-install-recommends git unzip zip bash curl ca-certificates \
+ && apt-get install -y --no-install-recommends git unzip zip bash curl ca-certificates python3 python3-pip python3-venv \
&& rm -rf /var/lib/apt/lists/*
+COPY docs/requirements-docs.txt /tmp/requirements-docs.txt
+
+RUN python3 -m venv /opt/docs-venv \
+ && /opt/docs-venv/bin/pip install --no-cache-dir -r /tmp/requirements-docs.txt \
+ && ln -sf /opt/docs-venv/bin/mkdocs /usr/local/bin/mkdocs
+
RUN pecl install xdebug \
&& docker-php-ext-enable xdebug
diff --git a/composer.json b/composer.json
index 90ae953..f78466f 100644
--- a/composer.json
+++ b/composer.json
@@ -73,7 +73,8 @@
"sh:security": "shellcheck scripts/*.sh",
"test:unit": "vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit --testsuite unit",
"test:integration": "vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit --testsuite integration",
- "examples:test": "vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit --testsuite documentation --filter ExamplesTest",
+ "examples:test": "vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit --testsuite integration --filter ExamplesOutputScenarioTest",
+ "docs:watch": "mkdocs serve -f docs/mkdocs.yml -a 0.0.0.0:8000",
"test:coverage": "XDEBUG_MODE=coverage vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit --coverage-text --coverage-clover=build/coverage/clover.xml",
"mutation:test": "vendor-bin/mutation/vendor/infection/infection/bin/infection --threads=max",
"benchmark:run": "vendor-bin/phpbench/vendor/phpbench/phpbench/bin/phpbench run --config=phpbench.json --report=aggregate",
diff --git a/docker-compose.yml b/docker-compose.yml
index be31fab..12feccc 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -24,4 +24,6 @@ services:
# Optional override (default shown): COMPOSER_CACHE_DIR=${HOME}/.composer
- ${COMPOSER_CACHE_DIR:-${HOME}/.composer}:/var/www/.composer/
- ./.profile:/var/www/html/.profile
+ ports:
+ - "${DOCS_PORT:-8000}:8000"
command: ["bash", "-lc", "composer --version && bash"]
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 374347b..6fe1e00 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -13,13 +13,24 @@ site_dir: ../build/docs-site
theme:
name: material
+ logo: https://avatars.githubusercontent.com/u/79158919?v=4
+ favicon: https://avatars.githubusercontent.com/u/79158919?v=4
palette:
- scheme: default
- primary: indigo
+ - scheme: default
+ primary: indigo
+ toggle:
+ icon: material/weather-night
+ name: Switch to dark mode
+ - scheme: slate
+ primary: indigo
+ toggle:
+ icon: material/weather-sunny
+ name: Switch to light mode
features:
- navigation.instant
- navigation.top
- content.code.copy
+ - content.action.edit
nav:
- Home: index.md
@@ -31,6 +42,11 @@ markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
use_pygments: true
- pygments_lang_class: true
+ - admonition
+ - pymdownx.details
- pymdownx.superfences
- pymdownx.inlinehilite
+ - pymdownx.snippets:
+ base_path:
+ - docs/source
+ check_paths: true
diff --git a/docs/source/guides/getting-started.md b/docs/source/guides/getting-started.md
index fe47d2f..ad356e5 100644
--- a/docs/source/guides/getting-started.md
+++ b/docs/source/guides/getting-started.md
@@ -33,12 +33,18 @@ $result = $compiler->compile(new CompileRequest(
## Validate the examples
-Run the documentation test suite to execute every example file and verify the generated artifacts:
+Run the integration scenario for examples to execute every example file and verify the generated artifacts:
```bash
composer run examples:test
```
+This command also materializes additional reusable integration scenarios under
+`build/examples/integration-scenarios/`.
+
+Visible stamp scenarios (including GovBR-like) are also materialized under
+`build/examples/visible-stamp/`.
+
## Where to look next
- [Examples](../reference/examples.md)
diff --git a/docs/source/index.md b/docs/source/index.md
index a30198b..9eb989a 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -14,6 +14,8 @@
## Quick example
```php
+
- */
- public static function documentedExamples(): array
- {
- return [
- 'basic-template.php',
- 'preview-pdf.php',
- 'images.php',
- 'svg.php',
- 'placement.php',
- 'interpolation.php',
- ];
- }
-
- /**
- * @return iterable
- */
- public static function exampleProvider(): iterable
- {
- foreach (self::documentedExamples() as $exampleFile) {
- yield $exampleFile => ['exampleFile' => $exampleFile];
- }
- }
-
- #[DataProvider('exampleProvider')]
- public function testExampleScriptsExecuteAndGenerateExpectedArtifacts(string $exampleFile): void
- {
- $projectRoot = dirname(__DIR__, 2);
- $examplePath = $projectRoot . '/docs/source/examples/' . $exampleFile;
- self::assertFileExists($examplePath);
-
- $result = require $examplePath;
-
- self::assertIsArray($result);
- self::assertArrayHasKey('generated_files', $result);
- self::assertArrayHasKey('content_stream', $result);
- self::assertArrayHasKey('resources', $result);
- self::assertArrayHasKey('bbox', $result);
-
- self::assertIsString($result['content_stream']);
- self::assertNotSame('', trim((string) $result['content_stream']));
-
- self::assertIsArray($result['resources']);
- self::assertArrayHasKey('Font', $result['resources']);
-
- self::assertIsArray($result['bbox']);
- self::assertCount(4, $result['bbox']);
-
- /** @var list $generatedFiles */
- $generatedFiles = $result['generated_files'];
- self::assertNotSame([], $generatedFiles);
-
- foreach ($generatedFiles as $generatedFile) {
- self::assertFileExists($generatedFile);
- $contents = file_get_contents($generatedFile);
- self::assertIsString($contents);
- self::assertNotSame('', $contents);
-
- if (str_ends_with($generatedFile, '.pdf')) {
- self::assertStringStartsWith('%PDF-', $contents);
- self::assertStringContainsString('%%EOF', $contents);
- }
- }
-
- if (isset($result['pdf_file']) && is_string($result['pdf_file'])) {
- $pdfContents = file_get_contents($result['pdf_file']);
- self::assertIsString($pdfContents);
- self::assertStringStartsWith('%PDF-', $pdfContents);
- }
- }
-
- public function testEveryPhpExampleFileIsCoveredByTheProvider(): void
- {
- $projectRoot = dirname(__DIR__, 2);
- $allPhpExamples = glob($projectRoot . '/docs/source/examples/*.php');
- self::assertIsArray($allPhpExamples);
-
- $actual = array_map(static fn (string $path): string => basename($path), $allPhpExamples);
- sort($actual);
-
- $expected = self::documentedExamples();
- sort($expected);
-
- self::assertSame($expected, $actual);
- }
-}
diff --git a/tests/Integration/ExamplesOutputScenarioTest.php b/tests/Integration/ExamplesOutputScenarioTest.php
new file mode 100644
index 0000000..f8ba52b
--- /dev/null
+++ b/tests/Integration/ExamplesOutputScenarioTest.php
@@ -0,0 +1,406 @@
+ $generatedFiles */
+ $generatedFiles = $result['generated_files'];
+ self::assertNotSame([], $generatedFiles);
+
+ foreach ($generatedFiles as $generatedFile) {
+ self::assertStringStartsWith($examplesOutputRoot . '/', $generatedFile);
+ self::assertFileExists($generatedFile);
+ $contents = file_get_contents($generatedFile);
+ self::assertIsString($contents);
+ self::assertNotSame('', $contents);
+
+ if (str_ends_with($generatedFile, '.pdf')) {
+ self::assertStringStartsWith('%PDF-', $contents);
+ self::assertStringContainsString('%%EOF', $contents);
+ }
+ }
+
+ if (isset($result['pdf_file']) && is_string($result['pdf_file'])) {
+ self::assertStringStartsWith($examplesOutputRoot . '/', $result['pdf_file']);
+ $pdfContents = file_get_contents($result['pdf_file']);
+ self::assertIsString($pdfContents);
+ self::assertStringStartsWith('%PDF-', $pdfContents);
+ }
+ }
+
+ public function testEveryPhpExampleFileIsCoveredByTheProvider(): void
+ {
+ $projectRoot = dirname(__DIR__, 2);
+ $allPhpExamples = glob($projectRoot . '/docs/source/examples/*.php');
+ self::assertIsArray($allPhpExamples);
+
+ $actual = array_map(static fn (string $path): string => basename($path), $allPhpExamples);
+ sort($actual);
+
+ $expected = self::documentedExamples();
+ sort($expected);
+
+ self::assertSame($expected, $actual);
+ }
+
+ /**
+ * @return list
+ */
+ private static function documentedExamples(): array
+ {
+ return [
+ 'basic-template.php',
+ 'preview-pdf.php',
+ 'images.php',
+ 'svg.php',
+ 'placement.php',
+ 'interpolation.php',
+ ];
+ }
+
+ /**
+ * @return iterable
+ */
+ public static function exampleProvider(): iterable
+ {
+ foreach (self::documentedExamples() as $exampleFile) {
+ yield $exampleFile => ['exampleFile' => $exampleFile];
+ }
+ }
+
+ #[DataProvider('integrationRenderingScenarioProvider')]
+ public function testIntegrationRenderingScenariosAlsoGenerateExampleArtifacts(
+ string $slug,
+ string $html,
+ float $width,
+ float $height,
+ int $maxStreamLength,
+ ): void {
+ $projectRoot = dirname(__DIR__, 2);
+ $scenarioOutputRoot = $projectRoot . '/build/examples/integration-scenarios';
+
+ if (!is_dir($scenarioOutputRoot)) {
+ mkdir($scenarioOutputRoot, 0777, true);
+ }
+
+ $resolvedHtml = $this->resolveIntegrationScenarioHtmlAssets($html, $scenarioOutputRoot);
+
+ $compiler = new XObjectTemplateCompiler();
+ $result = $compiler->compile(new CompileRequest(
+ html: $resolvedHtml,
+ width: $width,
+ height: $height,
+ ));
+
+ self::assertStringContainsString('BT', $result->contentStream);
+ self::assertStringContainsString('ET', $result->contentStream);
+ self::assertLessThan($maxStreamLength, strlen($result->contentStream));
+
+ $pdf = (new SinglePagePdfExporter())->export($result);
+ $pdfFile = $scenarioOutputRoot . '/' . $slug . '.pdf';
+ file_put_contents($pdfFile, $pdf);
+
+ $jsonFile = $scenarioOutputRoot . '/' . $slug . '.json';
+ file_put_contents($jsonFile, json_encode([
+ 'slug' => $slug,
+ 'bbox' => $result->bbox,
+ 'resources' => $result->resources,
+ 'content_stream_length' => strlen($result->contentStream),
+ 'metadata' => $result->metadata,
+ ], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+
+ self::assertFileExists($pdfFile);
+ self::assertFileExists($jsonFile);
+
+ $pdfContents = file_get_contents($pdfFile);
+ self::assertIsString($pdfContents);
+ self::assertStringStartsWith('%PDF-', $pdfContents);
+ self::assertStringContainsString('%%EOF', $pdfContents);
+
+ $jsonContents = file_get_contents($jsonFile);
+ self::assertIsString($jsonContents);
+ self::assertStringContainsString('"content_stream_length"', $jsonContents);
+ self::assertStringContainsString('"resources"', $jsonContents);
+ }
+
+ private function resolveIntegrationScenarioHtmlAssets(string $html, string $scenarioOutputRoot): string
+ {
+ if (!str_contains($html, '/fixture/example-image.png')) {
+ return $html;
+ }
+
+ $assetRoot = $scenarioOutputRoot . '/assets';
+ if (!is_dir($assetRoot)) {
+ mkdir($assetRoot, 0777, true);
+ }
+
+ $imagePath = $assetRoot . '/example-image.png';
+ if (!is_file($imagePath)) {
+ $contents = PngFixtureFactory::createRgbaPngFromPixelRenderer(
+ 20,
+ 20,
+ static fn (): array => [48, 98, 188, 255],
+ );
+ file_put_contents($imagePath, $contents);
+ }
+
+ return str_replace('/fixture/example-image.png', $imagePath, $html);
+ }
+
+ /**
+ * @return iterable
+ */
+ public static function integrationRenderingScenarioProvider(): iterable
+ {
+ yield 'title and status block' => [
+ 'slug' => 'title-status-block',
+ 'html' => 'Prepared for Demo User
'
+ . 'Document approved
',
+ 'width' => 260.0,
+ 'height' => 90.0,
+ 'maxStreamLength' => 1200,
+ ];
+
+ yield 'image with reference text' => [
+ 'slug' => 'image-reference-text',
+ 'html' => '
'
+ . 'ID 42',
+ 'width' => 260.0,
+ 'height' => 90.0,
+ 'maxStreamLength' => 1400,
+ ];
+
+ yield 'styled block with alignment and spacing' => [
+ 'slug' => 'styled-aligned-spacing',
+ 'html' => 'Prepared by Styled User
',
+ 'width' => 260.0,
+ 'height' => 90.0,
+ 'maxStreamLength' => 1800,
+ ];
+ }
+
+ #[DataProvider('visibleStampExampleScenarioProvider')]
+ public function testVisibleStampScenariosAlsoGenerateExampleArtifacts(
+ string $kind,
+ string $slug,
+ ?string $layout,
+ float $width,
+ float $height,
+ int $expectedImageCount,
+ array $expectedTexts,
+ ): void {
+ $projectRoot = dirname(__DIR__, 2);
+ $outputRoot = $projectRoot . '/build/examples/visible-stamp';
+ $factory = new VisibleStampPreviewFactory($projectRoot);
+
+ if ($kind === 'phase_one') {
+ if (!is_string($layout)) {
+ throw new \InvalidArgumentException('Phase-one visible stamp scenario requires a layout identifier.');
+ }
+
+ ['result' => $result, 'pdf' => $pdf, 'previewPath' => $previewPath] = $factory->compilePhaseOneLayoutPreview(
+ $slug,
+ $layout,
+ $outputRoot,
+ );
+
+ self::assertSame($width, $result->resources['XObject']['Im0']['Width']);
+ self::assertSame($height, $result->resources['XObject']['Im0']['Height']);
+ } else {
+ [
+ 'result' => $result,
+ 'pdf' => $pdf,
+ 'previewPath' => $previewPath,
+ 'logoPath' => $logoPath,
+ ] = $factory->compileGovBrLikePreview(
+ $slug,
+ $width,
+ $height,
+ $outputRoot,
+ );
+
+ self::assertSame($logoPath, $result->resources['XObject']['Im0']['Source']);
+ }
+
+ self::assertSame($expectedImageCount, count($result->resources['XObject'] ?? []));
+ self::assertStringStartsWith('%PDF-', $pdf);
+ self::assertStringContainsString('/Subtype /Form', $pdf);
+ self::assertStringContainsString('/Im0 Do', $result->contentStream);
+ self::assertFileExists($previewPath);
+ self::assertSame($pdf, file_get_contents($previewPath));
+ self::assertStringStartsWith($outputRoot . '/', $previewPath);
+
+ foreach ($expectedTexts as $expectedText) {
+ self::assertStringContainsString($expectedText, $result->contentStream);
+ self::assertStringContainsString($expectedText, $pdf);
+ }
+ }
+
+ /**
+ * @return iterable
+ * }>
+ */
+ public static function visibleStampExampleScenarioProvider(): iterable
+ {
+ foreach (self::visibleStampPhaseOneLayouts() as $name => $scenario) {
+ yield 'phase one: ' . $name => [
+ 'kind' => 'phase_one',
+ 'slug' => $scenario['slug'],
+ 'layout' => $scenario['layout'],
+ 'width' => VisibleStampPreviewFactory::DEFAULT_PREVIEW_WIDTH,
+ 'height' => VisibleStampPreviewFactory::DEFAULT_PREVIEW_HEIGHT,
+ 'expectedImageCount' => $scenario['expectedImageCount'],
+ 'expectedTexts' => $scenario['expectedTexts'],
+ ];
+ }
+
+ $govBr = self::govBrLikeScenario();
+ yield 'govbr-like' => [
+ 'kind' => 'govbr',
+ 'slug' => $govBr['slug'],
+ 'layout' => null,
+ 'width' => $govBr['width'],
+ 'height' => $govBr['height'],
+ 'expectedImageCount' => $govBr['expectedImageCount'],
+ 'expectedTexts' => $govBr['expectedTexts'],
+ ];
+ }
+
+ /**
+ * @return iterable
+ * }>
+ */
+ private static function visibleStampPhaseOneLayouts(): iterable
+ {
+ yield 'signature and metadata at right' => [
+ 'slug' => 'signature-and-metadata-right',
+ 'layout' => 'signature_and_metadata_right',
+ 'expectedImageCount' => 2,
+ 'expectedTexts' => [
+ 'Signed with LibreSign',
+ 'admin',
+ 'Issuer: Preview Issuer',
+ 'Date: 2026-05-28T16:40:21+00:00',
+ ],
+ ];
+
+ yield 'label and metadata at right' => [
+ 'slug' => 'label-and-metadata-right',
+ 'layout' => 'label_and_metadata_right',
+ 'expectedImageCount' => 1,
+ 'expectedTexts' => [
+ 'admin',
+ 'Signed with LibreSign',
+ 'Issuer: Preview Issuer',
+ 'Date: 2026-05-28T16:40:21+00:00',
+ ],
+ ];
+
+ yield 'signature centered' => [
+ 'slug' => 'signature-centered',
+ 'layout' => 'signature_centered',
+ 'expectedImageCount' => 2,
+ 'expectedTexts' => [],
+ ];
+
+ yield 'metadata only at top left' => [
+ 'slug' => 'metadata-only-top-left',
+ 'layout' => 'metadata_only_top_left',
+ 'expectedImageCount' => 1,
+ 'expectedTexts' => [
+ 'Signed with LibreSign',
+ 'admin',
+ 'Issuer: Preview Issuer',
+ 'Date: 2026-05-28T16:40:21+00:00',
+ ],
+ ];
+
+ yield 'two columns with centered cells' => [
+ 'slug' => 'two-columns-centered-cells',
+ 'layout' => 'two_columns_centered_cells',
+ 'expectedImageCount' => 2,
+ 'expectedTexts' => [
+ 'Signed with LibreSign',
+ 'Preview Issuer',
+ 'Date:',
+ '2026-05-28T16:40:21+00:00',
+ ],
+ ];
+ }
+
+ /**
+ * @return array{
+ * slug: string,
+ * width: float,
+ * height: float,
+ * expectedImageCount: int,
+ * expectedTexts: list
+ * }
+ */
+ private static function govBrLikeScenario(): array
+ {
+ return [
+ 'slug' => 'govbr-like-visible-stamp',
+ 'width' => 760.0,
+ 'height' => 210.0,
+ 'expectedImageCount' => 1,
+ 'expectedTexts' => [
+ 'Documento assinado digitalmente',
+ 'ASSINANTE DE EXEMPLO',
+ 'Data: 01/01/2026 12:00:00-0300',
+ 'Verifique em https://verificador.iti.br',
+ ],
+ ];
+ }
+}
\ No newline at end of file
diff --git a/tests/Integration/VisibleStampPreviewFactory.php b/tests/Integration/VisibleStampPreviewFactory.php
new file mode 100644
index 0000000..cc217f7
--- /dev/null
+++ b/tests/Integration/VisibleStampPreviewFactory.php
@@ -0,0 +1,318 @@
+ensureDirectoryExists($previewRoot);
+ $this->ensureDirectoryExists($assetRoot);
+
+ $backgroundPath = $this->createBackgroundPreview($assetRoot . '/background-' . $slug . '.png');
+ $signaturePath = $this->layoutUsesSignatureImage($layout)
+ ? $this->createSignaturePreview($assetRoot . '/signature-' . $slug . '.png')
+ : null;
+
+ return $this->compilePreviewWithSize(
+ $slug,
+ $this->buildLayoutHtml($layout, $backgroundPath, $signaturePath),
+ self::DEFAULT_PREVIEW_WIDTH,
+ self::DEFAULT_PREVIEW_HEIGHT,
+ $previewRoot,
+ );
+ }
+
+ /**
+ * @return array{result: \LibreSign\XObjectTemplate\Dto\CompileResult, pdf: string, previewPath: string, logoPath: string}
+ */
+ public function compileGovBrLikePreview(
+ string $slug,
+ float $width,
+ float $height,
+ string $previewRoot,
+ ): array {
+ $logoPath = $this->projectRoot . '/tests/Fixtures/Pdf/Svg/govbr-logo.svg';
+ if (!is_file($logoPath)) {
+ throw new \InvalidArgumentException(sprintf('GovBR logo fixture was not found at "%s".', $logoPath));
+ }
+
+ $preview = $this->compilePreviewWithSize(
+ $slug,
+ $this->buildGovBrLikeLayoutHtml($logoPath),
+ $width,
+ $height,
+ $previewRoot,
+ );
+
+ return $preview + ['logoPath' => $logoPath];
+ }
+
+ /**
+ * @return array{result: \LibreSign\XObjectTemplate\Dto\CompileResult, pdf: string, previewPath: string}
+ */
+ private function compilePreviewWithSize(
+ string $slug,
+ string $html,
+ float $width,
+ float $height,
+ string $previewRoot,
+ ): array {
+ $this->ensureDirectoryExists($previewRoot);
+ $this->removeLegacyPreviewPngs($previewRoot, $slug);
+
+ $compiler = new XObjectTemplateCompiler();
+ $result = $compiler->compile(new CompileRequest(
+ html: $html,
+ width: $width,
+ height: $height,
+ ));
+
+ $pdf = (new SinglePagePdfExporter())->export($result);
+ $previewPath = $previewRoot . '/' . $slug . '.pdf';
+ file_put_contents($previewPath, $pdf);
+
+ return [
+ 'result' => $result,
+ 'pdf' => $pdf,
+ 'previewPath' => $previewPath,
+ ];
+ }
+
+ private function buildLayoutHtml(string $layout, string $backgroundPath, ?string $signaturePath): string
+ {
+ $background = sprintf(
+ '
',
+ $this->escapeAttribute($backgroundPath),
+ );
+
+ return match ($layout) {
+ 'signature_and_metadata_right' => sprintf(
+ '%s'
+ . '
'
+ . '
'
+ . '
'
+ . '
'
+ . '
Signed with LibreSign
'
+ . '
admin
'
+ . '
Issuer: Preview Issuer
'
+ . '
Date: 2026-05-28T16:40:21+00:00
'
+ . '
'
+ . '
%s'
+ . '
'
+ . '
'
+ . '
Signed with LibreSign
'
+ . '
Issuer: Preview Issuer
'
+ . '
Date: 2026-05-28T16:40:21+00:00
'
+ . '
'
+ . '
%s'
+ . '
'
+ . '
%s'
+ . '
'
+ . '
Signed with LibreSign
'
+ . '
admin
'
+ . '
Issuer: Preview Issuer
'
+ . '
Date: 2026-05-28T16:40:21+00:00
'
+ . '
'
+ . '
%s'
+ . '
'
+ . '
'
+ . '
'
+ . '
'
+ . '
'
+ . '
Signed with LibreSign
'
+ . '
Preview Issuer
'
+ . '
Date: 2026-05-28T16:40:21+00:00
'
+ . '
'
+ . '
'
+ . '
'
+ . '
'
+ . '
'
+ . '
'
+ . '
'
+ . '
Documento assinado digitalmente
'
+ . '
ASSINANTE DE EXEMPLO
'
+ . '
Data: 01/01/2026 12:00:00-0300
'
+ . '
Verifique em https://verificador.iti.br
'
+ . '
'
+ . '
%s'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
Signed with LibreSign
'
- . '
admin
'
- . '
Issuer: Preview Issuer
'
- . '
Date: 2026-05-28T16:40:21+00:00
'
- . '
'
- . '
%s'
- . '
'
- . '
'
- . '
Signed with LibreSign
'
- . '
Issuer: Preview Issuer
'
- . '
Date: 2026-05-28T16:40:21+00:00
'
- . '
'
- . '
%s'
- . '
'
- . '
%s'
- . '
'
- . '
Signed with LibreSign
'
- . '
admin
'
- . '
Issuer: Preview Issuer
'
- . '
Date: 2026-05-28T16:40:21+00:00
'
- . '
'
- . '
%s'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
Signed with LibreSign
'
- . '
Preview Issuer
'
- . '
Date: 2026-05-28T16:40:21+00:00
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
Documento assinado digitalmente
'
- . '
ASSINANTE DE EXEMPLO
'
- . '
Data: 01/01/2026 12:00:00-0300
'
- . '
Verifique em https://verificador.iti.br
'
- . '
'
- . '
Prepared for Demo User
'
. 'Document approved
',
+ 'width' => 260.0,
+ 'height' => 90.0,
'maxStreamLength' => 1200,
];
yield 'image with reference text' => [
'html' => ''
. 'ID 42',
+ 'width' => 260.0,
+ 'height' => 90.0,
'maxStreamLength' => 1400,
];
yield 'styled block with alignment and spacing' => [
'html' => 'Prepared by Styled User
',
+ 'width' => 260.0,
+ 'height' => 90.0,
'maxStreamLength' => 1800,
];
}
From a9923d66a8bc9d947b1921c241e11e81cd036dfb Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Mon, 1 Jun 2026 17:01:14 -0300
Subject: [PATCH 27/31] test: simplify visible stamp integration scenarios
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.../ExamplesOutputScenarioTest.php | 187 +-------
.../VisibleStampPreviewFactory.php | 318 --------------
.../VisibleStampTemplateScenarioTest.php | 398 +++++++++++++++---
3 files changed, 331 insertions(+), 572 deletions(-)
delete mode 100644 tests/Integration/VisibleStampPreviewFactory.php
diff --git a/tests/Integration/ExamplesOutputScenarioTest.php b/tests/Integration/ExamplesOutputScenarioTest.php
index f8ba52b..9334686 100644
--- a/tests/Integration/ExamplesOutputScenarioTest.php
+++ b/tests/Integration/ExamplesOutputScenarioTest.php
@@ -218,189 +218,4 @@ public static function integrationRenderingScenarioProvider(): iterable
'maxStreamLength' => 1800,
];
}
-
- #[DataProvider('visibleStampExampleScenarioProvider')]
- public function testVisibleStampScenariosAlsoGenerateExampleArtifacts(
- string $kind,
- string $slug,
- ?string $layout,
- float $width,
- float $height,
- int $expectedImageCount,
- array $expectedTexts,
- ): void {
- $projectRoot = dirname(__DIR__, 2);
- $outputRoot = $projectRoot . '/build/examples/visible-stamp';
- $factory = new VisibleStampPreviewFactory($projectRoot);
-
- if ($kind === 'phase_one') {
- if (!is_string($layout)) {
- throw new \InvalidArgumentException('Phase-one visible stamp scenario requires a layout identifier.');
- }
-
- ['result' => $result, 'pdf' => $pdf, 'previewPath' => $previewPath] = $factory->compilePhaseOneLayoutPreview(
- $slug,
- $layout,
- $outputRoot,
- );
-
- self::assertSame($width, $result->resources['XObject']['Im0']['Width']);
- self::assertSame($height, $result->resources['XObject']['Im0']['Height']);
- } else {
- [
- 'result' => $result,
- 'pdf' => $pdf,
- 'previewPath' => $previewPath,
- 'logoPath' => $logoPath,
- ] = $factory->compileGovBrLikePreview(
- $slug,
- $width,
- $height,
- $outputRoot,
- );
-
- self::assertSame($logoPath, $result->resources['XObject']['Im0']['Source']);
- }
-
- self::assertSame($expectedImageCount, count($result->resources['XObject'] ?? []));
- self::assertStringStartsWith('%PDF-', $pdf);
- self::assertStringContainsString('/Subtype /Form', $pdf);
- self::assertStringContainsString('/Im0 Do', $result->contentStream);
- self::assertFileExists($previewPath);
- self::assertSame($pdf, file_get_contents($previewPath));
- self::assertStringStartsWith($outputRoot . '/', $previewPath);
-
- foreach ($expectedTexts as $expectedText) {
- self::assertStringContainsString($expectedText, $result->contentStream);
- self::assertStringContainsString($expectedText, $pdf);
- }
- }
-
- /**
- * @return iterable
- * }>
- */
- public static function visibleStampExampleScenarioProvider(): iterable
- {
- foreach (self::visibleStampPhaseOneLayouts() as $name => $scenario) {
- yield 'phase one: ' . $name => [
- 'kind' => 'phase_one',
- 'slug' => $scenario['slug'],
- 'layout' => $scenario['layout'],
- 'width' => VisibleStampPreviewFactory::DEFAULT_PREVIEW_WIDTH,
- 'height' => VisibleStampPreviewFactory::DEFAULT_PREVIEW_HEIGHT,
- 'expectedImageCount' => $scenario['expectedImageCount'],
- 'expectedTexts' => $scenario['expectedTexts'],
- ];
- }
-
- $govBr = self::govBrLikeScenario();
- yield 'govbr-like' => [
- 'kind' => 'govbr',
- 'slug' => $govBr['slug'],
- 'layout' => null,
- 'width' => $govBr['width'],
- 'height' => $govBr['height'],
- 'expectedImageCount' => $govBr['expectedImageCount'],
- 'expectedTexts' => $govBr['expectedTexts'],
- ];
- }
-
- /**
- * @return iterable
- * }>
- */
- private static function visibleStampPhaseOneLayouts(): iterable
- {
- yield 'signature and metadata at right' => [
- 'slug' => 'signature-and-metadata-right',
- 'layout' => 'signature_and_metadata_right',
- 'expectedImageCount' => 2,
- 'expectedTexts' => [
- 'Signed with LibreSign',
- 'admin',
- 'Issuer: Preview Issuer',
- 'Date: 2026-05-28T16:40:21+00:00',
- ],
- ];
-
- yield 'label and metadata at right' => [
- 'slug' => 'label-and-metadata-right',
- 'layout' => 'label_and_metadata_right',
- 'expectedImageCount' => 1,
- 'expectedTexts' => [
- 'admin',
- 'Signed with LibreSign',
- 'Issuer: Preview Issuer',
- 'Date: 2026-05-28T16:40:21+00:00',
- ],
- ];
-
- yield 'signature centered' => [
- 'slug' => 'signature-centered',
- 'layout' => 'signature_centered',
- 'expectedImageCount' => 2,
- 'expectedTexts' => [],
- ];
-
- yield 'metadata only at top left' => [
- 'slug' => 'metadata-only-top-left',
- 'layout' => 'metadata_only_top_left',
- 'expectedImageCount' => 1,
- 'expectedTexts' => [
- 'Signed with LibreSign',
- 'admin',
- 'Issuer: Preview Issuer',
- 'Date: 2026-05-28T16:40:21+00:00',
- ],
- ];
-
- yield 'two columns with centered cells' => [
- 'slug' => 'two-columns-centered-cells',
- 'layout' => 'two_columns_centered_cells',
- 'expectedImageCount' => 2,
- 'expectedTexts' => [
- 'Signed with LibreSign',
- 'Preview Issuer',
- 'Date:',
- '2026-05-28T16:40:21+00:00',
- ],
- ];
- }
-
- /**
- * @return array{
- * slug: string,
- * width: float,
- * height: float,
- * expectedImageCount: int,
- * expectedTexts: list
- * }
- */
- private static function govBrLikeScenario(): array
- {
- return [
- 'slug' => 'govbr-like-visible-stamp',
- 'width' => 760.0,
- 'height' => 210.0,
- 'expectedImageCount' => 1,
- 'expectedTexts' => [
- 'Documento assinado digitalmente',
- 'ASSINANTE DE EXEMPLO',
- 'Data: 01/01/2026 12:00:00-0300',
- 'Verifique em https://verificador.iti.br',
- ],
- ];
- }
-}
\ No newline at end of file
+}
diff --git a/tests/Integration/VisibleStampPreviewFactory.php b/tests/Integration/VisibleStampPreviewFactory.php
deleted file mode 100644
index cc217f7..0000000
--- a/tests/Integration/VisibleStampPreviewFactory.php
+++ /dev/null
@@ -1,318 +0,0 @@
-ensureDirectoryExists($previewRoot);
- $this->ensureDirectoryExists($assetRoot);
-
- $backgroundPath = $this->createBackgroundPreview($assetRoot . '/background-' . $slug . '.png');
- $signaturePath = $this->layoutUsesSignatureImage($layout)
- ? $this->createSignaturePreview($assetRoot . '/signature-' . $slug . '.png')
- : null;
-
- return $this->compilePreviewWithSize(
- $slug,
- $this->buildLayoutHtml($layout, $backgroundPath, $signaturePath),
- self::DEFAULT_PREVIEW_WIDTH,
- self::DEFAULT_PREVIEW_HEIGHT,
- $previewRoot,
- );
- }
-
- /**
- * @return array{result: \LibreSign\XObjectTemplate\Dto\CompileResult, pdf: string, previewPath: string, logoPath: string}
- */
- public function compileGovBrLikePreview(
- string $slug,
- float $width,
- float $height,
- string $previewRoot,
- ): array {
- $logoPath = $this->projectRoot . '/tests/Fixtures/Pdf/Svg/govbr-logo.svg';
- if (!is_file($logoPath)) {
- throw new \InvalidArgumentException(sprintf('GovBR logo fixture was not found at "%s".', $logoPath));
- }
-
- $preview = $this->compilePreviewWithSize(
- $slug,
- $this->buildGovBrLikeLayoutHtml($logoPath),
- $width,
- $height,
- $previewRoot,
- );
-
- return $preview + ['logoPath' => $logoPath];
- }
-
- /**
- * @return array{result: \LibreSign\XObjectTemplate\Dto\CompileResult, pdf: string, previewPath: string}
- */
- private function compilePreviewWithSize(
- string $slug,
- string $html,
- float $width,
- float $height,
- string $previewRoot,
- ): array {
- $this->ensureDirectoryExists($previewRoot);
- $this->removeLegacyPreviewPngs($previewRoot, $slug);
-
- $compiler = new XObjectTemplateCompiler();
- $result = $compiler->compile(new CompileRequest(
- html: $html,
- width: $width,
- height: $height,
- ));
-
- $pdf = (new SinglePagePdfExporter())->export($result);
- $previewPath = $previewRoot . '/' . $slug . '.pdf';
- file_put_contents($previewPath, $pdf);
-
- return [
- 'result' => $result,
- 'pdf' => $pdf,
- 'previewPath' => $previewPath,
- ];
- }
-
- private function buildLayoutHtml(string $layout, string $backgroundPath, ?string $signaturePath): string
- {
- $background = sprintf(
- '',
- $this->escapeAttribute($backgroundPath),
- );
-
- return match ($layout) {
- 'signature_and_metadata_right' => sprintf(
- '%s'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
Signed with LibreSign
'
- . '
admin
'
- . '
Issuer: Preview Issuer
'
- . '
Date: 2026-05-28T16:40:21+00:00
'
- . '
'
- . '
%s'
- . '
'
- . '
'
- . '
Signed with LibreSign
'
- . '
Issuer: Preview Issuer
'
- . '
Date: 2026-05-28T16:40:21+00:00
'
- . '
'
- . '
%s'
- . '
'
- . '
%s'
- . '
'
- . '
Signed with LibreSign
'
- . '
admin
'
- . '
Issuer: Preview Issuer
'
- . '
Date: 2026-05-28T16:40:21+00:00
'
- . '
'
- . '
%s'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
Signed with LibreSign
'
- . '
Preview Issuer
'
- . '
Date: 2026-05-28T16:40:21+00:00
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
'
- . '
Documento assinado digitalmente
'
- . '
ASSINANTE DE EXEMPLO
'
- . '
Data: 01/01/2026 12:00:00-0300
'
- . '
Verifique em https://verificador.iti.br
'
- . '
'
- . '
+
+ Documento assinado digitalmente
+
+
+ ASSINANTE DE EXEMPLO
+
+
+ Data: 01/01/2026 12:00:00-0300
+
+
+ Verifique em https://verificador.iti.br
+
+
',
- width: 240.0,
- height: 84.0,
-));
-
-$payload = (new XObjectPayloadAdapter())->toXObjectPayload($result);
-$pdf = (new SinglePagePdfExporter())->export($result);
-
-file_put_contents(__DIR__ . '/build/preview.pdf', $pdf);
+```bash
+composer require libresign/xobject-template
```
-### Standalone PDF export
-
-`SinglePagePdfExporter` wraps a compiled XObject result into a one-page PDF whose `MediaBox` matches the compiled `bbox` size exactly.
-
-- The page size is derived from `$result->bbox`
-- Non-zero bounding boxes are translated back to the page origin automatically
-- Local PNG and JPEG image sources are embedded into the standalone PDF during export
-
-### Output contract
-
-- `$result->contentStream`: PDF operators ready for a Form XObject stream
-- `$result->resources`: font/image resource dictionary keyed for PDF serialization
-- `$result->bbox`: bounding box as `[x1, y1, x2, y2]`
-- `$result->metadata`: render diagnostics such as `line_count`, `image_count`, `node_count`, and `render_ms`
-- `$payload`: transport-agnostic array with `stream`, `resources`, and `bbox`
-- `$pdf`: standalone PDF bytes ready to save, stream, or attach to preview workflows
-
-### Scaling a compiled XObject
-
-`CompileRequest::width` and `CompileRequest::height` define the base design size of the template.
-If a downstream consumer needs to place the compiled stamp at a different size while preserving the
-original aspect ratio, it should keep the compiled XObject unchanged and apply a uniform scale during
-PDF placement instead of recompiling the HTML with new dimensions.
-
-- Read the base size from `$result->bbox`
-- Compute a single scale factor from the target width or target height
-- Apply the same scale to both axes in the placement matrix
+## Quick example
```php
-[$minX, $minY, $maxX, $maxY] = $result->bbox;
-
-$baseWidth = $maxX - $minX;
-$baseHeight = $maxY - $minY;
-
-$targetWidth = 175.0;
-$scale = $targetWidth / $baseWidth;
-$targetHeight = $baseHeight * $scale;
-
-// Consumer-side PDF placement concept:
-$placement = sprintf(
- 'q %F 0 0 %F %F %F cm /Fm0 Do Q',
- $scale,
- $scale,
- $x,
- $y,
-);
-```
-
-Using a uniform placement scale keeps text, images, spacing, and line breaks visually aligned.
-Recompiling only to emulate a proportional resize is usually the wrong integration point for this
-package.
+fromWidth($result, 175.0, 36.0, 72.0);
+$result = $compiler->compile(new CompileRequest(
+ html: '
`) and then converted to a PDF Form XObject by the current SVG implementation.
+
+## Typical use cases
+
+- deterministic logos,
+- deterministic icons,
+- deterministic vector shape overlays in signature appearances.
+
+## Important scope limits
+
+SVG support is intentionally scoped and deterministic. It is not a full browser-grade SVG engine.
+
+See [Reference / Supported SVG](../reference/supported-svg.md) for exact supported primitives, path commands, transforms, paint behavior, and known unsupported features.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..1a90464
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,39 @@
+
+
+
+# xobject-template
+
+`xobject-template` compiles a focused HTML+CSS subset into reusable PDF Form XObject payloads.
+
+It is designed for deterministic visual appearance generation in digital-signature and document-workflow systems: signature appearances, stamps, labels, and overlays.
+
+It solves a practical integration problem: many PDF signers can place Form XObjects but do not want to implement HTML/CSS rendering.
+
+## What this package does
+
+- Renders text from a minimal HTML/CSS subset.
+- Supports context interpolation for template personalization.
+- Supports PNG/JPEG image embedding through file sources.
+- Supports scoped SVG rendering through current implementation support.
+- Produces reusable output contracts (`contentStream`, `resources`, `bbox`, metadata).
+
+## What this package is not
+
+- A full PDF signer.
+- A browser engine.
+- A generic PDF editor.
+- A complete HTML/CSS/SVG renderer.
+
+## Start quickly
+
+Go to [Getting started](getting-started.md) for a runnable example based on `examples/basic-template.php`.
+
+## Key references
+
+- [Supported HTML and CSS](reference/supported-html-css.md)
+- [Supported SVG](reference/supported-svg.md)
+- [LibreSign use case](use-cases/libresign.md)
+- [Contributing](community/contributing.md)
+- [Sustainability](community/sustainability.md)
+
+If this package helps your project generate reliable PDF signature appearances, consider starring the repository, contributing a fixture, or sponsoring maintenance.
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..bb329b5
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,31 @@
+
+
+
+# Installation
+
+## Requirements
+
+From `composer.json`:
+
+- PHP: `^8.2`
+- Required PHP extensions: no explicit extra extensions declared by this package.
+
+Runtime notes:
+
+- The HTML parser uses `DOMDocument`.
+- Image metadata detection uses `getimagesizefromstring` for raster images.
+- The package reads local image files for image embedding/export workflows.
+
+## Install with Composer
+
+```bash
+composer require libresign/xobject-template
+```
+
+## Verify installation
+
+A quick verification is to run one example from this repository after dependencies are installed:
+
+- `examples/basic-template.php`
+
+See [Getting started](getting-started.md) for the exact flow and output expectations.
diff --git a/docs/reference/errors.md b/docs/reference/errors.md
new file mode 100644
index 0000000..b8e78fe
--- /dev/null
+++ b/docs/reference/errors.md
@@ -0,0 +1,38 @@
+
+
+
+# Errors and exceptions
+
+## Public exception to catch
+
+- `LibreSign\XObjectTemplate\Exception\UnsupportedSubsetException`
+ - Raised when HTML includes unsupported tags in the subset parser.
+
+## Common invalid argument failures
+
+`\InvalidArgumentException` can be raised by integration/export/image/SVG paths, for example:
+
+- invalid `bbox` for export/placement,
+- empty placement alias,
+- image source missing or unreadable,
+- unsupported image format,
+- invalid SVG/viewBox/path payload.
+
+## What users should do
+
+- Validate input templates against [Supported HTML and CSS](supported-html-css.md).
+- Validate SVG assets against [Supported SVG](supported-svg.md).
+- Keep reproducible template and asset fixtures for failing cases.
+
+## How to report a minimal reproducible issue
+
+Please include:
+
+- minimal HTML/CSS/SVG input,
+- compile request dimensions,
+- expected behavior,
+- actual behavior,
+- package version or commit hash,
+- PHP version and runtime context.
+
+See [Community / Contributing](../community/contributing.md) for reporting guidance.
diff --git a/docs/reference/limitations.md b/docs/reference/limitations.md
new file mode 100644
index 0000000..1d2ec6a
--- /dev/null
+++ b/docs/reference/limitations.md
@@ -0,0 +1,23 @@
+
+
+
+# Limitations
+
+`xobject-template` is intentionally scoped.
+
+## Explicit non-goals
+
+- Not a browser engine.
+- Not a full PDF signer.
+- Not a generic PDF editor.
+- Not a complete HTML/CSS/SVG renderer.
+
+## Rendering scope
+
+- HTML/CSS/SVG support is intentionally limited to deterministic overlay/stamp workflows.
+- Behavior is deterministic, but not browser-compatible.
+- Unsupported subset inputs should be treated as out of scope, not as promised behavior.
+
+## Integration expectation
+
+Consumers should validate templates that matter to their workflow and keep fixture-based regression tests for critical appearance requirements.
diff --git a/docs/reference/output-contract.md b/docs/reference/output-contract.md
new file mode 100644
index 0000000..67efc7f
--- /dev/null
+++ b/docs/reference/output-contract.md
@@ -0,0 +1,33 @@
+
+
+
+# Output contract
+
+`CompileResult` is the stable output boundary for integration.
+
+## Fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `contentStream` | `string` | PDF operators intended for a Form XObject stream body. |
+| `resources` | `array