Add a browser-native LiquidJava playground (#3)

Author: rcosta358

.github/workflows/pages.yml

@@ -28,6 +28,24 @@ jobs:
           ruby-version: "2.6"
           bundler-cache: true
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Build playground
+        run: |
+          npm ci --ignore-scripts --no-audit --no-fund
+          npm run build:playground
+          npm run test:playground
+
       - name: Setup Pages
         uses: actions/configure-pages@v5
 

.gitignore

@@ -5,3 +5,6 @@ _site/
 .bundle/
 vendor/
 Gemfile.lock
+node_modules/
+.playground-build/
+playground/runtime/

README.md

@@ -32,3 +32,32 @@ bundle exec jekyll build
 ## Publishing
 
 The site is configured as a GitHub Pages project site at [https://liquid-java.github.io/liquidjava-docs/](https://liquid-java.github.io/liquidjava-docs/).
+
+## Browser playground
+
+The `/playground/` page runs LiquidJava in a browser worker with CheerpJ 4.3 and the official Z3 WebAssembly package. Code is checked locally. Stop terminates the worker, including a running solver, and the next check creates a fresh runtime.
+
+Build the runtime before building Jekyll:
+
+```bash
+npm ci --ignore-scripts --no-audit --no-fund
+npm run build:playground
+npm run test:playground
+bundle exec jekyll build
+```
+
+The build requires JDK 17, Python 3, Node.js, and access to Maven Central. It recompiles the published verifier 0.0.35 and annotation API 0.0.7 sources for Java 17 without changing them, packages their dependencies, and adds the docs-owned runner and Z3 loader. The standard-library classpath comes from the build JDK's `java.base.jmod`. Generated runtime files are ignored by Git and included in the Pages artifact. The normal Pages workflow builds everything automatically.
+
+The browser package also adapts Spoon 10.4.2's query initialization: when CheerpJ supplies an empty cast-exception stack trace, it selects Spoon's existing exotic-JVM query mode. The pinned source is downloaded and the adaptation checked during the build. This change is limited to the docs' generated dependency; the verifier repository and published sources remain unchanged.
+
+For local testing, after building the runtime:
+
+```bash
+npm run serve:playground
+```
+
+Open `http://127.0.0.1:8770/playground/`. This uses a static server with HTTP range support, which CheerpJ needs when loading JARs. Ordinary `jekyll serve` does not supply the required range responses.
+
+`playground/isolation.js` is a service worker scoped to `/playground/`. It adds the cross-origin isolation response headers Z3 requires on static hosting, including GitHub Pages. The first visit registers it and reloads once. Other docs pages are outside its scope. CheerpJ loads from its official CDN inside the verification worker; its runtime is not copied into this repository.
+
+The playground checks a single Java file using Java 8 source syntax, bundled annotations and core standard-library types from `java.base`. External dependencies and other Java modules are not available. Z3 4.16 runs behind the verifier's 4.8.17 Java API; browser integration tests must be repeated when updating either version. Unsupported native operations and unknown solver results fail explicitly instead of reporting success. This integration is kept entirely in `liquidjava-docs`.

_config.yml

@@ -46,6 +46,11 @@ defaults:
       image: /assets/images/Liquid2.png
 
 exclude:
+  - node_modules
+  - scripts
+  - package.json
+  - package-lock.json
+  - .playground-build
   - .DS_Store
   - vendor
   - Gemfile

_includes/nav_footer_custom.html

@@ -1,4 +1,4 @@
-<p>
-  Help improve this documentation by contributing on 
+<footer class="site-footer">
+  Help improve this documentation by contributing on
   <a href="https://github.com/liquid-java/liquidjava-docs">GitHub</a>
-</p>
+</footer>

_sass/custom/custom.scss

@@ -28,6 +28,10 @@
     $sidebar-color;
 }
 
+.site-footer {
+  color: $body-text-color;
+}
+
 .main-content a {
   color: #41586f;
   text-decoration-thickness: 0.08em;
@@ -43,7 +47,9 @@
 }
 
 .main-content pre.highlight,
-.main-content div.highlighter-rouge {
+.main-content div.highlighter-rouge,
+.main-content #lj-editor,
+.main-content .lj-output {
   overflow-x: auto;
   overflow-y: hidden;
   scrollbar-width: thin;
@@ -259,40 +265,30 @@
   margin: 1.5rem 0 0;
 }
 
-.home-button {
+.main-content .home-button {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  min-height: 2.9rem;
-  padding: 0.8rem 1.1rem;
-  border-radius: 999px;
-  border: 1px solid transparent;
-  font-weight: 700;
-  line-height: 1.1;
-  text-decoration: none !important;
-  transition: transform 120ms ease, box-shadow 120ms ease, background-color 120ms ease, border-color 120ms ease;
-  box-shadow: 0 14px 26px rgba(51, 80, 106, 0.22);
-}
-
-.home-button:hover,
-.home-button:focus {
-  transform: translateY(-1px);
-}
-
-.home-button:focus {
-  outline: none;
-  box-shadow: 0 0 0 3px rgba(65, 88, 111, 0.16);
+  gap: 0.65rem;
+  padding: 0.7rem 1.1rem;
+  border-radius: 0.5rem;
+  color: #fff;
+  background: #334e68;
+  font-weight: 400;
+  line-height: 1.5;
+  text-decoration: none;
+  box-shadow: 0 2px 4px rgba(23, 26, 31, 0.12);
 }
 
-.home-button.primary {
+.main-content .home-button:hover {
   color: #fff;
-  background: linear-gradient(135deg, #63c093 0%, #4e98a8 50%, #4a80b0 100%);
-  box-shadow: 0 18px 10px rgba(51, 80, 106, 0.22);
+  background: #253b50;
+  text-decoration: none;
 }
 
-.home-button.secondary {
-  color: #2a3642;
-  border-color: rgba(42, 54, 66, 0.15);
+.main-content .home-button:focus-visible {
+  outline: 3px solid #5f7ea1;
+  outline-offset: 3px;
 }
 
 .card-panel {