Add project setup, map overlays, and automated releases

.changeset/README.md

@@ -5,6 +5,10 @@ Run `pnpm changeset` for a change that should ship in the next release. Select
 configuration migration. App, IIIF, renderer and canvas-panel changes all ship
 as this one package, even when their source lives in another workspace folder.
 
+These summaries become the package changelog and GitHub release notes. Keep each
+to a few sentences about user-visible changes. Include required migration steps
+and removed options; link to documentation for examples and detailed behavior.
+
 Content-only changes belong in the content repository's history. Changes that
 do not need a release do not need a changeset.
 

.changeset/content-independent-development.md

@@ -0,0 +1,7 @@
+---
+"@allmaps/slides": patch
+---
+
+Root development commands now accept a content directory instead of selecting
+one automatically, for example `pnpm dev ./content/slides-template`.
+Remove unused app code and dependencies.

.changeset/fresh-narrative-map.md

@@ -0,0 +1,7 @@
+---
+"@allmaps/slides": minor
+---
+
+Add `slides init [directory]` (alias `slides create`) to create a minimal English
+project. Prompts ask for a title and optional Protomaps key; use `--title`,
+`--protomaps-key` and `--yes` for automation. Existing files are never overwritten.

.changeset/global-overlay-layers.md

@@ -0,0 +1,12 @@
+---
+"@allmaps/slides": minor
+---
+
+Add global `layers` defaults and custom MapLibre layers, including GeoJSON labels.
+Each slide resolves its overrides independently in the viewer and previews.
+GeoJSON layers fade using native transitions; feature-dependent circle and symbol
+opacity may switch abruptly.
+
+Fix duplicate layer prefixes. Remove any workaround `user-` prefix from authored
+overrides: use `<source>-line`, `<source>-fill`, `<source>-point-circle`,
+`<source>-point-symbol`, or a custom layer's `id`.

.changeset/optional-basemaps.md

@@ -0,0 +1,7 @@
+---
+"@allmaps/slides": patch
+---
+
+Show no basemap when no custom style or Protomaps key is supplied, including in
+previews. An empty `map.styles` block is no longer needed. Keys can still come
+from configuration or `PUBLIC_PROTOMAPS_KEY`.

.changeset/quiet-dev-startup.md

@@ -0,0 +1,6 @@
+---
+"@allmaps/slides": patch
+---
+
+Fix the missing base `tsconfig.json` warning when starting development, build or
+preview commands.

.changeset/remove-image-map-mode.md

