v0.20: runtime subpaths, ESM-only distribution, demo-asset catalog and two-channel Pages

.github/workflows/ci.yml

@@ -5,8 +5,9 @@ name: CI
 # runs locally. A lane is added there, never here.
 #
 #   plan ─┬─► gates (matrix)
-#         ├─► test (matrix) ─► skip-budget
-#         └─► build ─┬─► verify (matrix)
+#         ├─► test (matrix) ──┬─► skip-budget
+#         └─► build ─┬────────┘
+#                    ├─► verify (matrix)
 #                    └─► site ─► smoke
 #                                       all ─► verdict   (the required check)
 #
@@ -202,8 +203,8 @@ jobs:
   # One budget over every lane's report: a test that moves from one lane to
   # another must not change the count.
   skip-budget:
-    needs: [plan, test]
-    if: ${{ !cancelled() && needs.plan.outputs.skipBudget == 'true' && needs.test.result == 'success' }}
+    needs: [plan, test, build]
+    if: ${{ !cancelled() && needs.plan.outputs.skipBudget == 'true' && needs.test.result == 'success' && (needs.build.result == 'success' || needs.build.result == 'skipped') }}
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -225,6 +226,8 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: ./.github/actions/setup
+        with:
+          browser: chromium
 
       - name: Build core
         env:
@@ -241,12 +244,32 @@ jobs:
           EXOJS_REQUIRE_PRODUCTION_BUILD: '1'
         run: pnpm test:production-stripping
 
+      - name: Verify the packed Core, its runtime subpaths and the legacy shims against the built dist
+        env:
+          EXOJS_REQUIRE_PRODUCTION_BUILD: '1'
+        run: pnpm test:release-dist --reporter=minimal --reporter=junit --outputFile.junit=./test-results/build.junit.xml
+
+      - name: Keep the JUnit report for the skip budget
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: junit-build
+          path: test-results/*.junit.xml
+          retention-days: 1
+          if-no-files-found: ignore
+
+      - name: Verify the built ESM tree through a browser import map
+        run: pnpm test:esm-importmap
+
       - uses: actions/upload-artifact@v7
         with:
           name: dist
+          # The demo-assets build copies its standard media into media/, which
+          # the package exports and packs; the verify jobs pack from this tree.
           path: |
             dist/
             packages/*/dist/
+            packages/exojs-demo-assets/media/
           retention-days: 1
           if-no-files-found: error
 
@@ -272,21 +295,42 @@ jobs:
     if: ${{ !cancelled() && needs.plan.outputs.site == 'true' && needs.build.result == 'success' }}
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    outputs:
+      # A re-run of failed jobs keeps this job's earlier attempt, so the smoke
+      # and the publisher find the candidate by this name, not by recomputing it.
+      candidate: site-${{ steps.channel.outputs.channel }}-${{ github.sha }}-${{ github.run_attempt }}
     steps:
       - uses: actions/checkout@v6
       - uses: ./.github/actions/setup
         with:
           dist: 'true'
 
+      # main builds Stable at /ExoJS/, next builds Next at /ExoJS/next/ (a pull
+      # request builds the channel of the branch it targets); any other ref
+      # builds Stable. The table lives in scripts/pages/site-channel.ts.
+      - id: channel
+        env:
+          SITE_REF: ${{ github.event_name == 'pull_request' && github.base_ref || github.ref_name }}
+        run: node scripts/pages/site-channel.ts >> "$GITHUB_OUTPUT"
+
       # Typechecks the site against the published entry points, so it needs
       # the dist the build job produced.
       - run: pnpm gates site
 
       - env:
           EXOJS_PACKAGE_PATH: ..
+          EXOJS_SITE_CHANNEL: ${{ steps.channel.outputs.channel }}
+          EXOJS_SITE_BASE: ${{ steps.channel.outputs.base }}
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
         run: pnpm site:build
 
+      # The tree must match its own site-build.json, carry this commit, channel
+      # and base, contain no links or special files and fit the site budget.
+      - name: Verify the site candidate
+        env:
+          SITE_CHANNEL: ${{ steps.channel.outputs.channel }}
+        run: node scripts/pages/channel-artifact.ts verify --dir site/dist --channel "$SITE_CHANNEL" --sha "$GITHUB_SHA"
+
       - name: Upload tooling logs on failure
         if: ${{ failure() }}
         uses: actions/upload-artifact@v7
@@ -297,12 +341,14 @@ jobs:
           include-hidden-files: true
           if-no-files-found: warn
 
-      # Deploy Pages ships exactly this artifact; it builds nothing itself.
+      # Deploy Pages ships exactly this artifact; it builds nothing itself. A
+      # push to main or next is a publishable channel candidate and is kept for
+      # 90 days, so the publisher never depends on a short-lived download.
       - uses: actions/upload-artifact@v7
         with:
-          name: site-dist-${{ github.sha }}
+          name: site-${{ steps.channel.outputs.channel }}-${{ github.sha }}-${{ github.run_attempt }}
           path: site/dist/
