feat: interactive Iceberg Mode Explorer with real C++→WASM engine

.github/workflows/build-iceberg-engine.yml

@@ -0,0 +1,133 @@
+name: Build Iceberg engine (WASM)
+
+# Builds the Iceberg Mode Explorer's engine — Redpanda's real C++ Avro->Iceberg
+# schema mapper compiled to WebAssembly — for a specific Redpanda release, so
+# each docs major.minor loads the engine built from that release's source.
+#
+# This is the analog of the Bloblang playground's update-go-modules workflow,
+# keyed on Redpanda release tags instead of Go module bumps. It produces
+# iceberg-engine-<major.minor>.js/.wasm as build artifacts; publish those to the
+# versioned docs content repo under
+# modules/<module>/assets/attachments/ so the tool loads the version-matched
+# engine at runtime (see src/js/27-iceberg-explorer.js loader).
+
+on:
+  workflow_dispatch:
+    inputs:
+      redpanda_ref:
+        description: 'Immutable Redpanda ref to build the engine from: a release tag (e.g. v26.2.1) or a 40-char commit SHA. Mutable branches such as dev are rejected.'
+        required: true
+  # Trigger from the redpanda repo on a new release via repository_dispatch:
+  #   curl -X POST .../dispatches -d '{"event_type":"redpanda-release","client_payload":{"ref":"v26.2.1"}}'
+  repository_dispatch:
+    types: [redpanda-release]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Resolve Redpanda ref and docs version
+        id: ver
+        # The ref comes from workflow_dispatch input or repository_dispatch
+        # payload, so it is event-controlled: pass it through env (never
+        # interpolate it into the script) and validate it before use.
+        env:
+          REF_INPUT: ${{ github.event.inputs.redpanda_ref || github.event.client_payload.ref }}
+        run: |
+          REF="$REF_INPUT"
+          if [[ ! "$REF" =~ ^[A-Za-z0-9][A-Za-z0-9._/-]*$ ]]; then
+            echo "Invalid Redpanda ref: $REF" >&2
+            exit 1
+          fi
+          echo "ref=$REF" >> "$GITHUB_OUTPUT"
+          # major.minor from a vX.Y.Z tag; 'dev' stays 'dev'.
+          if [[ "$REF" =~ ^v?([0-9]+)\.([0-9]+) ]]; then
+            echo "version=${BASH_REMATCH[1]}.${BASH_REMATCH[2]}" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=$REF" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Set up Emscripten
+        uses: mymindstorm/setup-emsdk@v14
+        with:
+          version: 6.0.3
+
+      - name: Fetch Redpanda source + third-party deps
+        working-directory: iceberg-editor/wasm-spike
+        env:
+          REDPANDA_REF: ${{ steps.ver.outputs.ref }}
+          # This workflow is the only path that publishes engines, so it always
+          # builds from an immutable ref: env.sh's require_pinned_ref() rejects a
+          # branch such as `dev` instead of producing an unattributable artifact.
+          REDPANDA_REQUIRE_PINNED: '1'
+        run: |
+          ./fetch-sources.sh
+          ./third_party/fetch-deps.sh
+
+      - name: Build engine (web target)
+        working-directory: iceberg-editor/wasm
+        run: ./build.sh web
+
+      - name: Stage versioned artifact
+        id: stage
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+          REF: ${{ steps.ver.outputs.ref }}
+        run: |
+          V="$VERSION"
+          # V lands in filenames and a sed replacement, so keep it to the
+          # characters a docs version / branch name may legitimately use.
+          if [[ ! "$V" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
+            echo "Invalid engine version: $V" >&2
+            exit 1
+          fi
+          mkdir -p dist
+          cp src/static/iceberg-engine.js  "dist/iceberg-engine-$V.js"
+          cp src/static/iceberg-engine.wasm "dist/iceberg-engine-$V.wasm"
+          # The emscripten glue references the .wasm by its build name; rewrite
+          # it to the versioned name so both files can coexist per version.
+          sed -i "s/iceberg-engine\.wasm/iceberg-engine-$V.wasm/g" "dist/iceberg-engine-$V.js"
+          # Attribute the artifact to the Redpanda revision it was built from.
+          # fetch-sources.sh records that commit in vendor/REDPANDA_COMMIT, which
+          # is git-ignored and outside dist/, so without this the published
+          # engine carries no provenance. $REF and $V are already validated
+          # above, so neither can break out of the JSON.
+          COMMIT="$(cat iceberg-editor/wasm-spike/vendor/REDPANDA_COMMIT)"
+          printf '{"engine_version":"%s","redpanda_ref":"%s","redpanda_commit":"%s"}\n' \
+            "$V" "$REF" "$COMMIT" >"dist/iceberg-engine-$V.provenance.json"
+          ls -la dist
+
+      - name: Smoke-test the built engine under Node
+        working-directory: iceberg-editor/wasm
+        run: |
+          ./build.sh node
+          node - <<'EOF'
+          const create = require('./build/iceberg-engine-node.js')
+          create().then(m => {
+            const out = m.avroToIcebergJson(JSON.stringify({
+              type:'record', name:'t', fields:[{name:'a',type:'string'}]
+            }))
+            const p = JSON.parse(out)
+            if (!p.fields || p.fields[0].type !== 'string') { console.error('FAIL', out); process.exit(1) }
+            console.log('engine smoke test OK:', out)
+          })
+          EOF
+
+      - name: Upload versioned engine artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: iceberg-engine-${{ steps.ver.outputs.version }}
+          path: dist/
+          if-no-files-found: error
+
+      # Publishing step (commented): open a PR to the versioned content repo
+      # placing dist/* under modules/<module>/assets/attachments/ for the
+      # matching docs version. Wire this to your content-repo bot token.
+      # - name: Publish to content repo
+      #   run: ./ci/publish-iceberg-engine.sh "${{ steps.ver.outputs.version }}" dist/

.github/workflows/iceberg-dsl-conformance.yml

@@ -0,0 +1,71 @@
+name: Iceberg DSL conformance
+
+# Verifies the Iceberg Mode Explorer's config-string builder (pure JS in
+# src/js/27-iceberg-explorer.js) still matches Redpanda's authoritative DSL
+# serialization, whose expectations live in
+# src/v/model/tests/iceberg_mode_test.cc in the redpanda repo.
+#
+# The unit test (tests/iceberg-dsl/conformance-test.js) always runs. On a
+# schedule / manual dispatch it also fetches the current C++ test file from a
+# chosen redpanda ref and greps for the expected format strings, so upstream
+# DSL changes surface as a failing check even before anyone updates the JS.
+
+on:
+  pull_request:
+    paths:
+      - 'src/js/27-iceberg-explorer.js'
+      - 'tests/iceberg-dsl/**'
+  workflow_dispatch:
+    inputs:
+      redpanda_ref:
+        description: 'redpanda ref to diff the DSL vectors against'
+        required: false
+        default: 'dev'
+  schedule:
+    - cron: '0 6 * * 1' # weekly: catch upstream DSL drift
+
+jobs:
+  conformance:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      # This job only reads the checkout, so don't leave GITHUB_TOKEN in the
+      # runner's git config for the rest of the job.
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run DSL conformance vectors
+        run: npm run test:iceberg-dsl
+
+      - name: Cross-check vectors against upstream iceberg_mode_test.cc
+        if: github.event_name != 'pull_request'
+        env:
+          REF: ${{ github.event.inputs.redpanda_ref || 'dev' }}
+        run: |
+          set -euo pipefail
+          url="https://raw.githubusercontent.com/redpanda-data/redpanda/$REF/src/v/model/tests/iceberg_mode_test.cc"
+          curl -fsSL "$url" -o upstream_iceberg_mode_test.cc
+          # Merge C++ adjacent string-literal concatenation ("a" "b" -> "ab"),
+          # including across line breaks, so long expected strings that the test
+          # file wraps still match.
+          norm="$(tr -d '\n' < upstream_iceberg_mode_test.cc | sed 's/"[[:space:]]*"//g')"
+          # Every expected string in our conformance vectors must still appear
+          # verbatim in the upstream C++ format tests.
+          missing=0
+          while IFS= read -r expected; do
+            [ -z "$expected" ] && continue
+            if ! printf '%s' "$norm" | grep -qF -- "$expected"; then
+              echo "::warning::Expected DSL string not found upstream ($REF): $expected"
+              missing=$((missing+1))
+            fi
+          done < <(grep -oE "expect: '[^']+'" tests/iceberg-dsl/conformance-test.js | sed "s/expect: '//; s/'$//")
+          if [ "$missing" -gt 0 ]; then
+            echo "$missing expected DSL string(s) no longer present upstream — the DSL may have changed; re-sync tests/iceberg-dsl vectors and update buildConfigString."
+            exit 1
+          fi
+          echo "All DSL vectors still present in upstream iceberg_mode_test.cc @ $REF"

.stylelintrc

@@ -11,7 +11,8 @@
       {
         "ignoreProperties": [
           "contain",
-          "aspect-ratio"
+          "aspect-ratio",
+          "accent-color"
         ]
       }
     ]

gulp.d/tasks/build-preview-pages.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const Asciidoctor = require('@asciidoctor/core')()
+const log = require('fancy-log')
 const fs = require('fs-extra')
 const handlebars = require('handlebars')
 const merge = require('merge-stream')
@@ -29,12 +30,25 @@ module.exports = (src, previewSrc, previewDest, sink = () => map()) => (done) =>
     ),
   ])
     .then(([baseUiModel, { layouts }]) => {
-      const extensions = ((baseUiModel.asciidoc || {}).extensions || []).map((request) => {
-        ASCIIDOC_ATTRIBUTES[request.replace(/^@|\.js$/, '').replace(/[/]/g, '-') + '-loaded'] = ''
-        const extension = require(request)
-        extension.register.call(Asciidoctor.Extensions)
-        return extension
-      })
+      const extensions = ((baseUiModel.asciidoc || {}).extensions || [])
+        .map((request) => {
+          let extension
+          try {
+            extension = require(request)
+          } catch (err) {
+            // A sample ui-model.yml can reference an extension from a
+            // sibling package (e.g. docs-extensions-and-macros) before that
+            // package has actually published it -- don't let one
+            // not-yet-available extension take down the whole preview
+            // build; skip it and keep going.
+            log.warn(`Preview build: could not load AsciiDoc extension '${request}', skipping it (${err.message})`)
+            return null
+          }
+          ASCIIDOC_ATTRIBUTES[request.replace(/^@|\.js$/, '').replace(/[/]/g, '-') + '-loaded'] = ''
+          extension.register.call(Asciidoctor.Extensions)
+          return extension
+        })
+        .filter(Boolean)
       const asciidoc = { extensions }
       for (const component of baseUiModel.site.components) {
         for (const version of component.versions || []) {

iceberg-editor/README.md

@@ -0,0 +1,28 @@
+# iceberg-editor
+
+WASM engine tooling for the interactive **Iceberg Mode Explorer** docs tool,
+mirroring the layout of `blobl-editor/` (the Bloblang playground's Go→WASM
+engine).
+
+Unlike Bloblang — whose engine is Go and wraps `benthos` directly — Iceberg
+mode translation is implemented in **C++** in the Redpanda core
+(`redpanda/src/v/iceberg/conversion/` + `src/v/datalake/`). To keep the docs
+tool faithful to production behavior (and to stay current automatically, one
+build per `major.minor` release), the engine is the **real C++ translation code
+compiled to WebAssembly with Emscripten**, not a re-implementation.
+
+## Status
+
+- `wasm-spike/` — a **feasibility spike** that proves the hardest dependency
+  (Apache Avro C++ + a thin Seastar shim + the `iceberg/conversion` schema
+  mapper) compiles and links under Emscripten. Run this **before** investing in
+  the full engine module. See `wasm-spike/README.md`.
+
+## Why a spike first
+
+The schema/value mappers are synchronous and free of Seastar's reactor, but the
+shared Iceberg type model (`iceberg/datatypes.h`) transitively includes a few
+Seastar utility types (`ss::sstring`, `chunked_vector`) and Redpanda base utils.
+The spike confirms those can be shimmed and that Avro C++ builds under
+Emscripten. If the spike passes, the remaining work (value mapper, DSL, JSON
+bindings, per-release CI) is mechanical.

iceberg-editor/wasm-spike/.gitignore

@@ -0,0 +1,11 @@
+# Everything fetched or built is reproducible from the scripts — never commit it.
+
+# Fetched Redpanda source (fetch-sources.sh, pinned to $REDPANDA_REF)
+vendor/
+
+# Downloaded third-party deps (fmt, boost, avro fork) — keep only the fetcher
+third_party/*
+!third_party/fetch-deps.sh
+
+# Build outputs (objects, wasm, js glue)
+build/