Issue 106

.github/workflows/api-reference.yml

@@ -0,0 +1,83 @@
+name: API Reference
+
+# Keeps skills/vaadin-playwright-test/api-reference.md in lock-step with the code.
+#
+# - On push (master / issue branches): regenerate and commit the result back to
+#   the branch, so the reference updates itself with no manual step.
+# - On pull_request: regenerate and FAIL if the committed file is stale. Push
+#   events from a fork have a read-only token and cannot auto-commit, so this
+#   verify-only job is what catches an out-of-date reference in a fork PR.
+#
+# The push path filter excludes api-reference.md itself, so the bot's own commit
+# does not re-trigger the workflow (no loop).
+
+on:
+  push:
+    branches:
+      - master
+      - 'issue-**'
+    paths:
+      - 'src/main/java/org/vaadin/addons/dramafinder/element/**'
+      - 'tools/generate-api-reference.java'
+      - '.github/workflows/api-reference.yml'
+  pull_request:
+    branches: [ master ]
+    paths:
+      - 'src/main/java/org/vaadin/addons/dramafinder/element/**'
+      - 'tools/generate-api-reference.java'
+      - '.github/workflows/api-reference.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  update-api-reference:
+    # Auto-commit path — only on push (needs write access to the branch).
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+      - name: Set up JBang
+        uses: jbangdev/setup-jbang@main
+      - name: Regenerate API reference
+        run: jbang tools/generate-api-reference.java
+      - name: Commit the regenerated reference if it changed
+        run: |
+          if git diff --quiet skills/vaadin-playwright-test/api-reference.md; then
+            echo "api-reference.md is already up to date."
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add skills/vaadin-playwright-test/api-reference.md
+            git commit -m "Regenerate api-reference.md [skip ci]"
+            git push origin HEAD:${{ github.ref_name }}
+          fi
+
+  verify-api-reference:
+    # Verify-only path — for pull requests (incl. forks, whose token is read-only).
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+      - name: Set up JBang
+        uses: jbangdev/setup-jbang@main
+      - name: Regenerate API reference
+        run: jbang tools/generate-api-reference.java
+      - name: Fail if the committed reference is out of date
+        run: |
+          if ! git diff --exit-code skills/vaadin-playwright-test/api-reference.md; then
+            echo "::error::api-reference.md is stale. Run 'jbang tools/generate-api-reference.java' and commit the result."
+            exit 1
+          fi

AGENTS.md

@@ -245,4 +245,16 @@ public static ButtonElement getByText(Locator locator, String text) { ... }
 - Follow this file's conventions for any edits. Keep patches minimal and
   focused.
 - Use `*IT.java` only for end-to-end tests executed by Failsafe.
-- Refer to `docs/specifications/` for detailed element API documentation.
+- **Never download or unzip the DramaFinder jar/sources to discover its API.**
+  The complete public API (every element, signatures, one-line descriptions) is
+  in `skills/vaadin-playwright-test/api-reference.md`, auto-generated from source
+  by `tools/generate-api-reference.java`. To look something up, **grep that file
+  for the element name and read only its `### <Name>Element` section** — don't
+  read the whole file. In a consumer project where it isn't checked out, fetch
+  it (one request) from
+  `https://raw.githubusercontent.com/parttio/dramafinder/master/skills/vaadin-playwright-test/api-reference.md`.
+- `api-reference.md` is generated — never edit it by hand. After changing any
+  element's public API, regenerate it (`jbang tools/generate-api-reference.java`)
+  and commit the result; CI fails if it is stale.
+- Refer to `docs/specifications/` for the prose docs on components with
+  non-obvious behaviour (Grid, TreeGrid, VirtualList, and extension guidance).

GEMINI.md

@@ -49,6 +49,14 @@ mvn -Pit verify
 
 ## Available Element Classes
 
+> **Never download or unzip the DramaFinder jar/sources to discover its API.**
+> The complete, always-current public API (every element, its methods,
+> signatures and one-line descriptions) is in
+> `skills/vaadin-playwright-test/api-reference.md`, auto-generated from source.
+> Read that file — in a consumer project, fetch it from
+> `https://raw.githubusercontent.com/parttio/dramafinder/master/skills/vaadin-playwright-test/api-reference.md`.
+> The table below is a component→class overview only.
+
 Each element class wraps a Playwright `Locator` and provides typed helpers (getters, actions, assertions) for a specific Vaadin component. They all extend `VaadinElement` and are annotated with `@PlaywrightElement`.
 
 | Element | Vaadin Component | Tag |