# Browser XSLT migration trial

This change uses the existing server-side Saxon path for full pages and a locally
bundled XSLTProcessor polyfill for AJAX fragments. Full pages arrive as HTML, so
their scripts run through normal browser page loading. No browser extension or
CDN is required.

## Deployment and activation

1. Deploy the changed ZymonicMP module, JavaScript and stylesheets together,
   including the new `javascript/Zymonic/XSLT.js` and
   `javascript/xslt-polyfill/` directory. Rebuild the combined stylesheets and
   customer/language variants through the normal deployment process, and refresh
   the system version used for asset caching. Reload the Apache workers as usual
   for a Perl module update.
2. Ensure `/usr/local/bin/saxon` works for the Apache user. This is the executable
   used by the existing full-page server renderer in `Zymonic::MP`; configuring a
   SaxonServlet for report generation does not configure that renderer.
3. Enable the existing configuration option in the trial system's definitions
   (update an existing definition if present):

   ```xml
   <ConfigOption>
     <OptionName>ServerSideXSLTUserAgents</OptionName>
     <OptionValue>.*</OptionValue>
   </ConfigOption>
   ```

   Apply it through the normal definition/configuration update process. It
   selects server rendering for all browser user agents. This patch does not
   change the default globally: without this setting, initial page loading still
   depends on native browser XSLT.
4. If a customer stylesheet replaces a complete page head, add
   `<xsl:call-template name="ZymonicXSLTIncludes" />` immediately after its
   `Zymonic/Zymonic.js` include, with jQuery already loaded. Remove its old combined
   stylesheet loader. Inheriting the standard page templates needs no such edit.

AJAX requests identified by `X-Requested-With: XMLHttpRequest` retain their XML
responses, unless they explicitly request `ZZxsl`. API/no-transform responses
remain raw, and non-XML responses are never sent to Saxon. Custom AJAX clients
which do not send that header should use the existing `notransform` parameter.

The shared loader holds jQuery's ready callbacks until both the polyfill and the
combined stylesheet are ready. A failure or 30-second timeout displays an error
and leaves initialisation held. Modern browsers use the polyfill even while
native XSLT exists; older browsers retain the native/ActiveX route. The existing
synchronous `Transformer.js` interface remains unchanged.

## Manual server/browser checks

Disable the browser extension and native XSLT (in Chrome, `chrome://flags/#xslt`)
for the trial. Check:

- A fresh login page and a full page reload return `text/html`, run the scripts
  and initialise menus and fields.
- Opening and refreshing a filter, submitting a process and updating a linked
  field work; their AJAX responses remain XML.
- Validation errors, session expiry/relogin and dynamically added scripts/CSS
  still work.
- Single-block/embedded pages and customer/language stylesheet variants work.
- Cold-cache startup waits for the engine and stylesheet; deliberately blocking
  either asset gives the startup error.
- Initial page response time and Apache load are acceptable: the existing
  renderer launches Saxon for each full-page response.

Custom combined stylesheets must be self-contained for the synchronous polyfill
API. External imports/includes or `document()` resources need separate review.
Browser-displayed XML reports and other entry points outside these UI page
templates are not migrated by this patch.

Only source review, JavaScript syntax checks and XML well-formedness checks were
performed locally. `perl -c` was blocked by missing `CGI::Apache2::Wrapper`.
Runtime behaviour remains unverified until the server/browser trial.

To roll back, restore the previous assets/module and previous configuration
value together. Native XSLT must still be available for the previous UI to work.