mikebarkmin · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026
diff --git a/.github/actions/check-browser/action.yml b/.github/actions/check-browser/action.yml
@@ -0,0 +1,40 @@
+name: Check browser compatibility
+description: Require the browser checkout, current generated contract, parity fixture and reference compilation
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v7
+      with:
+        repository: openpatch/online-ide
+        path: .validation/online-ide
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: npm
+        cache-dependency-path: .validation/online-ide/package-lock.json
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Regenerate Javadoc metadata
+      shell: bash
+      run: mvn -q -DskipTests prepare-package
+    - name: Require current compatibility artifacts and parity fixture
+      shell: bash
+      run: |
+        python3 scripts/browser-compatibility.py --check --online-ide .validation/online-ide
+        python3 scripts/parity-fixture.py --check --strict --online-ide .validation/online-ide
+        python3 scripts/release-catalogs.py --check --online-ide .validation/online-ide
+    - name: Compile reference examples and check browser inventories
+      shell: bash
+      working-directory: .validation/online-ide
+      run: |
+        npm ci
+        npm run test:ci -- src/test/ScratchCompatibilityTest.test.ts
+        npm run browser:install -- --with-deps
+        npm run test:browser
+    - name: Match desktop lifecycle behavior
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y xvfb libgl1-mesa-dri
+        bash scripts/lifecycle-parity.sh
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -8,6 +8,7 @@ on:
 jobs:
   documentation:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
 
     permissions:
       pages: write      # needed to publish to GitHub Pages
@@ -21,12 +22,22 @@ jobs:
         uses: actions/setup-java@v5
         with:
           distribution: temurin
-          java-version: 17
+          java-version: 25
           cache: maven
 
       - name: Build Java Project
         run: mvn clean package
 
+      - name: Check browser compatibility before publishing
+        uses: ./.github/actions/check-browser
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install the released Hyperbook toolchain
+        run: npm install --global hyperbook@0.112.0
+
       - name: Build Docs
         run:  bash ./build.sh
 

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -7,7 +7,21 @@ on:
       - main
 
 jobs:
+  validate:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: 25
+          cache: maven
+      - run: mvn -B test
+      - uses: ./.github/actions/check-browser
+
   release:
+    needs: validate
     if: github.event.pull_request.merged == true  # only run if PR was merged
     runs-on: ubuntu-latest
 
@@ -60,6 +74,21 @@ jobs:
         # to avoid paying for the full suite twice in the same job.
         run: mvn -B clean package -Pall -DskipTests
 
+      - name: Require current catalogs and assemble offline examples
+        run: |
+          python3 scripts/browser-compatibility.py --check
+          python3 scripts/release-catalogs.py --check
+          python3 scripts/release-catalogs.py --archive dist/scratch-catalogs.zip
+
+      - name: Checkout curriculum for the release course pack
+        uses: actions/checkout@v7
+        with:
+          repository: openpatch/hyperbook-informatik
+          path: .validation/curriculum
+
+      - name: Assemble offline course pack
+        run: python3 scripts/build-course-pack.py --curriculum .validation/curriculum --output dist/scratch-to-java-course.zip
+
       - name: Get project version
         id: get-version
         run: |
