Run the CAYW JavaFX picker in the native jabsrv image

[wanling0000]

Summary

The native jabsrv image builds, but the CAYW endpoint failed at runtime because the image lacked the reachability metadata JavaFX needs.

This PR adds:

• macOS accessibility JNI metadata (com.sun.glass.ui.mac.MacAccessible + its enums, java.lang.Enum.toString, MacVariant) so the Glass accessibility bridge initializes;
• CAYW GUI resources (cayw.css, JabRef-icon-64.png) ;
• drops -Djava.awt.headless=true from the native build args so the JavaFX GUI isn't forced headless.
• added -march=compatibility to prevent CPU-ISA error on older machines (document)

Status:
Verified on macOS.
Linux is pending a GPU. The test VM has no GPU, so JavaFX's es2 pipeline rejects the software (llvmpipe) renderer (System GPU doesn't meet the es2 pipe requirement). It can be forced with -Dprism.forceGPU=true and does render (confirmed via screenshot under xvfb), but there's no proper visual/interactive verification without a real display+GPU. I've requested an AWS G-instance vCPU quota increase (awaiting approval) to bring up a GPU desktop for manual verification

Steps to test

# Build (Liberica NIK Full 25)
JAVA_HOME=<liberica-nik-full-25> ./gradlew :jabsrv-cli:nativeCompile -PuseLibericaJdkFull \
  -Dorg.gradle.java.installations.paths="$JAVA_HOME"

# Terminal A — run the native server
./jabsrv-cli/build/native/nativeCompile/jabsrv

# Terminal B — trigger CAYW
curl "http://localhost:23119/better-bibtex/cayw?librarypath=demo&format=biblatex"

Related issues and pull requests

Closes NA

This PR is part of the JabRef components as native images project.

Follow-up to #16565

AI usage

claude-opus-4-8

---

AI CHECKLIST.md walkthrough

Checklist

• I own the copyright of the code submitted and I license it under the MIT license
• If AI tools were used, I disclosed them in the "AI usage" section and reviewed, understood, and take full ownership of all AI-generated code
• I manually tested my changes in running JabRef (always required)
• [/] I added JUnit tests for changes (if applicable)
• [/] I added screenshots in the PR description (if change is visible to the user)
• [/] I added one sentence (max 20 words) to CHANGELOG.md describing the change from the user's point of view (if the change is visible to the user)
• [/] I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Enable the JavaFX CAYW picker in native jabsrv

🐞 Bug fix ⚙️ Configuration changes 🧪 Tests 🕐 10-20 Minutes

AI Description

• Enable JavaFX CAYW picker startup in native jabsrv images.
• Register accessibility, software rendering, styling, and icon reachability metadata.
• Align invalid-library tests with interactive CAYW request behavior.

Diagram

graph TD
  Client["CAYW Client"] --> Endpoint["CAYW Endpoint"] --> Picker["JavaFX Picker"]
  Build["Native Build"] --> Image["jabsrv Image"] --> Endpoint
  Metadata["Reachability Metadata"] --> Image
  Resources["GUI Resources"] --> Image

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Generate metadata with the tracing agent

• ➕ Captures runtime JNI and reflection usage from representative picker sessions
• ➕ Reduces the chance of omitting indirectly accessed JavaFX members
• ➖ Produces broader, noisier metadata that still requires manual review
• ➖ Requires representative runs on every relevant platform and rendering path

2. Register JavaFX through a native-image Feature

• ➕ Can centralize conditional platform registration in executable code
• ➕ Supports version-aware or platform-aware metadata decisions
• ➖ Adds custom build-time code and maintenance complexity
• ➖ Is excessive for a targeted set of known classes and resources

Recommendation: Keep the explicit reachability metadata and resource registration because it is transparent, narrowly scoped, and appropriate for the known JavaFX failures. Use tracing-agent output as a validation aid—especially on Linux and future JavaFX upgrades—rather than replacing the curated metadata.

Files changed (3) +280 / -3

Bug fix (2) +280 / -1

build.gradle.ktsAllow GUI initialization in native jabsrv builds +0/-1

Allow GUI initialization in native jabsrv builds

• Removes the native-image build argument that forced AWT headless mode. This allows the CAYW endpoint to initialize and display its JavaFX picker.

jabsrv-cli/build.gradle.kts

reachability-metadata.jsonRegister JavaFX picker native-image metadata and assets +280/-0

Register JavaFX picker native-image metadata and assets

• Adds JNI reachability for the macOS Glass accessibility bridge, its enums, 'MacVariant', and 'Enum.toString'. It also retains the JavaFX software pipeline and packages the CAYW stylesheet and JabRef icon.

jabsrv/src/main/resources/META-INF/native-image/org.jabref/jabsrv/reachability-metadata.json

Tests (1) +0 / -2

CAYWResourceTest.javaTest invalid libraries without selected-entry mode +0/-2

Test invalid libraries without selected-entry mode

• Removes the 'selected' query parameter from unknown-library and empty-database requests. The tests now represent the normal interactive CAYW request path while continuing to assert bad-request handling.

jabsrv/src/test/java/org/jabref/http/server/cayw/CAYWResourceTest.java

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (3) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Native CAYW fix lacks tests 📘 Rule violation ☼ Reliability

Description

