konrad/NeitzelFXDesigner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document Designer workflows and qualify the real library example

Browse Source
This commit is contained in:
konrad
2026-11-13 23:04:20 +01:00
parent e865d7b4df
commit 83b9e4013d
13 changed files with 960 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-guide/architecture.md
+71
View File
@@ -0,0 +1,71 @@
# Architecture, development and troubleshooting
The host owns editing; the target owns application execution. This separation lets a JavaFX 26 editor design applications using the qualified JavaFX 21 runtime without importing their classes or native toolkit into the host.
```mermaid
flowchart TD
IDE[IntelliJ Documents and commands] --> HOST[Host service contracts]
APP[Standalone documents and windows] --> HOST
HOST <--> UI[Shared Kit 26 UI and lexical projection]
UI --> CORE[Shared workflow and validation]
CORE --> BUILD[Isolated Maven build and capture]
BUILD --> STORE[Immutable snapshot and leases]
CORE --> WORKER[Authenticated target JVM]
STORE --> WORKER
WORKER --> LIB[NeitzelLib ViewLoader and injection]
LIB --> MODEL[Fresh sample Model and ViewModel graph]
LIB --> VIEW[Real FXML Components and bindings]
WORKER --> PIXELS[Images and sizing metadata]
PIXELS --> UI
WORKER --> PREVIEW[Independent interactive preview window]
```
## Dependency boundaries
| Module | Responsibility |
| --- | --- |
| `designer-contracts` | Configuration, metadata and wire values; no Kit/IDE/application dependency |
| `designer-core` | Build/snapshot orchestration, lexical edits, workflow and host service interfaces |
| `designer-kit-ui` | Shared Kit UI, source projection, binding panels and diagnostics |
| `designer-standalone` | Local document/window implementation and launcher |
| `designer-intellij` | Native IDE Documents, commands, navigation, Problems and toolkit gate |
| `designer-preview-api` | Small Java 21 sample provider/session contract, optionally test-scoped in applications |
| `designer-target-tools` | Java 21 worker, runtime adapter, discovery and rendering |
| `designer-maven-plugin` | Captures Maven's effective application runtime for immutable snapshots |
| `designer-model-processor` | Optional Java 21 compile-time Model metadata and ViewModel generation |
The application depends on NeitzelLib FX/core/injection and its own JavaFX runtime, not the host. Preview providers depend on the small API; annotation processing depends on the processor. The target tool JARs are supplied by the host. The shared UI uses a narrow patched Kit source with recorded provenance; see [third-party notices](../../THIRD-PARTY-NOTICES.md). The Kit patch retains its BSD-3-Clause notice. The original Designer code currently has no assigned license, as the notices state; a public repository alone does not establish reuse permission. Retain the applicable third-party licenses and notices when redistributing those components. See [module boundaries](../module-host-boundaries.md) for extension points.
## Trust and lifecycle
Transport uses authenticated loopback sessions, random tokens delivered through an owner pipe, bounded messages and correlated build/document/request identities. Application stdout/stderr are logs, not protocol framing. Worker ownership is explicit: cancellation, editor close and owner death trigger bounded shutdown. Draft overlays use private copies and cannot mutate published snapshots. Process isolation does not restrict application file/network access.
Adding a host should implement the host service interfaces and reuse core/Kit; avoid putting host APIs into shared contracts. Supporting another runtime requires a target adapter and compatibility evidence, not loading the runtime in Kit. New binding authoring should use lexical edits tied to authoritative revisions, shared target validation and host command history. Protocol/schema versions are validated explicitly; never accept unsupported data by guessing.
## Development checks
`./mvnw -B -ntp verify` validates shared modules. The [README qualification commands](../../README.md#validate-the-foundation) additionally check exact local runtime artifacts, bytecode/linkage boundaries, native standalone workflows, target fixtures, lifecycle and IntelliJ packaging. Registered IDE tests are separate. Packaging creates a macOS app image/ZIP with a bundled runtime; it is not a graphical installer, signed public release or cross-platform qualification. Follow [distribution qualification](../standalone-distribution.md).
A fresh NeitzelLib rebuild may change JAR hashes without changing source. Use the normal development launch route while developing. Requalifying the recorded runtime requires regression XML inspection, source/class/artifact comparison, relevant adapter/host tests and deliberately updated provenance together. The [runtime record](../runtime/neitzellib-baseline.md) is explicit; a checksum mismatch must not be bypassed. The current snapshot coordinates identify local artifacts, not a published corrected release.
The [real fx-example qualification](quick-start.md#verify-this-reference-integration-automatically) tests actual application resources in a copied reactor and packaged host. Existing synthetic classpath/module-path fixtures remain useful for failure cases and native IDE regression; neither replaces testing application-specific services and behavior.
## Troubleshooting
| Symptom | Check and action |
| --- | --- |
| Configuration rejected | Schema version, unknown keys, explicit context, reactor-relative module and local full-JDK mappings |
| Build fails resolving Designer snapshot | Build/install Designer tools locally first; no public snapshot repository is assumed |
| Runtime hash gate fails after library install | Distinguish developer build from recorded qualification; follow deliberate requalification, do not rewrite hashes automatically |
| Source works, designer unavailable in IntelliJ | Exact qualified SDK, `embed.scene.builder=false`, restart, no preloaded incompatible Glass |
| Blank/stale Component image | Successful Build and Refresh, matching sample descriptor, Model PI, captured resource mapping and target logs |
| New preview refused after Java/POM change | Build again, or explicitly select last successful build with its outdated state |
| Child View has no sample | Add a descriptor matching that resource and a compatible fresh provider; rebuild |
| Preview fails loading a class/property | Verify the original application first, correct FXML/imports/JPMS access, inspect target logs; no broad opens are injected |
| Converter warning | Declare/test capabilities when supported; an unverified warning is distinct from a known incompatible binding |
| Metadata stale or duplicate | Clean build after processor/Model changes; ensure one owning source compilation emits it |
| Edit or fix rejected as stale | Refresh current source/diagnostics and repeat the intended action; no old ranges are applied |
| Unsupported enum/object projection | Keep runtime initialization in application code where appropriate, or edit Source; target execution support does not imply host property-editor support |
| Preview hangs or worker dies | Review readiness timeouts and nonblocking `ready()`, target logs and native crash files; use small fresh sample services |
Implementation pages linked throughout this manual retain dated historical results. Their earlier “next” sections describe those slices, not an override of this current guide. Remaining product boundaries include graphical setup, production handoff, broader platform/IDE qualification, signed release distribution, arbitrary FXML object editors and complete native accessibility qualification.