fixes for a Git HEAD corruption

Author: mrhunsaker

.gitignore

@@ -9,6 +9,7 @@ pom.xml.versionsBackup
 pom.xml.next
 release.properties
 dependency-reduced-pom.xml
+GraphDigitizer/
 
 # IDE
 .idea/
@@ -50,3 +51,8 @@ bin/
 *.zip
 *.tar.gz
 *.rar
+*.exe
+*.msi
+*.dmp
+*.bak
+core.20251202.120453.9872.0001.dmp

.scripts/find_missing_javadoc.py

@@ -0,0 +1,24 @@
+import pathlib,re
+root=pathlib.Path('src/main/java')
+missing=[]
+for p in sorted(root.rglob('*.java')):
+    s=p.read_text(encoding='utf-8')
+    m=re.search(r'^(?:\s*)public\s+(class|record|enum|interface)\s+\w+', s, flags=re.M)
+    if m:
+        start=m.start()
+        before=s[:start]
+        # look for a /** that starts a javadoc block in the last 10 lines before
+        prev_lines=before.rstrip('\n').split('\n')[-10:]
+        has_javadoc=False
+        for line in reversed(prev_lines):
+            if '/**' in line:
+                has_javadoc=True
+                break
+            if line.strip()=='' or line.strip().startswith('*') or line.strip().startswith('/*'):
+                continue
+            if not line.strip().startswith('//'):
+                break
+        if not has_javadoc:
+            missing.append(str(p))
+print('\n'.join(missing))
+print('MISSING_COUNT:', len(missing))

META-INF/MANIFEST.MF

@@ -0,0 +1,5 @@
+Manifest-Version: 1.0
+Created-By: Maven JAR Plugin 3.3.0
+Build-Jdk-Spec: 24
+Main-Class: com.digitizer.ui.GraphDigitizerApp
+

README.md

@@ -47,6 +47,41 @@ A modern Java 21 / JavaFX implementation of the Graph Digitizer tool for extract
 
 - **[jlink / jpackage Guide](docs/JPACKAGE.md)** - How to create runtime images, cross-arch examples (Docker), and use `jpackage` for native installers.
 
+### **Native Packaging (Windows)**
+
+- **Symptom:** Packaged launcher could exit early during GUI startup due to the runtime attempting to load a missing assistive-technology provider (AccessBridge). This manifests as an AWTError about "Assistive Technology not found: com.sun.java.accessibility.AccessBridge" during toolkit initialization.
+
+- **Fix applied:** The Windows `jpackage` launcher is now created with an explicit JVM option that disables assistive-technology lookups on startup:
+
+```
+--java-options -Djavax.accessibility.assistive_technologies=
+```
+
+- **Where it's configured:** In the project `pom.xml` under the `native` profile's `jpackage-app-image` execution. The produced launcher (`target/jpackage/GraphDigitizer/app/GraphDigitizer.cfg`) will include the `java-options=-Djavax.accessibility.assistive_technologies=` entry so the packaged app does not attempt to load `com.sun.java.accessibility.AccessBridge` at runtime.
+
+- **How to build (PowerShell):** quote properties in PowerShell so Maven parses them correctly, and use the `preserve.appimage` property to keep the `app-image` folder for inspection:
+
+```powershell
+mvn -DskipTests verify -Pnative "-Dpreserve.appimage=true"
+```
+
+- **How to test quickly (PowerShell):** run the bundled runtime to see verbose JavaFX output (example):
+
+```powershell
+# Run the bundled java with the packaged classpath
+& .\target\jpackage\GraphDigitizer\runtime\bin\java.exe \
+  -Djavax.accessibility.assistive_technologies= \
+  -Dprism.verbose=true -Dprism.order=d3d \
+  -cp ".\target\jpackage\GraphDigitizer\app\graph-digitizer.jar; .\target\jpackage\GraphDigitizer\app\lib\*" \
+  com.digitizer.ui.GraphDigitizerApp
+```
+
+- **Alternative:** If full assistive-technology support is required, bundle the appropriate Access Bridge classes in the runtime and enable them explicitly. For most users, disabling the lookup is lighter and avoids the ClassNotFoundException.
+
+- **Notes:**
+  - The `preserve.appimage` Maven property is used during the build to avoid an automated cleanup of `target/jpackage/GraphDigitizer` so you can inspect the `app` and `runtime` folders. In PowerShell, quote the `-Dpreserve.appimage=true` argument as shown above.
+  - The change is safe for end users — it prevents an unnecessary classloading attempt when the AccessBridge is not present and does not affect normal GUI behavior.
+  
 ### Packaging Scripts
 
 