The PR makes the JavaFX CAYW picker runnable in the native image by adding runtime metadata, but
adds no native-image regression or smoke test that exercises this path. Existing JVM endpoint tests
cannot detect missing GraalVM JNI/resource metadata, so the original runtime failure can recur
unnoticed.

Code

jabsrv/src/main/resources/META-INF/native-image/org.jabref/jabsrv/reachability-metadata.json[R1299-1300]

+      "type": "com.sun.glass.ui.mac.MacAccessible",
+      "jniAccessible": true,

Evidence

PR Compliance ID 18 requires regression coverage for behavior changes. The cited metadata enables
the previously failing native JavaFX path, while the repository has no jabsrv native-image test
files and the only changed endpoint tests merely remove query parameters from existing bad-request
cases.

AGENTS.md: Update Tests for Behavioral and Core Logic Changes: AGENTS.md: Update Tests for Behavioral and Core Logic Changes: AGENTS.md: Update Tests for Behavioral and Core Logic Changes: AGENTS.md: Update Tests for Behavioral and Core Logic Changes
jabsrv/src/main/resources/META-INF/native-image/org.jabref/jabsrv/reachability-metadata.json[1299-1300]
jabsrv/src/test/java/org/jabref/http/server/cayw/CAYWResourceTest.java[103-121]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The native-image metadata fix is not protected by a test that runs the CAYW JavaFX path in the native `jabsrv` executable.
## Issue Context
The existing `CAYWResourceTest` runs on the JVM and cannot detect omitted GraalVM JNI or resource metadata. Add an appropriate native-image smoke or integration test that fails when the picker cannot initialize; isolate platform/display requirements where necessary.
## Fix Focus Areas
- jabsrv/src/main/resources/META-INF/native-image/org.jabref/jabsrv/reachability-metadata.json[1287-1560]
- jabsrv/src/test/java/org/jabref/http/server/cayw/CAYWResourceTest.java[103-121]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. CAYW requirement is missing 📘 Rule violation ⚙ Maintainability

Description

Restoring an endpoint that previously failed at runtime in the native server is a significant bug
fix, but no OpenFastTrace requirement was added for native CAYW availability. This leaves the
behavior without the required product-to-implementation traceability.

Code

jabsrv/src/main/resources/META-INF/native-image/org.jabref/jabsrv/reachability-metadata.json[R1299-1300]

+      "type": "com.sun.glass.ui.mac.MacAccessible",
+      "jniAccessible": true,

Evidence

PR Compliance ID 25 requires a requirement for significant fixes. The new MacAccessible native
metadata is the implementation of the runtime fix, but docs/requirements/http-server.md contains
requirements only for search, groups, and import and has no CAYW requirement.

AGENTS.md: Add Properly Formatted Requirements for Features and Significant Fixes: AGENTS.md: Add Properly Formatted Requirements for Features and Significant Fixes: AGENTS.md: Add Properly Formatted Requirements for Features and Significant Fixes: AGENTS.md: Add Properly Formatted Requirements for Features and Significant Fixes
jabsrv/src/main/resources/META-INF/native-image/org.jabref/jabsrv/reachability-metadata.json[1299-1300]
docs/requirements/http-server.md[4-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The significant native CAYW runtime fix has no corresponding OpenFastTrace requirement.
## Issue Context
Add a requirement under the HTTP server requirements describing that the native `jabsrv` image supports the CAYW picker, place its `req~...~1` identifier immediately after the heading, and add matching implementation/test links. Preserve the required file-level markdownlint directive.
## Fix Focus Areas
- docs/requirements/http-server.md[4-41]
- jabsrv/src/main/resources/META-INF/native-image/org.jabref/jabsrv/reachability-metadata.json[1287-1560]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. CAYW fix lacks changelog 📘 Rule violation ⚙ Maintainability

Description

The native jabsrv CAYW endpoint changes from a runtime failure to displaying its picker, which is
observable to endpoint users, but the PR adds no CHANGELOG.md entry. Users therefore receive no
release note for the restored functionality.

Code

jabsrv-cli/build.gradle.kts[73]

-            buildArgs.add("-Djava.awt.headless=true")

Evidence

PR Compliance ID 27 requires release notes for observable changes. Removing the forced AWT headless
property is a changed build line that enables the native GUI, while the current Unreleased
changelog has no entry for jabsrv or the native CAYW picker.

AGENTS.md: Maintain Accurate User-Facing CHANGELOG Entries: AGENTS.md: Maintain Accurate User-Facing CHANGELOG Entries: AGENTS.md: Maintain Accurate User-Facing CHANGELOG Entries: AGENTS.md: Maintain Accurate User-Facing CHANGELOG Entries
jabsrv-cli/build.gradle.kts[70-75]
CHANGELOG.md[10-80]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The user-visible native CAYW runtime fix is missing from the changelog.
## Issue Context
Add a concise end-user-oriented item under the appropriate `Unreleased` section explaining that the CAYW picker now works in the native `jabsrv` executable. Since the PR description identifies no issue, use the PR link or a TODO placeholder until its number is available.
## Fix Focus Areas
- CHANGELOG.md[10-80]
- jabsrv-cli/build.gradle.kts[70-75]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can ask Qodo to dismiss a finding you disagree with, with your reason on record

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