@@ -91,9 +120,9 @@ jobs:
           files: |
             target/*.jar
             dist/*.jar
+            dist/*.zip
 
       - name: Delete changeset branch
         run: |
           echo "Deleting branch 'changeset'"
           git push origin --delete changeset || true
-
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -11,6 +11,7 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
 
     steps:
       - name: Checkout repository
@@ -29,3 +30,6 @@ jobs:
 
       - name: Run tests
         run: mvn -B test
+
+      - name: Check browser compatibility and generated references
+        uses: ./.github/actions/check-browser
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,19 @@
 ---
 name: Changelog
-index: 75
+index: 76
 lang: en
 ---
 
+## 5.8.0
+
+Add the Scratch for Java cat as built-in sprites. Its animations - idle, walk, crouch, jump, fall, land, punch, hurt, ko, cheer and climb - load by name, for example `addAnimation("walk", "cat_walk_%d", 6)`. Coffee beans, a bug, a goal mug and hearts for a platformer come with it. The new Cat Platformer example shows them all in a game.
+
+Distribute versioned API, asset and example catalogs, with stable documentation
+identifiers, translation overrides and offline example artifacts.
+
+Treat non-finite game speeds as zero and ignore negative elapsed frame time, keeping timers usable after invalid speed input.
+
+
 ## 5.7.1
 
 

diff --git a/README.md b/README.md
@@ -22,6 +22,10 @@ npx hyperbook dev
 
 ## Library
 
+Browser versions, API availability and synchronization commands are documented in
+[compatibility/README.md](compatibility/README.md). The generated contract is
+[compatibility/contract.json](compatibility/contract.json).
+
 If you want to work on the library. You need a Java environment and Maven. Then you can use the following command to build
 the library.
 
@@ -132,3 +136,23 @@ Scratch for Java is maintained by [OpenPatch](https://openpatch.org), an organiz
 The Scratch for Java library is profiled using [Java Profiler](https://www.ej-technologies.com/products/jprofiler/overview.html)
 
 [![Java Profiler](https://www.ej-technologies.com/images/product_banners/jprofiler_large.png)](https://www.ej-technologies.com/products/jprofiler/overview.html)
+
+
+## Shared release data and offline course
+
+Javadoc generates the API catalog; atlas and example sources generate the asset
+and project catalogs. Run `scripts/release-catalogs.py` after documentation
+metadata generation. `--check`, `--studio` and `--online-ide` verify consumer
+snapshots without requiring a particular checkout layout. `--archive` creates
+an offline artifact used by Studio's template synchronizer.
+
+Build the tutorial/Spielwerkstatt pack with:
+
+```sh
+python3 scripts/build-course-pack.py --curriculum /path/to/hyperbook-informatik \
+  --output target/scratch-to-java-course.zip
+```
+
+See `compatibility/portable-project.md`, `compatibility/behavioral-checks.md`
+and `course/` for transfer/test formats, teacher notes and the pending pilot form.
+The canonical behavioral check runs unchanged in desktop JUnit and Chromium.
diff --git a/build.sh b/build.sh
@@ -36,6 +36,9 @@ done
 # pages as they were after the last `mvn package`, which is how pages for
 # deleted methods used to survive.
 mvn -q -DskipTests prepare-package
+python3 scripts/browser-compatibility.py
+python3 scripts/release-catalogs.py
+python3 scripts/build-course-pack.py --output docs/public/scratch-to-java-course.zip
 
 # Any jar linked in for local testing by scripts/link-jar.sh is taken out again
 # here. Zipping one in would put a 19 MB library inside every project download.

diff --git a/catalogs/README.md b/catalogs/README.md
@@ -0,0 +1,31 @@
+# Release catalogs
+
+The doclet supplies public overloads, parameter names and documentation.
+Availability comes from the reviewed compatibility contract. Translation
+overrides use stable identifiers: documentation group plus erased parameters.
+Do not overwrite translated descriptions when regenerating English Javadoc.
+
+Generate after the doclet and compatibility artifacts. Pass explicit consumer
+paths to synchronize their committed snapshots:
+
+    mvn -q -DskipTests prepare-package
+    python3 scripts/browser-compatibility.py --online-ide /path/to/online-ide
+    python3 scripts/release-catalogs.py --online-ide /path/to/online-ide --studio /path/to/studio
+    python3 scripts/release-catalogs.py --check --online-ide /path/to/online-ide --studio /path/to/studio
+
+The same JSON is distributed in the library JAR, documentation, Studio and
+browser assets. Example entries include checksums for source and asset files.
+The --archive option packages those ordinary files:
+
+    python3 scripts/release-catalogs.py --archive target/scratch-catalogs.zip
+
+Studio can update templates from the release artifact without a sibling checkout:
+
+    python3 scripts/sync-templates.py --artifact /path/to/scratch-catalogs.zip --check
+
+Older libraries can use local source JARs. Without source metadata, Studio filters
+the current descriptions against the project's actual public binary signatures.
+No network request or class initialization is needed to select help.
+
+CI checks consumer snapshots against the library's default branch. Coordinated
+changes must merge their generated snapshots together before these gates pass.