`, `
`, ``, `
`, `![]()
`
+- Text fragments are normalized into inline text nodes internally
+- Inline styles are read from the `style` attribute
+- Images use the `src` attribute as the source reference included in the resource dictionary
+
+### CSS used by the renderer
+
+- Typography: `font-size`, `font-family`, `font-weight`, `line-height`, `color`
+- Layout: `margin`, `padding`, `text-align`, `width`, `height`
+- Numeric values can be provided as unitless numbers or `px`
+- `px` values are converted to PDF points using the package conversion rules
+- Unknown or incomplete CSS declarations are ignored instead of aborting the render
+
+### Rendering notes
+
+- Font family mapping currently targets the built-in Helvetica, Times, and Courier aliases used by the generated PDF resources
+- `img` width/height fall back to `32x32` when omitted or invalid
+- Image and text placement are clamped to the requested output box
+- The compiler output is not tied to any single downstream package; any consumer that understands Form XObject stream/resources/bbox data can use it
+
+## Failure modes
+
+- Unsupported HTML elements raise `UnsupportedSubsetException`
+- Malformed HTML fragments are normalized by `DOMDocument` before traversal
+- Empty text nodes and invalid inline-style fragments are ignored during parsing/rendering
diff --git a/composer.json b/composer.json
index 2f381d5..c985bcb 100644
--- a/composer.json
+++ b/composer.json
@@ -1,12 +1,14 @@
{
"name": "libresign/xobject-template",
- "description": "Minimal HTML+CSS to PDF Form XObject compiler for visible signature appearance.",
+ "description": "Minimal HTML+CSS to reusable PDF Form XObject compiler.",
"type": "library",
"license": "AGPL-3.0-or-later",
"keywords": [
"pdf",
"xobject",
- "signature",
+ "template",
+ "rendering",
+ "layout",
"html",
"css"
],
@@ -59,7 +61,6 @@
"composer:validate": "composer validate --strict",
"composer:normalize:check": "vendor-bin/qa/vendor/ergebnis/composer-normalize/bin/composer-normalize --dry-run",
"bc:check": "vendor-bin/qa/vendor/roave/backward-compatibility-check/bin/roave-backward-compatibility-check --from=origin/main --to=HEAD",
- "licenses:check": "php scripts/licenses-check.php",
"changelog:check": "echo 'Handled by GitHub Action: .github/workflows/changelog.yml'",
"release:draft": "echo 'Handled by GitHub Action: .github/workflows/release-draft.yml'",
"deps:audit": "composer audit",
diff --git a/scripts/licenses-check.php b/scripts/licenses-check.php
deleted file mode 100644
index 1c00e8d..0000000
--- a/scripts/licenses-check.php
+++ /dev/null
@@ -1,37 +0,0 @@
-
+ *
+ * @throws UnsupportedSubsetException If the HTML fragment contains an element outside the supported subset.
*/
public function parse(string $html): array
{
diff --git a/src/Integration/SignatureAppearanceXObjectAdapter.php b/src/Integration/XObjectPayloadAdapter.php
similarity index 75%
rename from src/Integration/SignatureAppearanceXObjectAdapter.php
rename to src/Integration/XObjectPayloadAdapter.php
index 38463e4..cf5f796 100644
--- a/src/Integration/SignatureAppearanceXObjectAdapter.php
+++ b/src/Integration/XObjectPayloadAdapter.php
@@ -9,10 +9,10 @@
use LibreSign\XObjectTemplate\Dto\CompileResult;
-final class SignatureAppearanceXObjectAdapter
+final class XObjectPayloadAdapter
{
/**
- * Output compatible with consumers expecting stream/resources pair.
+ * Output compatible with consumers expecting a generic Form XObject payload.
*
* @return array{
* stream: string,
@@ -20,7 +20,7 @@ final class SignatureAppearanceXObjectAdapter
* bbox: array{0: float, 1: float, 2: float, 3: float}
* }
*/
- public function toPdfSignerPayload(CompileResult $result): array
+ public function toXObjectPayload(CompileResult $result): array
{
return [
'stream' => $result->contentStream,
diff --git a/src/XObjectTemplateCompiler.php b/src/XObjectTemplateCompiler.php
index f2b6545..2154712 100644
--- a/src/XObjectTemplateCompiler.php
+++ b/src/XObjectTemplateCompiler.php
@@ -10,6 +10,7 @@
use LibreSign\XObjectTemplate\Contract\XObjectTemplateCompilerInterface;
use LibreSign\XObjectTemplate\Dto\CompileRequest;
use LibreSign\XObjectTemplate\Dto\CompileResult;
+use LibreSign\XObjectTemplate\Exception\UnsupportedSubsetException;
use LibreSign\XObjectTemplate\Html\SubsetHtmlParser;
use LibreSign\XObjectTemplate\Layout\LinearLayoutEngine;
use LibreSign\XObjectTemplate\Pdf\ColorParser;
@@ -37,6 +38,11 @@ public function __construct(
);
}
+ /**
+ * Compile the supported HTML+CSS subset into a reusable PDF Form XObject payload.
+ *
+ * @throws UnsupportedSubsetException If the HTML fragment contains an unsupported element.
+ */
public function compile(CompileRequest $request): CompileResult
{
$start = hrtime(true);
diff --git a/tests/Fixtures/overlay-basic.html b/tests/Fixtures/overlay-basic.html
new file mode 100644
index 0000000..83f5d44
--- /dev/null
+++ b/tests/Fixtures/overlay-basic.html
@@ -0,0 +1,2 @@
+Prepared for {{display_name}}
+Reference: {{reference}}
diff --git a/tests/Fixtures/signature-basic.html b/tests/Fixtures/signature-basic.html
deleted file mode 100644
index 399f180..0000000
--- a/tests/Fixtures/signature-basic.html
+++ /dev/null
@@ -1,2 +0,0 @@
-Signed by {{signer_name}}
-Reason: {{reason}}
diff --git a/tests/Integration/VisibleSignatureBusinessRuleTest.php b/tests/Integration/XObjectRenderingScenarioTest.php
similarity index 64%
rename from tests/Integration/VisibleSignatureBusinessRuleTest.php
rename to tests/Integration/XObjectRenderingScenarioTest.php
index aae663e..e2ddd7c 100644
--- a/tests/Integration/VisibleSignatureBusinessRuleTest.php
+++ b/tests/Integration/XObjectRenderingScenarioTest.php
@@ -12,10 +12,10 @@
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
-final class VisibleSignatureBusinessRuleTest extends TestCase
+final class XObjectRenderingScenarioTest extends TestCase
{
- #[DataProvider('signatureScenarioProvider')]
- public function testVisibleSignatureTemplateScenarios(string $html, int $maxStreamLength): void
+ #[DataProvider('renderingScenarioProvider')]
+ public function testReusableXObjectScenarios(string $html, int $maxStreamLength): void
{
$compiler = new XObjectTemplateCompiler();
$result = $compiler->compile(new CompileRequest(html: $html, width: 260.0, height: 90.0));
@@ -30,22 +30,23 @@ public function testVisibleSignatureTemplateScenarios(string $html, int $maxStre
/**
* @return iterable
*/
- public static function signatureScenarioProvider(): iterable
+ public static function renderingScenarioProvider(): iterable
{
- yield 'signer name and status' => [
- 'html' => 'Signed by Demo User
Document approved
',
+ yield 'title and status block' => [
+ 'html' => 'Prepared for Demo User
'
+ . 'Document approved
',
'maxStreamLength' => 1200,
];
- yield 'signer with image mark' => [
- 'html' => '
'
+ yield 'image with reference text' => [
+ 'html' => '
'
. 'ID 42',
'maxStreamLength' => 1400,
];
- yield 'styled signer with alignment and spacing' => [
+ yield 'styled block with alignment and spacing' => [
'html' => 'Signed by Styled User
',
+ . 'margin:6;padding:2;width:220">Prepared by Styled User
',
+ width: 240.0,
+ height: 84.0,
+));
+
+$payload = (new XObjectPayloadAdapter())->toXObjectPayload($result);
+```
+
+### 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`
+
+## Supported HTML/CSS subset
+
+### HTML
+
+- Supported elements: `
',
+ 'html' => '