@@ -0,0 +1,9 @@
+---
+"@allmaps/slides": minor
+---
+
+Remove `warpedMaps[].type: Image`, its `region` and `wiggle` options, the
+`model/map/image` export and the unused `imageLayer` label.
+Move non-georeferenced images to [zoomable IIIF figures](https://github.com/allmaps/slides/blob/main/docs/images.md#iiif-figures)
+in slide Markdown; use `data-region` to retain a crop and `hideBasemap: true` on
+the slide when needed.

.changeset/shared-camera-fit.md

@@ -0,0 +1,12 @@
+---
+"@allmaps/slides": minor
+---
+
+Support `fit: contain` (default), `cover` and `equal` on slides and start screens,
+in both the viewer and previews. Set `padding` for a uniform inner margin without
+changing the space reserved by the interface. Use `fit: cover` with `padding: 0`
+for edge-to-edge fitting, or negative padding for extra cropping.
+
+Remove unused chapter fields `caption`, `freeze` and `contain`, and interface
+labels `chapterCountSingular`, `chapterCountPlural` and `noCredits`.
+Per-map `warpedMaps[].caption` remains supported.

.changeset/space-map-comparison.md

@@ -0,0 +1,8 @@
+---
+"@allmaps/slides": patch
+---
+
+Hold Space to hide warped maps for comparison with the basemap; release it to
+restore them. This replaces the backtick shortcut. Fix shortcuts after map
+interaction and text-panel scrolling, and make both Space and layers-panel
+hide/show controls redraw immediately after zooming.

.github/test-paths.yml

@@ -0,0 +1,12 @@
+# Used with dorny/paths-filter's `every` predicate in both test workflows.
+# Run tests unless every changed file is documentation. Keep content Markdown,
+# licenses, workflow files and unknown paths covered by default.
+tests:
+  - '**'
+  - '!docs/**'
+  - '!README.md'
+  - '!packages/*/README.md'
+  - '!apps/*/README.md'
+  - '!packages/*/CHANGELOG.md'
+  - '!apps/*/CHANGELOG.md'
+  - '!.changeset/*.md'

.github/workflows/release.yml

@@ -1,26 +1,115 @@
-name: Release notes
+name: Publish release
 
 on:
   push:
+    branches: [main]
     tags: ['@allmaps/slides@*']
+    paths: ['packages/slides/package.json']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Optional existing tag: repair GitHub release only. Leave empty to publish the current version on main.'
+        required: false
+        type: string
+
+concurrency:
+  group: publish-slides
+  cancel-in-progress: false
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
+  publish:
+    if: github.ref == 'refs/heads/main' && inputs.tag == ''
+    runs-on: ubuntu-24.04
+    environment: npm
+    timeout-minutes: 20
+    permissions:
+      contents: write
+      id-token: write
+    outputs:
+      release: ${{ steps.plan.outputs.release }}
+      tag: ${{ steps.plan.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          package-manager-cache: false
+      - name: Check version and previous publication
+        id: plan
+        env:
+          RELEASE_BEFORE: ${{ github.event.before }}
+        run: node scripts/prepare-npm-release.mjs
+      - uses: pnpm/action-setup@v4
+        if: steps.plan.outputs.release == 'true' && steps.plan.outputs.published == 'false'
+      - name: Install npm with trusted publishing support
+        if: steps.plan.outputs.release == 'true' && steps.plan.outputs.published == 'false'
+        run: npm install --global npm@11
+      - name: Install packaging dependencies
+        if: steps.plan.outputs.release == 'true' && steps.plan.outputs.published == 'false'
+        # Packaging does not run the native renderer or need content repositories.
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Build and pack
+        if: steps.plan.outputs.release == 'true' && steps.plan.outputs.published == 'false'
+        # pnpm applies publishConfig.exports and removes workspace dependencies.
+        run: pnpm --filter @allmaps/slides pack --out "$RUNNER_TEMP/slides.tgz"
+      - name: Publish to npm
+        if: steps.plan.outputs.release == 'true' && steps.plan.outputs.published == 'false'
+        env:
+          NPM_TAG: ${{ steps.plan.outputs.npmTag }}
+        run: npm publish "$RUNNER_TEMP/slides.tgz" --access public --tag "$NPM_TAG" --provenance
+      - name: Create and push the release tag
+        if: steps.plan.outputs.release == 'true'
+        env:
+          RELEASE_TAG: ${{ steps.plan.outputs.tag }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          if ! git show-ref --verify --quiet "refs/tags/$RELEASE_TAG"; then
+            git tag -a "$RELEASE_TAG" "$GITHUB_SHA" -m "$RELEASE_TAG"
+          fi
+          gh auth setup-git
+          git push origin "refs/tags/$RELEASE_TAG"
+
   notes:
+    needs: publish
+    # Tags pushed by GITHUB_TOKEN do not start another workflow; create the
+    # release here too. User-pushed tags and manual repairs keep working.
+    if: >-
+      always() && !cancelled() &&
+      ((needs.publish.result == 'success' && needs.publish.outputs.release == 'true') ||
+       startsWith(github.ref, 'refs/tags/@allmaps/slides@') ||
+       (github.event_name == 'workflow_dispatch' && inputs.tag != ''))
     runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    env:
+      RELEASE_TAG: ${{ inputs.tag || needs.publish.outputs.tag || github.ref_name }}
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+          persist-credentials: false
       - uses: actions/setup-node@v6
         with:
           node-version: 24
       - name: Extract notes for the tagged version
-        run: node scripts/release-notes.mjs > "$RUNNER_TEMP/slides-release-notes.md"
+        run: GITHUB_REF_NAME="$RELEASE_TAG" node scripts/release-notes.mjs > "$RUNNER_TEMP/slides-release-notes.md"
       - name: Create GitHub release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          args=(--verify-tag --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/slides-release-notes.md")
-          if [[ "$GITHUB_REF_NAME" == *-beta.* ]]; then args+=(--prerelease); fi
-          gh release create "$GITHUB_REF_NAME" "${args[@]}"
+          if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+            echo "Release $RELEASE_TAG already exists."
+            exit 0
+          fi
+          args=(--verify-tag --title "$RELEASE_TAG" --notes-file "$RUNNER_TEMP/slides-release-notes.md")
+          if [[ "$RELEASE_TAG" == *-beta.* ]]; then args+=(--prerelease); fi
+          gh release create "$RELEASE_TAG" "${args[@]}"

.github/workflows/slides.yml

@@ -1,45 +1,57 @@
 name: Slides architecture
 on:
+  # Always report the required check; skip expensive steps for documentation-only PRs.
   pull_request:
-    paths:
-      - "packages/**"
-      - "package.json"
-      - ".changeset/**"
-      - "apps/slides/**"
-      - "scripts/**"
-      - "content/**"
-      - "pnpm-lock.yaml"
-      - "pnpm-workspace.yaml"
-      - ".github/workflows/slides.yml"
   workflow_dispatch:
 jobs:
   integration:
     runs-on: ubuntu-24.04
     timeout-minutes: 20
     permissions:
       contents: read
+      pull-requests: read
     steps:
       - uses: actions/checkout@v6
+      - name: Detect changes that need testing
+        id: changes
+        # Manual runs and PRs beyond the API's 3,000-file limit run all tests.
+        if: github.event_name == 'pull_request' && github.event.pull_request.changed_files <= 3000
+        uses: dorny/paths-filter@v4
         with:
-          submodules: recursive
+          predicate-quantifier: every
+          filters: .github/test-paths.yml
+      - name: Documentation-only changes
+        if: steps.changes.outputs.tests == 'false'
+        run: echo "Documentation-only changes; integration tests were not needed." >> "$GITHUB_STEP_SUMMARY"
+      - name: Check out the integration presentation
+        if: steps.changes.outputs.tests != 'false'
+        run: git submodule update --init content/slides-template
       - uses: pnpm/action-setup@v4
+        if: steps.changes.outputs.tests != 'false'
         with:
           version: 10.22.0
       - uses: actions/setup-node@v6
+        if: steps.changes.outputs.tests != 'false'
         with:
           node-version: 24
           cache: pnpm
       - name: Set up native renderer
+        if: steps.changes.outputs.tests != 'false'
         run: sudo sh packages/static-render/scripts/install-system-deps.sh
       - run: pnpm install --frozen-lockfile
+        if: steps.changes.outputs.tests != 'false'
       - name: Unit and component checks
+        if: steps.changes.outputs.tests != 'false'
         run: |
           pnpm -r test
           pnpm --filter @allmaps/slides --filter @allmaps/iiif --filter @allmaps/static-render check
-          pnpm exec slides check ./content/gravity-at-sea
+          pnpm check ./content/slides-template
       - name: Native pixel alignment
+        if: steps.changes.outputs.tests != 'false'
         run: xvfb-run -a pnpm --filter @allmaps/static-render test:native
       - name: Independent development sites
+        if: steps.changes.outputs.tests != 'false'
         run: pnpm --filter @allmaps/slides test:dev
       - name: Fresh installed consumer
+        if: steps.changes.outputs.tests != 'false'
         run: xvfb-run -a pnpm --filter @allmaps/slides test:package

.github/workflows/static-render.yml

@@ -1,24 +1,31 @@
 name: Static renderer
 on:
+  # Always report the required check; skip expensive steps for documentation-only PRs.
   pull_request:
-    paths:
-      - "packages/**"
-      - "apps/slides/**"
-      - "scripts/**"
-      - ".dockerignore"
-      - "pnpm-lock.yaml"
-      - "pnpm-workspace.yaml"
-      - ".github/workflows/static-render.yml"
   workflow_dispatch:
 jobs:
   container:
     runs-on: ubuntu-24.04
     permissions:
       contents: read
+      pull-requests: read
     steps:
       - uses: actions/checkout@v6
+      - name: Detect changes that need testing
+        id: changes
+        # Manual runs and PRs beyond the API's 3,000-file limit run all tests.
+        if: github.event_name == 'pull_request' && github.event.pull_request.changed_files <= 3000
+        uses: dorny/paths-filter@v4
+        with:
+          predicate-quantifier: every
+          filters: .github/test-paths.yml
+      - name: Documentation-only changes
+        if: steps.changes.outputs.tests == 'false'
+        run: echo "Documentation-only changes; container tests were not needed." >> "$GITHUB_STEP_SUMMARY"
       - uses: docker/setup-buildx-action@v3
+        if: steps.changes.outputs.tests != 'false'
       - name: Build image and run native smoke test
+        if: steps.changes.outputs.tests != 'false'
         uses: docker/build-push-action@v6
         with:
           context: .
@@ -30,5 +37,6 @@ jobs:
           cache-from: type=gha,scope=slides-renderer
           cache-to: type=gha,mode=max,scope=slides-renderer
       - name: Check container entrypoint
+        if: steps.changes.outputs.tests != 'false'
         timeout-minutes: 1
         run: docker run --rm slides-renderer:check node packages/static-render/bin/render.mjs --help

.github/workflows/version.yml

@@ -25,7 +25,6 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-          submodules: recursive
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with: