Court/editor fixes, release+preview Pages pipeline, and arc42 docs

.github/workflows/ci.yml

@@ -3,9 +3,15 @@ name: CI
 on:
   push:
     branches: [main]
+    tags: ['v*']
   pull_request:
     branches: [main]
 
+# Allow one concurrent deployment; newer runs supersede in-progress ones.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
 jobs:
   build:
     name: Build & Validate
@@ -20,19 +26,17 @@ jobs:
       - run: npm run build
       - run: node scripts/validate-examples.js
 
-      - name: Assemble Pages artifact
-        if: github.ref == 'refs/heads/main'
-        run: |
-          mkdir -p _site
-          cp index.html style.css ocf-bundle.js ocf-bundle.js.map _site/
-          cp -r examples _site/examples
-          cp opencoachingformat-v1.schema.json _site/
-
-      - name: Upload Pages artifact
-        if: github.ref == 'refs/heads/main'
-        uses: actions/upload-pages-artifact@v3
+  # On a release tag, package.json must match the tag, or we refuse to ship.
+  version-check:
+    name: Version matches tag
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          path: '_site'
+          node-version: '20'
+      - run: bash scripts/check-version.sh "${GITHUB_REF_NAME}"
 
   test:
     name: E2E Tests
@@ -49,18 +53,35 @@ jobs:
       - run: npx playwright install chromium --with-deps
       - run: npm test
 
+  # Assemble the full Pages site (root = newest release tag, /preview = main)
+  # only after build + tests are green. Runs on main pushes and on tag pushes.
   deploy:
     name: Deploy to GitHub Pages
     needs: [build, test]
-    if: github.ref == 'refs/heads/main'
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       pages: write
       id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
+      - uses: actions/checkout@v4
+        with:
+          # Need full history + all tags so build-pages.sh can pick the newest.
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - name: Assemble Pages site (release + preview)
+        run: bash scripts/build-pages.sh _site
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -6,3 +6,4 @@ ocf-bundle.js.map
 .idea/
 playwright-report/
 test-results/
+_site/

README.md

@@ -6,7 +6,13 @@
 
 Reference web editor for the [Open Coaching Format](https://github.com/opencoachingformat/spec) — an open standard for basketball drill diagrams and animations.
 
-**Live demo:** https://opencoachingformat.github.io/ocf-editor
+**Live demo (latest release):** https://opencoachingformat.github.io/ocf-editor
+**Preview (current `main`):** https://opencoachingformat.github.io/ocf-editor/preview/
+
+> The root URL serves the latest tagged release; `/preview/` always tracks the
+> current `main` and is redeployed on every merge (after CI passes). See
+> [Releases & Deployment](#releases--deployment). Architecture is documented in
+> [doc/arc42.md](doc/arc42.md).
 
 ---
 
@@ -56,6 +62,30 @@ OCF (Open Coaching Format) is a JSON-based standard for basketball drill diagram
 
 This editor intentionally deviates from the spec in two places for `ajv` strict-mode compatibility — see the comment block at the top of `src/schema.js` for details.
 
+## Releases & Deployment
+
+GitHub Pages hosts two builds side by side:
+
+- **`/`** (root) — the latest **release**, built from the newest `v*` tag.
+- **`/preview/`** — the current **`main`**, redeployed on every merge (after CI passes).
+
+Until the first release tag exists, the root mirrors the preview build.
+
+To cut a release:
+
+1. Bump `version` in `package.json` (and the `.app-version` badge in `index.html`).
+2. Commit and merge to `main`.
+3. Tag the merge commit and push the tag:
+   ```bash
+   git tag v0.3.0
+   git push origin v0.3.0
+   ```
+
+CI refuses to deploy a tag whose `package.json` version doesn't match it
+(`scripts/check-version.sh`). The Pages site is assembled by
+`scripts/build-pages.sh`, which you can run locally (`bash scripts/build-pages.sh`)
+to preview the exact deployed layout in `./_site`.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).