Build requirements and assets

These values describe this checkout, version 1.2.1.

ShellBuilder emits framework CSS before custom CSS and deferred scripts in this order: HTMX when enabled, framework JavaScript, custom JavaScript. Serving these URLs is the host application's responsibility. The site supplies Spring static-resource handling and a lite WebJars locator for the versionless HTMX URL. The site uses Boot's spring-boot-starter-webmvc and test-scoped spring-boot-starter-webmvc-test; it does not require legacy locator-core or Jackson 2 databind. The library remains independent of Spring.

The official site locally serves the Highlight.js 11.12.0 browser common bundle at /vendor/highlightjs/11.12.0/highlight.min.js for optional, progressive snippet highlighting. Its BSD 3-Clause license and copyright notice are packaged at /vendor/highlightjs/11.12.0/LICENSE (site/src/main/resources/static/vendor/highlightjs/11.12.0/LICENSE in the checkout). The upstream source is the npm package @highlightjs/cdn-assets 11.12.0 tarball; this is provenance, not a runtime CDN. The asset adds no Maven or npm production dependency. The site's private script enriches explicitly labeled code in the initial document and HTMX-loaded fragments when the bundled grammar recognizes the language or alias. Unknown, unlabelled, text and Mermaid blocks remain plain text; there is no diagram renderer. Server-escaped text remains readable without JavaScript. This is site presentation, not a library API or an automatic asset promise for consumer applications.

The site overrides Boot's dependency properties with jackson-bom.version=3.1.7 and tomcat.version=11.0.27; Jackson annotations remain 2.21. These use the parent POM's property mechanism, not an unmodified, vendor-tested Boot dependency set. They do not establish future support or security certification for the site or consumer applications.

Page renders content/layout without a complete HTML document. ShellBuilder.build() and ShellTemplate.render(...) return complete documents. ShellBuilder.buildBody() returns body content. Template shell mode uses its explicit content slot and does not auto-load /home.

HTMX configuration ownership

Full documents and compiled shell templates that include HTMX preserve three 1.x defaults: selfRequestsOnly: false, methodsThatUseUrlParams: ['get'], and scrollBehavior: 'smooth'. DELETE form data therefore stays in the request body, and HTMX's own default scrolling stays smooth. These are compatibility choices, not a destination-security policy.

A private generated head marker lets the existing framework script initialize those values before deferred custom scripts. It is an implementation detail, not an application configuration API. Immediate assignments in custom JS and its DOMContentLoaded handlers remain authoritative. An explicit upstream meta[name="htmx-config"] is merged later by HTMX and also overrides these initial values. Defaults are not reapplied after swaps, insertion, or settle. A standard compatibility meta alone would overwrite immediate deferred custom-script choices during HTMX initialization; the shell does not generate that meta.

withHtmx(false) emits neither the HTMX asset nor the private marker. buildBody() emits no assets, scripts, or marker in either mode. Loading framework JS in an unmarked, manually assembled host does not change HTMX defaults. Such hosts must explicitly choose their request policy before issuing requests. For example, to select the legacy defaults with the existing upstream mechanism:

<meta name="htmx-config" content='{"selfRequestsOnly":false,"methodsThatUseUrlParams":["get"],"scrollBehavior":"smooth"}'>

Use ordinary upstream configuration for a different policy. Applications own allowed destinations, CORS responses, CSRF issuance/verification, authentication, and authorization. Permitting cross-origin requests here does not grant a browser CORS exemption or make an endpoint safe.

Form header compatibility boundary

With the bundled HTMX and framework JS loaded once, a delegated htmx:configRequest handler recovers missing Object.prototype-name headers, including __proto__, from the source FORM's own hx-headers attribute. The attribute must be literal JSON containing lexically exactly one string pair; duplicate textual pairs, multiple pairs, expressions, non-string values, ancestor-only attributes, and non-form sources are outside this repair. No .form CSS class is required. A hand-authored form with the same observable shape also qualifies; DOM markup carries no Java provenance.