-          retention-days: 1
+          retention-days: ${{ github.event_name == 'push' && 90 || 1 }}
           if-no-files-found: error
 
   # Every catalog example through the real playground route, against the site
@@ -321,13 +367,21 @@ jobs:
       - uses: ./.github/actions/setup
         with:
           browser: chromium
+      # The exact candidate tree, served at the base its site-build.json names.
       - uses: actions/download-artifact@v8
         with:
-          name: site-dist-${{ github.sha }}
+          name: ${{ needs.site.outputs.candidate }}
           path: site/dist
 
       - run: pnpm test:examples:smoke --renderer webgl2 ${{ needs.plan.outputs.smokeSample == 'true' && '--sample' || '' }}
 
+      # The playground shell around the examples: console capture across the
+      # preview iframe and the Output panel's layouts, and the Asset Browser's
+      # previews, cancelled loads and generated snippets. Runs after a failed
+      # smoke too, so one run reports both.
+      - run: pnpm test:playground:e2e
+        if: ${{ !cancelled() }}
+
       - name: Keep the smoke report
         if: ${{ !cancelled() }}
         uses: actions/upload-artifact@v7

.github/workflows/deploy-pages.yml

@@ -1,83 +1,125 @@
 name: Deploy Pages
 
-# Deploys the site EXACTLY as CI built and validated it — this workflow builds
-# no source code. CI's `site` job (and a release's `prepare` job) runs the site
-# gates and `site:build` and uploads `site/dist/**` as `site-dist-<sha>`; here
-# that same artifact is downloaded from the run that triggered this one and
-# handed to Pages unchanged.
+# The one publisher of the project site. GitHub Pages serves a single tree, so
+# every deployment carries both channels: Stable at /ExoJS/ and Next at
+# /ExoJS/next/, each exactly as a green CI push to main or next (or a stable
+# Release) built and smoked it. This workflow builds no site code.
 #
-# The defect this prevents: the workflow used to check the sources out and
-# rebuild the library and the site itself, so what went live was a second build
-# that no gate had ever seen. A green CI run said nothing about the deployed
-# bytes.
+# The triggering run is only a wake-up call. On every start the publisher
+# re-decides BOTH channels from GitHub's own metadata (scripts/pages/
+# select-channels.ts): each channel gets the newest qualified candidate on its
+# branch's current history, or keeps what is already published. A queued or
+# re-run event can therefore neither roll a channel back nor drop the other
+# channel's update, and a green run without a site candidate changes nothing.
 #
-# Fail-closed by construction: there is no `workflow_dispatch` path, because a
-# manual run has no triggering run to read the artifact from. If the artifact is
-# missing or belongs to a different commit, the download step fails and nothing
-# is deployed. To re-deploy, re-run the CI workflow for the commit.
+# Trust: only successful same-repository push runs of CI (main/next) and
+# stable Release tags qualify; a pull request, a fork or a manual dispatch
+# never does. Candidates are downloaded by the trusted scripts of the
+# default-branch checkout below, never executed, and checked against the
+# digest GitHub reports, their own site-build.json and the archive rules
+# before anything is composed. Any doubt deploys nothing and leaves the live
+# site as it is.
+#
+# A deployment also keeps its composed tree (the Pages artifact) and its
+# channels.json for 90 days, so a channel whose candidate expired can be
+# carried over unchanged from the last published snapshot.
 
 on:
   workflow_run:
     workflows: ['Release', 'CI']
     types: [completed]
 
-permissions:
-  contents: read
-  # Reading an artifact from ANOTHER workflow run needs `actions: read` plus an
-  # explicit token on the download step.
-  actions: read
-  pages: write
-  id-token: write
+permissions: {}
 
+# One queue for the whole site, and a running deployment is never cancelled.
+# Ordering does not rest on this: each run re-decides both channels when it
+# starts.
 concurrency:
-  group: pages-${{ github.event.workflow_run.head_sha }}
-  cancel-in-progress: true
+  group: pages-combined
+  cancel-in-progress: false
 
 jobs:
-  deploy:
-    name: Deploy to GitHub Pages
+  compose:
+    name: Compose Stable and Next
     if: >-
       ${{
         github.event_name == 'workflow_run' &&
         github.event.workflow_run.conclusion == 'success' &&
-        (
-          github.event.workflow_run.name == 'Release' ||
-          (
-            github.event.workflow_run.name == 'CI' &&
-            github.event.workflow_run.event == 'push' &&
-            github.event.workflow_run.head_branch == 'main'
-          )
-        )
+        github.event.workflow_run.event == 'push' &&
+        github.event.workflow_run.repository.full_name == github.repository &&
+        github.event.workflow_run.head_repository.full_name == github.repository
       }}
     runs-on: ubuntu-latest
-    timeout-minutes: 10
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      # Listing runs and reading artifacts of other workflow runs.
+      actions: read
+    outputs:
+      deploy: ${{ steps.select.outputs.deploy }}
     steps:
