Document Designer workflows and qualify the real library example

2026-11-13 23:04:20 +01:00
parent e865d7b4df
commit 83b9e4013d
13 changed files with 960 additions and 0 deletions
@@ -0,0 +1,50 @@
+# Documentation and reference-example validation
+
+This record covers the current-guide/reference-example documentation slice on 2026-11-13. It does not replace the earlier complete Designer host qualification or turn skipped human checks into passes.
+
+## Coverage reviewed
+
+| Developer task | Current guide | Executable reference / evidence |
+| --- | --- | --- |
+| Start the application, then connect the editor | [Quick start](quick-start.md) | NeitzelLib `fx-example`, existing nine application regression tests |
+| Configure contexts, JDKs, Maven and sample services | [Projects](projects.md) | Checked-in library context, optional `designer-preview` profile, local settings helper |
+| Understand host/target/runtime dependencies | [Architecture](architecture.md) | Module boundary checks and exact local artifact manifest remain unchanged |
+| Use snapshots, draft overlays and separate previews | [Previews](previews.md) | Actual packaged host Build and Refresh, target Component pixels and fresh per-View samples |
+| Edit bindings, structures, diagnostics and fixes | [Authoring](authoring.md) | Existing shared/registered-host qualification; actual example metadata and no-error binding discovery |
+| Generate metadata, Java ViewModels and FXML | [Generation](generation.md) | Actual example generates Person/Address/Note metadata; existing generated-VM/FXML suites cover those features separately |
+| Install and use the plugin | [IntelliJ](intellij.md) | Exact SDK/toolkit guard and build scripts reviewed against source; no new SDK/platform qualification claimed |
+| Follow licensing and development boundaries | [Architecture](architecture.md) | Third-party notices, unlicensed original Designer code and local development snapshots distinguished |
+
+The library documentation separately explains MVVM, dependency injection and every runtime binding type. The Designer guide links to those concepts rather than claiming the editor creates application semantics. Reviewed corrections include Controller-based Computed methods (no direction/path/Converter), initial DirectBinding population in every direction, shared ObservableList behavior, direct Repeat/Table collection Attributes, the non-generic runtime ViewModel base and exact descriptor keys.
+
+## Repeatable checks
+
+With JDK 21 in the NeitzelLib checkout:
+
+```sh
+mvn -B -ntp -pl fx-example -am -Pdesigner-preview -Dmaven.test.failure.ignore=false verify
+mvn -B -ntp -pl fx-example -am -Dmaven.test.failure.ignore=false clean verify
+```
+
+The parent POM hardcodes failure-ignore; inspect all Surefire XML, not just the exit status. The profile run passed **127 tests** (core 1, injection 10, fx 105, fx-example 11). The subsequent clean ordinary build passed **125 tests** (the same runtime tests and fx-example 9), with zero failures, errors or skips in both runs. The clean ordinary output contained neither preview provider classes nor generated Designer metadata. No rebuilt library runtime artifacts were installed by these checks.
+
+With an already qualified app image, JDK 25 and target JDK 21, run `scripts/check-library-example.py` using the [quick-start command](quick-start.md#verify-this-reference-integration-automatically). It copies the real library checkout and app, injects an external test agent only into the disposable host, and verifies:
+
+- Build and Refresh of the real selected reactor and target pixels for `homeForm`;
+- generated Person metadata with no binding errors;
+- source editing, exact Undo/Redo and save through host documents;
+- Address Component source navigation and duplicate-window prevention;
+- per-document sample discovery and interactive loading for Desk, AddressForm, VisitForm, VisitRow and NoteForm;
+- worker exit after host disposal and no new native crash report.
+
+The test deliberately supplies known parent and child drafts together, as the production host does. An earlier test attempt omitted the saved parent's overlay when launching a child and correctly received `Build is outdated`; the test was corrected without weakening the product's current-build gate.
+
+The documentation reviewer independently compiled and ran the library's new-project JavaFX quick start and injection-only recipe. The generated-registry snippets also compiled and ran, verifying selected generated defaults, stored-property identity and UI write-back.
+
+The local settings helper was checked for creation and refusal to overwrite existing settings. Python syntax, guide relative links, JSON snippets and formatted Java sources were checked. `scripts/check-neitzellib-artifact.py` still passed all seven pinned artifact hashes for source `90e08b7`; no baseline hashes changed.
+
+Local disposable evidence is printed by each invocation. The first complete actual-example pass was under `/private/var/folders/0b/lyx5t31j6ns1mf4pw7sxksj40000gn/T/designer-library-example-xh0b17ty`; library logs were `/tmp/fx-example-designer-profile.log` and `/tmp/fx-example-normal-final.log`. A final rerun after test-script formatting also passed under `/private/var/folders/0b/lyx5t31j6ns1mf4pw7sxksj40000gn/T/designer-library-example-pe02j042` (`/tmp/designer-fx-example-final.log`). These paths are evidence locations on the test workstation, not required project inputs or published artifacts.
+
+## Qualification limits
+
+The actual `fx-example` integration uses classpath mode and the packaged standalone macOS host. Named-module and IntelliJ behavior remains covered by the pre-existing dedicated fixtures/host suites; this documentation slice does not claim that the actual nonmodular fx-example was converted to JPMS or independently rerun in IntelliJ. No manual testing, VoiceOver review, new OS/SDK validation, signed installer or public artifact publication was performed.