The handler defines a missing own data property without changing the header object's prototype. Existing own case-insensitive spellings, including null, accessors, and non-enumerable entries, remain untouched; nonextensible maps and earlier cancellation are respected. Later application listeners may override or cancel normally. Ordinary headers deliberately deleted by an application are not regenerated. To suppress a collision header explicitly, use an own null entry or cancel; a deleted collision is indistinguishable from upstream omission at this event stage.

This is not a general HTMX options merger. An ajax options __proto__ entry discarded by upstream before configRequest cannot be recovered as that earlier override; use an own event-stage entry for that case. Stopped propagation and host-controlled header maps retain their normal ownership. No inherited/evaluated-header parser, retry, alternate transport, header rename, or token verification is supplied. Form's raw JSON, getters, null-string behavior, attribute order, and UTF-16 representation are unchanged. Exact JSON representability is broader than legal browser HTTP-header transport.

Build outputs

• Library JAR: simplypages/target/simplypages-1.2.1.jar
• Executable site JAR: site/target/simplypages-site.jar
• Generated API docs: simplypages/target/reports/apidocs/
• Packaged guide source: site/target/classes/static/docs/
• Packaged API docs: site/target/classes/static/javadocs/

The reactor and each independent module POM enforce JDK [21,) and Maven [3.10.0,4). Both modules target Java 21 class files (major version 65), including when built with a later JDK. Use the wrapper rather than a system Maven.

The POMs pin build plugins and output timestamps. The library attaches source and Javadoc JARs at package time. Javadoc uses all,-missing with warnings fatal: structural lint is required, but missing API prose is not a build failure or evidence of complete documentation.

The site build checks that generated Javadocs are present. ./build-site.sh runs a clean reactor package with tests skipped and uses Python 3 to verify the exact docs and Javadoc inventories and bytes in the executable JAR. Python is not required to run that portable JAR; skipped tests do not produce the fixtures required by the browser harness. Run it locally with java -jar site/target/simplypages-site.jar. ./deploy.sh accepts no arguments and forwards to the local build; it never deploys remotely. Use a reactor build such as ./mvnw clean install before running the site independently. ./mvnw clean verify runs the Maven verification lifecycle; browser tests are a separate command in the build guide. There is no automatic coverage, SBOM, continuous security, or remote CI acceptance gate claimed here. Public artifact publication to Maven Central is not part of this release. Install the library locally or use your team's artifact repository. GitHub release v1.2.1 provides the library JAR, sources, Javadocs, and POM; it does not deploy the website.

Beta status, known issues, and support

Version 1.2.1 is a controlled beta, not an unqualified production-readiness claim. The support baseline is Java 21 or later and local Chromium checks at desktop and mobile viewports. Mobile viewports do not certify physical devices. Other browsers, native Windows, and remote CI remain unverified.

Known open issues:

• #81: Private chat shutdown warning: the site currently catches IllegalStateException during terminal emitter completion to address the recycled-response destroy warning. That warning was absent in two packaged SIGTERM reproductions with 64 streams. The 30-second graceful shutdown timeout and async timeout warnings remained, so these checks do not establish that all shutdown issues are resolved. No leak has been proven; this is not evidence of a general framework chat crash.
• #84: Documentation completeness: remaining API catalog, missing-Javadoc, and executable-example coverage are follow-up work, not complete today. The 100-warning display cap is not a count of documentation debt.

The site defaults to loopback. Editing and forum use temporary session-owned sandboxes; chat owns a separate session conversation. The site implements same-origin/CSRF checks and browser token/form wiring. These examples provide no production authentication, durable storage, rate protection, or production guarantees. /demos/recovery provides an explicit editing/forum reset; chat uses its own Start New control. Neither recovery path automatically replays an action. Hosts own HTTP security, authorization, persistence, and request policy; the HTMX defaults and bounded Form-header repair above do not provide those controls. Report reproducible problems through the linked GitHub issues without including credentials or private data.

Licensing, remote website deployment, and Maven Central publication are outside this release; this status section does not grant rights, certify a deployment, or assert that unrun checks passed.

Build and documentation tasks · All reference