Document the current signature appearance and preview pipeline

[vitormattos]

Goal

Document the current LibreSign signature appearance, footer/template, preview and PDF rendering pipeline so contributors can understand the existing behavior before the future reusable appearance contract is defined.

This issue documents behavior that already exists.

Do not design the future template format, fix Unicode rendering, change the editor, or add AI-assisted authoring.

This documentation will be used as factual input by LibreSign/libresign#9061.

Why this is a good first issue

The current behavior is already implemented and covered by code/tests.

The contributor does not need to decide:

• what the future template language should be;
• whether LibreSign should use Twig, HTML, JSON/AST or another representation;
• how #8155 should be fixed;
• how AI generation should work;
• how the editor should be redesigned.

The task is to trace the existing data flow and document it accurately using the sources listed below.

If a behavior cannot be confirmed, do not guess. Comment on this issue with the unresolved point.

Documentation destination

Create:

developer_manual/architecture/signature-appearance.rst

Do not move or rename:

developer_manual/architecture.rst

Update developer_manual/architecture.rst so its "Where to go next" section links to the new page.

Update the developer manual toctree only as needed so Sphinx includes the page.

Do not reorganize unrelated documentation.

Sources to inspect

Policy/editor configuration

Inspect the existing signature footer/appearance settings, including at least:

• src/views/Settings/PolicyWorkbench/settings/signature-footer/model.ts
• src/views/Settings/PolicyWorkbench/settings/signature-footer/realDefinition.ts
• src/views/Settings/PolicyWorkbench/settings/signature-footer/SignatureFooterRuleEditor.vue
• related policy definitions/providers under lib/Service/Policy/Provider/

Document only currently supported settings and behavior.

Preview path

Inspect at least:

• lib/Controller/SignatureStampPreviewController.php
• lib/Service/SignatureStampPreview/SignatureStampPreviewNativeService.php
• related classes under lib/Service/SignatureStampPreview/

Trace:

• where preview input comes from;
• how values/placeholders are resolved;
• how appearance data is built;
• what preview output represents.

Final signing/rendering path

Inspect at least:

• lib/Handler/SignEngine/PhpNativeHandler.php
• lib/Handler/SignEngine/Pkcs12Handler.php
• any appearance/XObject DTO/builder classes used by the native path.

Document the responsibility boundary between LibreSign and the signing library.

Do not document private library behavior that LibreSign does not rely on.

Current variables/elements

Inspect:

• lib/Service/SignerElementsService.php
• signature-text/template services used by the current appearance path;
• relevant policy/model definitions.

Create a verified inventory of current variables/placeholders or render elements that are actually supported.

Do not invent aliases or planned variables.

Tests

Use current tests as behavioral evidence.

Inspect at least:

• tests/php/Unit/Service/SignatureStampPreviewNativeServiceTest.php
• tests/php/Unit/Controller/SignatureStampPreviewControllerTest.php
• tests/php/Unit/Handler/SignEngine/PhpNativeHandlerTest.php
• relevant frontend/Playwright tests for signature footer/template editing.

Use tests to confirm edge cases and renderer behavior.

Known limitation

Read #8155.

Document it only as a current known limitation where relevant.

Do not propose or implement the fix in this documentation task.

Required page structure

The new page must use this structure.

1. What a signature appearance is

Explain the distinction between:

• the cryptographic/digital signature;
• the optional visible appearance rendered in the PDF.

Do not imply that a visible appearance is required for signature validity.

Cross-reference existing documentation if this distinction is already explained elsewhere.

2. Current configuration sources

Document where current appearance/footer settings come from.

Explain the role of Policy Workbench and any user/request-specific inputs that actually exist.

Do not describe planned configuration.

3. Current data flow

Provide a concise flow diagram or ordered list covering the current path from configuration/input to preview/final rendering.

The diagram must be based on verified code.

For example, identify boundaries such as:

policy/configuration -> appearance values -> preview/render builder -> signing handler -> PDF appearance

Do not use this example literally if the code shows a different boundary.

4. Preview pipeline

Explain:

