NeitzelFXDesigner/docs/user-guide/architecture.md

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.

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. 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 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 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.

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 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 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.