Modernize signature appearance templates and PDF rendering #9048

Goal

Create a reusable, safe and well-defined signature-appearance template architecture for LibreSign so visible signature/footer/stamp rendering can evolve independently from any AI feature.

This work must be useful and complete even when no AI provider is installed.

Motivation

LibreSign already has signature footer/template editing, preview behavior and native PDF appearance/XObject rendering, but these capabilities are not yet a single reusable contract for richer signature appearances.

Related existing needs include:

• PhpNative engine: non-ASCII characters in the signature stamp are rendered as mojibake #8155 — Unicode/non-ASCII rendering in the PhpNative signature stamp;
• Templates for a quicker workflow #5628 — reusable templates/workflows;
• existing footer/template editor and preview behavior.

Architecture goals

Define a stable contract for:

• supported appearance/template representation;
• allowed variables/placeholders;
• safe formatting/layout capabilities;
• validation and sanitization;
• preview behavior;
• PDF/XObject rendering;
• Unicode text handling;
• backward compatibility/migration for existing templates;
• renderer-specific responsibilities.

Do not expose arbitrary execution through templates.

If Twig or another template engine is used internally, define a deliberately restricted language. Do not allow arbitrary functions, filesystem access, includes/imports, remote resources or other behavior outside the appearance use case.

UX and prototype requirement

Before implementing a materially richer editor:

• review the current LibreSign footer and signature appearance flows;
• review relevant editor patterns from Nextcloud and signing/document tools;
• produce a concrete interaction proposal or prototype for the editor;
• define how variables, formatting, preview, validation errors and reset/default behavior are presented;
• validate that the editor remains usable without understanding template-engine internals.

The implementation should prefer direct manipulation and safe controls over asking administrators to author raw markup.

Security

Template input is untrusted configuration.

The implementation must:

• validate allowed structure and variables on the backend;
• sanitize any supported markup/style subset;
• reject or safely handle scripts, event attributes, remote resources and unknown/unsafe constructs;
• avoid filesystem/network access through template evaluation;
• ensure preview and final PDF rendering apply the same security contract;
• preserve signed-PDF integrity expectations.

Documentation

Document the signature appearance feature in the LibreSign documentation project as product documentation, including:

• default behavior;
• supported customization;
• variables/placeholders;
• preview and validation;
• administrator workflow;
• limitations;
• migration/compatibility considerations where users need to know them.

Add contextual help from the editor/settings UI when it improves discoverability.

Planning and downstream handoff

This epic is a prerequisite for #9049.

Do not prematurely define AI output as raw Twig/HTML or another representation before this epic establishes the actual appearance contract.

Before closing this epic:

1. review Add AI-assisted signature appearance authoring #9049 against the final appearance representation, variable registry, validation/sanitization rules, preview behavior and PDF rendering contract established here;
2. update Add AI-assisted signature appearance authoring #9049 where its assumptions differ from the completed architecture;
3. only then decompose Add AI-assisted signature appearance authoring #9049 into focused implementation issues.

Do not create a full implementation backlog for #9049 before this review.

Native GitHub relationships are the source of truth for blocking and sub-issue state.

Done when

• A single documented signature appearance contract exists.
• The editor/preview consumes that contract.
• Final PDF rendering consumes the same validated representation.
• Unicode behavior is defined and PhpNative engine: non-ASCII characters in the signature stamp are rendered as mojibake #8155 is resolved or incorporated through focused work.
• Unsafe template constructs are rejected.
• Existing supported templates have a migration/backward-compatibility path.
• The UX has been prototyped/reviewed before material editor changes.
• The feature is documented for administrators/users.
• The downstream AI authoring epic has been reviewed against the final contract.