• preview controller/service responsibility;
• how sample/preview signer/document data is used;
• what preview is intended to represent;
• important differences between preview and final signing, if verified.

5. Final PDF rendering

Explain:

• where final appearance rendering is triggered;
• the responsibility of PhpNativeHandler;
• how appearance/XObject data reaches the signing engine;
• renderer-specific behavior that LibreSign currently depends on.

6. Current variables and render modes

Provide a verified table containing, where applicable:

• variable/element name;
• meaning;
• source value;
• where it is consumed;
• relevant limitation.

Also document current render modes exposed by SignerElementsService or equivalent source.

Do not list anything that cannot be confirmed in code/tests.

7. Validation and escaping

Document current validation/escaping/sanitization behavior that is explicitly implemented.

If the current implementation has no generic sanitizer for a particular input, say only what can be verified; do not claim a stronger security guarantee.

8. Unicode and font limitations

Document #8155 as a current limitation of the relevant native rendering path.

State observed/current behavior and scope.

Do not choose a future font/encoding strategy.

9. Renderer differences

Document only differences between supported signing/rendering paths that are relevant to visible appearance behavior and are confirmed by code/tests.

Do not attempt to make engines identical in this issue.

10. Testing map

Explain which existing tests cover:

• template/policy model;
• preview behavior;
• final native rendering;
• relevant browser/editor behavior.

Point to representative test files.

11. Related architecture

Cross-reference:

• the main developer architecture page;
• testing documentation;
• relevant PDF/signing documentation if it already exists.

Do not duplicate those pages.

Writing requirements

Write for a developer who understands PHP/TypeScript/PDF concepts but has not traced LibreSign's appearance pipeline before.

Use these rules:

• explain product/domain concepts before class names;
• describe current behavior in present tense;
• distinguish visible appearance from digital-signature validity;
• do not narrate the research process;
• do not describe #9061's future contract as implemented;
• do not recommend a future template language;
• keep code excerpts very small and only when they clarify a public/internal contract;
• every technical claim must be traceable to current code/tests;
• use cross-references instead of repeating general signing/PDF concepts;
• use synthetic example values only.

Evidence rule

Before documenting a behavior, confirm it through current implementation, tests or repository guidance.

If two render paths behave differently:

• document the difference if verified and relevant;
• do not "normalize" the description;
• do not modify production behavior;
• comment on this issue if it is unclear whether the difference is intentional.

Screenshots

Because this PR changes rendered documentation, the pull request must include screenshots of the rendered page. Repository-wide contribution guidance for this rule is tracked by #46; this issue's screenshot requirement applies even if #46 is still open.

For this page:

• include at least one screenshot showing the new page title and current-pipeline overview;
• include focused screenshots for tables/diagrams if they are not readable in the first image;
• screenshots are PR review evidence and do not need to be committed into the manual unless an image is itself required by the documentation.

Do not include personal/customer data.

Out of scope

Do not:

• modify LibreSign application code;
• fix #8155;
• add or remove template variables;
• change render modes;
• redesign Policy Workbench;
• choose a future template grammar;
• change preview behavior;
• change PDF/XObject rendering;
• implement AI-assisted authoring;
• restructure unrelated documentation.

Validation

Before opening the PR:

1. build the developer manual using the repository's documented build flow;
2. verify the new page is reachable from the developer architecture documentation;
3. verify Sphinx cross-references resolve;
4. verify every named source path/class exists;
5. compare the page against current tests to ensure it does not overstate behavior;
6. review the rendered page;
7. include required screenshots in the PR description.

Done when

• developer_manual/architecture/signature-appearance.rst exists.
• The main architecture page links to it.
• The visible-appearance concept and current configuration sources are documented.
• The preview and final rendering pipelines are documented.
• Current variables/elements and render modes are inventoried from code.
• Current validation/escaping behavior is documented without overclaiming.
• #8155 is documented as a current limitation, not solved here.
• Representative tests are mapped to the documented behavior.
• Sphinx build/checks pass.
• The PR includes screenshots of the rendered documentation.