feat:Add playground (#600)

Motivation:
Add a sjsonnet playground, it's single-paged.
The html is written by AI, but I attached a spec.md for later
improvement.

refs: #353

<img width="1916" height="970" alt="image"
src="https://github.com/user-attachments/assets/b2f471a9-f012-493d-a1ee-5f23abfbbd1f"
/>

Author: He-Pin

.github/workflows/playground-deploy.yaml

@@ -0,0 +1,55 @@
+name: Deploy Playground to GitHub Pages
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'playground/**'
+      - 'sjsonnet/src/**'       # shared core (parser, evaluator, stdlib) — used by JS build
+      - 'sjsonnet/src-js/**'    # JS-specific code (SjsonnetMain, JsVirtualPath)
+      - 'build.mill'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-java@v5
+        with:
+          java-version: 17
+          distribution: 'zulu'
+
+      - name: Build Playground Bundle
+        run: ./mill playground.bundle
+
+      - name: Prepare Pages artifact
+        run: |
+          mkdir -p _site
+          cp out/playground/bundle.dest/index.html _site/
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-22.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release-build.yaml

@@ -26,6 +26,8 @@ jobs:
         run: ./mill "sjsonnet.jvm[$SCALA_VERSION].__.assembly"
       - name: JS Build
         run: ./mill "sjsonnet.js[$SCALA_VERSION].fullLinkJS"
+      - name: Playground Build
+        run: ./mill playground.bundle
       - name: Rename Artifacts
         run: |
           mkdir release
@@ -34,6 +36,7 @@ jobs:
           cp ./out/sjsonnet/jvm/$SCALA_VERSION/assembly.dest/out.jar ./release/sjsonnet-$VERSION.jar
           cp ./out/sjsonnet/jvm/$SCALA_VERSION/client/assembly.dest/out.jar ./release/sjsonnet-client-$VERSION.jar
           cp ./out/sjsonnet/jvm/$SCALA_VERSION/server/assembly.dest/out.jar ./release/sjsonnet-server-$VERSION.jar
+          cp ./out/playground/bundle.dest/index.html ./release/sjsonnet-playground-$VERSION.html
       - uses: actions/upload-artifact@v6
         name: Upload Artifacts
         with:

build.mill

@@ -375,3 +375,70 @@ object sjsonnet extends VersionFileModule {
     )
   }
 }
+
+object playground extends Module {
+
+  def playgroundHtml = Task.Source(BuildCtx.workspaceRoot / "playground" / "index.html")
+
+  /**
+   * Compile ScalaJS and inline the resulting JS bundle into a single HTML file. Note: the HTML
+   * template (playground/index.html) may still reference external assets (e.g. CSS/JS from CDNs),
+   * so the output is not guaranteed to be fully self-contained or offline-capable.
+   */
+  def bundle = Task {
+    val jsOutput = sjsonnet.js(scalaVersions.head).fullLinkJS()
+    val mainJs = jsOutput.dest.path / "main.js"
+    val dest = Task.ctx().dest
+
+    // Wrap CommonJS module for browser usage
+    val source = os.read(mainJs)
+    val wrappedJs =
+      s"""// sjsonnet browser bundle - auto-generated
+         |(function(global) {
+         |  var exports = {};
+         |  var module = { exports: exports };
+         |
+         |  $source
+         |
+         |  global.SjsonnetMain = exports.SjsonnetMain || module.exports.SjsonnetMain;
+         |})(typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : Function('return this')());""".stripMargin
+
+    // Read HTML template and inline the JS bundle
+    val htmlTemplate = os.read(playgroundHtml().path)
+    val placeholder = "/* SJSONNET_BUNDLE_PLACEHOLDER */"
+    val occurrences =
+      java.util.regex.Pattern.quote(placeholder).r.findAllMatchIn(htmlTemplate).length
+    require(
+      occurrences == 1,
+      s"Expected exactly 1 occurrence of '$placeholder' in playground/index.html, found $occurrences"
+    )
+    val inlinedHtml = htmlTemplate.replace(placeholder, wrappedJs)
+    os.write(dest / "index.html", inlinedHtml)
+
+    PathRef(dest)
+  }
+
+  /**
+   * Build and open the playground in the default browser.
+   *
+   * Since the HTML is self-contained (JS inlined), no HTTP server is needed. The file is opened
+   * directly in the default browser.
+   */
+  def start() = Task.Command {
+    val htmlFile = bundle().path / "index.html"
+    val fileUri = htmlFile.toNIO.toUri.toString
+    println(s"Opening Sjsonnet Playground: $fileUri")
+
+    val osName = System.getProperty("os.name", "").toLowerCase
+    val openCmd =
+      if (osName.contains("mac") || osName.contains("darwin")) Seq("open", fileUri)
+      else if (osName.contains("win")) Seq("cmd", "/c", "start", "", fileUri)
+      else Seq("xdg-open", fileUri) // Linux / BSD
+
+    val opened = scala.util.Try(os.proc(openCmd).call(stdout = os.Inherit, stderr = os.Inherit))
+    if (opened.isFailure) {
+      println(s"Could not open browser automatically. Please open this file manually:")
+      println(s"  $htmlFile")
+    }
+  }
+}