@@ -59,35 +94,53 @@ A modern Java 21 / JavaFX implementation of the Graph Digitizer tool for extract
 
 - **[Latest API (Javadoc)](https://mrhunsaker.github.io/Graph_Digitizer_Java_Implementation/)** – Generated from the current main branch
 
+- **Local Javadoc:** To regenerate the API docs locally run:
+
+```powershell
+mvn javadoc:javadoc
+```
+
+The generated docs are written to `target/site/apidocs`.
+
 - **Versioned Archives:** Each release will publish Javadocs under a subdirectory (e.g. `/1.1/`, `/1.2/`). Navigate directly to a version path to view older APIs.
 
 ## Quick Start
 
-### Prerequisites
+### Java & JavaFX Requirements
 
+This project uses Java 21 and JavaFX 21 (see `<properties>` in `pom.xml`). Packaging and runtime behavior depend on two things matching correctly:
 
-- Java 21 or later
-jpackage --type dmg --name GraphDigitizer --main-jar graph_digitizer_1.0.jar \
+- Java runtime (JDK/JRE) that is compatible with JavaFX (HotSpot builds are recommended). We recommend using Eclipse Temurin (HotSpot) builds for packaging and runtime (`Java 21` LTS builds are tested). Avoid using OpenJ9 builds for the runtime image used by `jlink`/`jpackage` since some OpenJ9 builds have exhibited native compatibility issues with JavaFX in past tests.
+
+- Matching JavaFX platform artifacts (jmods or platform jars) for the same JavaFX release (example: `javafx-21.0.2`). When creating runtime images with `jlink` you should use JavaFX `jmods` that match your JavaFX dependency version; for `jpackage` windows app-images we copy the platform jars into the app `lib/` directory so the launcher can find native JavaFX libraries at runtime.
+
+Where to get them:
+
+- Java (Temurin): https://adoptium.net/ — download the matching Java 21 (x64/arm64) HotSpot builds. Use the `jmods` or full JDK for `jlink`.
+- JavaFX SDK / jmods: https://openjfx.io/ or Gluon (https://gluonhq.com/products/javafx/) — download the JavaFX SDK / jmods that match the JavaFX version in `pom.xml`.
+
+Packaging tips:
+
+- Use a Temurin HotSpot JDK when running `jlink` and `jpackage` to produce the runtime image; specify the `--runtime-image` jlink output when invoking `jpackage`.
+- Ensure the JavaFX classifier/platform (e.g., `win`, `linux`, `mac`) matches the target OS when copying platform jars into `target/jpackage-input/lib`.
+- If you run into native crashes or rendering issues, try rebuilding the runtime with another HotSpot build (Temurin) and ensure JavaFX versions match exactly.
 
+See the `docs/JPACKAGE.md` for detailed packaging examples and cross-arch instructions.
+
+### Prerequisites
+
+jpackage --type dmg --name GraphDigitizer --main-jar graph_digitizer_1.0.jar \
 Note: This project uses JavaFX 21 and therefore either the user's JDK should
-contain JavaFX modules (e.g., a Liberica Full JDK) or the build will need
 to download platform-specific JavaFX artifacts (handled by Maven profiles in
-the `pom.xml`).
-
-### Installation
 
 
 1. Clone or download the repository
-
 2. Navigate to the project directory
-
 3. Build the project:
 
 ````bash
 mvn clean package
-
 ```
-
 ### Running the Application
 
 Using Maven:

docs/JPACKAGE.md

@@ -55,6 +55,12 @@ Example for Windows MSI (run on Windows host):
 
 For ARM64 MSI you would pass `--runtime-image C:\path\to\runtime-arm64` (and run jpackage on a Windows host or produce a Windows-compatible runtime image accordingly).
 
+### Recommended JVM & JavaFX builds
+
+- Use a HotSpot JDK (we recommend Eclipse Temurin) for `jlink` and `jpackage` — HotSpot builds are the most commonly tested and are known to work well with JavaFX. Some OpenJ9 builds have shown native compatibility issues with JavaFX rendering or native libraries.
+- Download JavaFX SDK/jmods that exactly match the `javafx.version` in `pom.xml` (for example `21.0.2`). Use the platform-specific `jmods` or platform jars for the target OS/arch.
+- When creating runtime images, use the JDK that matches the target architecture (x64 vs arm64) and include `java.desktop` and `java.management` modules if your app uses AWT/Swing interop or management APIs.
+
 ## CI recommendations
 
 
@@ -69,6 +75,24 @@ For ARM64 MSI you would pass `--runtime-image C:\path\to\runtime-arm64` (and run
 
 - If an MSI fails to install on a target arch, verify the runtime image architecture matches the target and that the app's native libraries (JavaFX) were built for that arch.
 
+- **AWT / Accessibility startup error**: On some Windows systems the bundled launcher may attempt to load the Java Accessibility Access Bridge (`com.sun.java.accessibility.AccessBridge`) which is not always present in minimal runtime images. When the AWT Toolkit attempts to load configured assistive technologies and the AccessBridge class is missing, startup can fail with an `AWTError: Assistive Technology not found: com.sun.java.accessibility.AccessBridge`.
+
+  - Quick workaround (recommended for most builds): instruct the JVM to skip assistive-technology lookups by adding the JVM option:
+
+    ```text
+    -Djavax.accessibility.assistive_technologies=
+    ```
+
+    When using `jpackage` this should be included as a `--java-options` argument so generated launchers include the property. Example (snippet from this project's `pom.xml`):
+
+    ```text
+    --java-options -Djavax.accessibility.assistive_technologies=
+    ```
+
+  - Alternative: if you require full Access Bridge support, bundle the AccessBridge classes and native bits in the runtime image and enable them explicitly. This increases runtime size and complexity and is only needed for systems that rely on the Access Bridge.
+
+  - Note: This project's `README.md` and `pom.xml` are updated to include this `--java-options` by default for the Windows `jpackage` steps.
+
 ## References
 
 

docs/NATIVE_PACKAGING_VERIFICATION.md

@@ -0,0 +1,57 @@
+Packaging verification — latest run (2025-12-02)
+
+Summary
+
+- Installer MSI produced: `target/jpackage-msi/GraphDigitizer-1.1.msi` — present
+- App-image folder: `target/jpackage/GraphDigitizer` — not present in this run (the `jpackage` step removed the folder before MSI creation)
+- jlink runtime image used for packaging: `target/jlink-image` — present
+- Key diagnostic logs captured during the process:
+  - `target/jlink-driver/app-run3.log` (detailed JavaFX startup logs)
+  - `target/jlink-native-debug.log` (native debug flags output)
+  - `target/jlink-driver/run.log` (launcher driver run log)
+
+Where artifacts live
+
+- jlink runtime image: `target/jlink-image`
+- jpackage app-image (if preserved): `target/jpackage/GraphDigitizer`
+- installer MSI: `target/jpackage-msi/GraphDigitizer-1.1.msi`
+- staged jpackage input (app + libs): `target/jpackage-input/` (contains `graph-digitizer.jar` and `lib/*.jar`)
+
+Next steps you can request
+
+- "Re-run packaging and keep app-image" — re-run `mvn -DskipTests package -Pnative` but skip the cleanup step so the `app-image` folder remains under `target/jpackage/GraphDigitizer` (I can do this and then list its contents).
+- "Build and sign MSI" — run the packaging and then apply codesigning (requires access to a signing certificate).
+
+Commands used to reproduce the run
+
+1) Build + prepare jpackage input and run jpackage profile:
+
+```powershell
+mvn -DskipTests package -Pnative
+```
+
+2) Create the jlink runtime image (example used in this run):
+
+```powershell
+& 'C:\Program Files\Eclipse Adoptium\jdk-21.0.9.10-hotspot\bin\jlink.exe' \
+  --strip-debug --no-man-pages --no-header-files \
+  --add-modules java.desktop,java.management,java.logging,java.xml,javafx.base,javafx.graphics,javafx.controls,javafx.fxml,javafx.swing \
+  --module-path 'C:\Program Files\Eclipse Adoptium\jdk-21.0.9.10-hotspot\jmods;C:\javafx-jmods-21.0.9' \
+  --output target/jlink-image
+```
+
+3) Run the packaged app against the created runtime for verification (expanded classpath):
+
+```powershell
+$cp = (Get-ChildItem .\target\jpackage-input\lib -Filter *.jar | ForEach-Object { $_.FullName }) -join ';'
+& .\target\jlink-image\bin\java \
+  "-Djava.library.path=$PWD\target\jlink-image\bin;$PWD\target\jlink-image\bin\javafx" \
+  "-Dprism.verbose=true" "-Djavafx.verbose=true" \
+  -cp "$PWD\target\jlink-driver\bin;$PWD\target\jpackage-input\graph-digitizer.jar;$cp" \
+  com.digitizer.ui.GraphDigitizerApp 2>&1 | Tee-Object .\target\jlink-driver\app-run3.log
+```
+
+Notes
+
+- The `pom.xml` in the `native` profile was updated to copy runtime-scoped dependencies into `target/jpackage-input/lib` and to pass `--runtime-image ${project.build.directory}/jlink-image` to `jpackage`.
+- If you'd like, I can re-run packaging to preserve the `app-image` folder and then enumerate its contents and sizes.