-      # `run-id` pins the download to the exact run that triggered this one, and
-      # the commit in the artifact name pins it to that run's commit — an older
-      # or unrelated build cannot be picked up. A missing artifact fails here.
-      - name: Download validated site artifact
-        uses: actions/download-artifact@v8
+      # The publisher's own scripts, from the default branch - never from a
+      # candidate. Dependency-free TypeScript that node strips: no install.
+      - uses: actions/checkout@v6
         with:
-          name: site-dist-${{ github.event.workflow_run.head_sha }}
-          run-id: ${{ github.event.workflow_run.id }}
-          github-token: ${{ github.token }}
-          path: site-dist
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+          sparse-checkout-cone-mode: false
+          sparse-checkout: |
+            /.nvmrc
+            /scripts/pages/
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+
+      - name: Select both channels
+        id: select
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          TRIGGER_RUN_ID: ${{ github.event.workflow_run.id }}
+        run: node scripts/pages/select-channels.ts --out "$RUNNER_TEMP/selection.json"
 
-      - name: Verify the artifact carries a built site
-        run: |
-          test -f site-dist/index.html || {
-            echo "::error::site-dist-${{ github.event.workflow_run.head_sha }} has no index.html — refusing to deploy."
-            exit 1
-          }
+      - name: Fetch, verify and compose the channels
+        if: steps.select.outputs.deploy == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          node scripts/pages/compose-site.ts
+          --selection "$RUNNER_TEMP/selection.json"
+          --work "$RUNNER_TEMP/channels"
+          --out "$RUNNER_TEMP/site"
+          --channels-out "$RUNNER_TEMP/channels-record"
 
       - name: Package for Pages
+        if: steps.select.outputs.deploy == 'true'
         uses: actions/upload-pages-artifact@v5
         with:
-          path: site-dist
+          path: ${{ runner.temp }}/site
+          retention-days: 90
 
+      - name: Keep the deployed pairing
+        if: steps.select.outputs.deploy == 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          name: pages-channels-${{ github.run_id }}
+          path: ${{ runner.temp }}/channels-record/channels.json
+          retention-days: 90
+          if-no-files-found: error
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: compose
+    if: needs.compose.outputs.deploy == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
       - name: Deploy
         id: deployment
         uses: actions/deploy-pages@v5

.github/workflows/release.yml

@@ -81,33 +81,36 @@ jobs:
           pnpm verify:lockstep
           pnpm verify:release-matrix
 
-      - name: Build core, extensions and the site
+      - name: Build core (with its runtime modules), adapters and the site
         env:
           EXOJS_PACKAGE_PATH: ..
+          # A release tag sits on main: its site is the Stable channel.
+          EXOJS_SITE_CHANNEL: stable
         # One line per package: verify:release-matrix checks each against the
         # lockstep list, so a package added without a build line fails there.
         run: |
           pnpm build
-          pnpm --filter @codexo/exojs-particles build
-          pnpm --filter @codexo/exojs-tilemap build
           pnpm --filter @codexo/exojs-tiled build
-          pnpm --filter @codexo/exojs-physics build
-          pnpm --filter @codexo/exojs-tilemap-physics build
-          pnpm --filter @codexo/exojs-lighting build
-          pnpm --filter @codexo/exojs-pathfinding build
-          pnpm --filter @codexo/exojs-audio-fx build
           pnpm --filter @codexo/exojs-aseprite build
           pnpm --filter @codexo/exojs-ldtk build
           pnpm --filter @codexo/exojs-react build
           pnpm --filter create-exo-app build
+          # Not a lockstep package, but the site serves its catalog and media.
+          pnpm --filter @codexo/exojs-demo-assets build
           pnpm site:build
 
-      # Deploy Pages ships the site of a successful release from this artifact.
+      - name: Verify the Stable site candidate
+        env:
+          RELEASE_SHA: ${{ needs.trust.outputs.sha }}
+        run: node scripts/pages/channel-artifact.ts verify --dir site/dist --channel stable --sha "$RELEASE_SHA"
+
+      # Deploy Pages may ship the Stable site of a successful release from this
+      # artifact, and falls back to it when the CI candidate has expired.
       - uses: actions/upload-artifact@v7
         with:
-          name: site-dist-${{ needs.trust.outputs.sha }}
+          name: site-stable-${{ needs.trust.outputs.sha }}-${{ github.run_attempt }}
           path: site/dist/
-          retention-days: 1
+          retention-days: 90
           if-no-files-found: error
 
       # The site build regenerates tracked content with platform-dependent

.gitignore

@@ -2,6 +2,9 @@
 node_modules
 dist/*
 packages/*/dist
+# Assembled from examples/assets by the demo-assets build and archive scripts.
+packages/exojs-demo-assets/media/
+packages/exojs-demo-assets/archives/
 coverage
 __screenshots__
 npm-debug.log*