NeitzelFXDesigner/README.md

# Neitzel FX Designer

Shared Scene Builder Kit designer for NeitzelLib FX, with minimal standalone and IntelliJ hosts.

## Current state

The first workflow is runnable in both hosts: Build and Refresh publishes immutable snapshots; authenticated target workers discover examples and render parent/Component FXML drafts into the shared Kit canvas. Source and supported canvas edits use host-owned documents and undo/redo. See [the connected workflow](docs/first-connected-workflow.md) for architecture, launch commands, evidence and limits.

The repository builds six shared Maven modules, a Maven capture plugin and a separate IntelliJ adapter plugin. Application code runs only in target JVMs. The shared UI now applies [source-preserving edits](docs/source-preserving-projection.md), supports nested/anonymous Components and fx:root bodies, and provides Source/Design/Split modes. Retained [target sessions, target sizing, interactive preview and Component/Row navigation](docs/target-runtime-sessions.md) now extend that workflow. The shared [binding discovery browser](docs/binding-discovery.md) now lists declared Model paths and direction-aware target compatibility. The [DirectBinding inspector](docs/direct-binding-inspector.md) creates, edits and removes declarations through source-preserving host Undo/Redo. Shared [Converter discovery and binding validation](docs/converter-validation.md) now adds capability-based proposals, document diagnostics and preview gating. [Custom ViewModel discovery and Computed-binding validation](docs/viewmodel-computed-validation.md) now follow the explicitly selected Controller or Component in both hosts. The [Computed-binding inspector](docs/computed-binding-inspector.md) now creates, changes and removes Computed declarations with method suggestions and shared source-preserving Undo/Redo. The [Repeat inspector](docs/repeat-binding-inspector.md) adds source-preserving collection declarations with host Undo/Redo and [collection/Component compatibility discovery](docs/repeat-compatibility.md). The shared [Table/Column inspector](docs/table-column-inspector.md) adds source-preserving Table configuration, ordered Column authoring and explicit Row navigation, now with [Table-specific compatibility and declared Row alignment discovery](docs/table-compatibility.md). The shared [reference-safe Structure editor](docs/reference-safe-structure.md) now renames identifiers, copies subtrees with fresh identifiers and deletes associated bindings through source-preserving host Undo/Redo, including destination validation for cross-View paste. The [shared Problems panel and IntelliJ Problems integration](docs/shared-diagnostics.md) now expose current diagnostics with authoritative FXML navigation and editor-scoped cleanup. Broader discovery, generation and product packaging remain later work.

Configuration 1.0 schemas, context selection, local JDK mappings and draft protocol validation are now executable. See [configuration and protocol](docs/configuration-and-protocol.md) for formats and validation rules.

The shared [Build and Refresh workflow](docs/build-and-refresh.md) now builds isolated reactor copies and publishes immutable, leased snapshots, with explicit save approval and last-successful-build selection.

The [preview API and target adapter](docs/preview-target-fixtures.md) are validated with real classpath and named-module NeitzelLib applications, including bindings, rendering, readiness and cleanup. Each preview session requires a fresh target JVM.

The Component builder fix is integrated in NeitzelLib main. A [verified local development snapshot](docs/runtime/neitzellib-baseline.md) is recorded with source/artifact identity; a corrected released version is still unestablished. NeitzelLib sources are not copied here; the narrow Kit text-selection patch has explicit provenance and regression coverage.

## Validate the foundation

Requirements: JDK 25 for builds, JDK 21 for target linkage validation, Python 3.10+, the recorded local NeitzelLib artifacts, and IntelliJ IDEA SDK build **263.7307.200**. Downloads require network access. Set `JAVA_HOME` to JDK 25 and supply explicit local paths:

```sh
python3 scripts/check-bootstrap.py --idea-home "$IDEA_HOME" --target-java-home "$TARGET_JAVA_HOME"
```

On macOS `IDEA_HOME` points to the IDE application's `Contents` directory. The current SDK check uses its macOS product-info layout; other platforms are not qualified. The command checks runtime artifact hashes, clean-builds/installs the Maven modules, tests the adapters, checks bytecode baselines, runs target linkage under the supplied target JDK, builds the plugin ZIP, runs the real Maven snapshot and target-preview fixtures, checks the connected workflow in both document adapters and native standalone Kit windows, and validates documentation. Real registered IntelliJ UI qualification is a separate command below. It does not install or publish NeitzelLib.

Maven is pinned to **3.9.11** (Wrapper **3.3.4**); the separate IntelliJ build uses **Gradle 9.1.0** and IntelliJ Platform Gradle Plugin **2.20.1**. Wrapper distributions have pinned checksums. Shared-module-only validation is `./mvnw -B -ntp clean verify`; it does not qualify IntelliJ packaging. Plugin output is under `designer-intellij/build/distributions/`.

## Run the minimal hosts

After the full build, launch a disposable fixture with either command; add `--mode modulepath` for named modules:

```sh
python3 scripts/run-fixture-host.py standalone --java-home "$JAVA_HOME" --target-java-home "$TARGET_JAVA_HOME"
python3 scripts/run-fixture-host.py intellij --java-home "$JAVA_HOME" --target-java-home "$TARGET_JAVA_HOME" --idea-home "$IDEA_HOME"
```

The IntelliJ launcher isolates settings/plugins and disables bundled Scene Builder embedding while retaining JavaFX/FXML language support. Select **Neitzel Designer**, then **Build and Refresh**. Both hosts use JavaFX/Kit 26, with the fixture application running separately on Java 21 / JavaFX 21.0.7.

Qualify the registered editor and loaded JavaFX natives in real disposable IDE windows:

```sh
python3 scripts/check-ide-host.py --java-home "$JAVA_HOME" --target-java-home "$TARGET_JAVA_HOME" --idea-home "$IDEA_HOME"
```

Worker startup cancellation and ready-preview cleanup are covered by the [native lifecycle regression](docs/native-worker-lifecycle.md); host checks also reject new native JVM crash reports.

These graphical checks require a macOS desktop session; other platforms are not qualified. See [workflow limits](docs/first-connected-workflow.md#limits-and-next-stage) before using arbitrary application documents.

## Implementation references

- [Initial project contract](docs/initial-project-contract.md): module responsibilities, configuration, snapshots, runtimes, preview sessions and communication.
- [Repository bootstrap plan](docs/repository-bootstrap-plan.md): ordered work packages and acceptance gates. Bootstrap work packages 1–7 are implemented; source-preserving projection is implemented and its [manual drag/resize gate](docs/manual-input-validation.md) passed in both hosts on the recorded baseline. Stage 3 now implements [target-runtime sessions, sizing and navigation](docs/target-runtime-sessions.md), with [manual passes and explicitly skipped remaining checks](docs/manual-runtime-navigation.md) recorded.
- [Decision provenance](docs/provenance.md): workspace planning and captured prototype evidence.
- [Third-party notices](THIRD-PARTY-NOTICES.md): Maven wrapper and patched Kit source provenance.

The canonical checkout is `/Volumes/PlanckSSD/KI/java/NeitzelFXDesigner`. Its Git remote is `ssh://git@gitea.neitzel.de:2222/konrad/NeitzelFXDesigner.git` and its default branch is `main`.

Validate the installed corrected development runtime separately with `python3 scripts/check-neitzellib-artifact.py`. This requires the recorded local artifacts; the full check also verifies these hashes.