@signalk/app-dock 1.2.0 → 1.2.1

package/.github/release.yml

@@ -0,0 +1,37 @@
+# Categories for the release notes GitHub generates for each tag, built from
+# the titles of the PRs merged since the previous one. release-please asks
+# GitHub for these notes (changelog-type: github in
+# release-please-config.json), and so does release_on_tag.yml for a
+# pre-release tag pushed by hand.
+#
+# A PR lands in the first category it matches, so the catch-all is last.
+# workflows/label-by-title.yml sets the label from the PR title's type, and
+# this file and that workflow name the same labels. A label set by hand
+# places a PR the same way until its title is edited; an unlabelled one
+# still appears, under Other.
+changelog:
+  exclude:
+    labels:
+      - skip-changelog
+      # release-please's own release PR, merged right before each tag, which
+      # would otherwise list itself.
+      - 'autorelease: pending'
+      - 'autorelease: tagged'
+  categories:
+    - title: 🚀 Features
+      labels:
+        - feature
+        - enhancement
+    - title: 🐛 Fixes
+      labels:
+        - bug
+        - fix
+    - title: 📖 Documentation
+      labels:
+        - documentation
+    - title: 📦 Dependencies
+      labels:
+        - dependencies
+    - title: Other
+      labels:
+        - '*'

package/.github/workflows/label-by-title.yml

@@ -0,0 +1,67 @@
+name: label-by-title
+
+on:
+  pull_request_target:
+    types: [opened, edited, reopened]
+
+permissions: {}
+
+jobs:
+  # .github/release.yml sorts the release notes by label, and a pull request
+  # opened from the command line carries none. The label follows the title's
+  # conventional-commit type. Only the title is read, with no checkout and
+  # nothing from the pull request run here, which is what makes
+  # pull_request_target safe to use and what lets a pull request from a fork
+  # be labelled.
+  #
+  # `edited` also fires for a body or base-branch edit; those leave the labels
+  # alone, so a label set by hand stays until the title changes.
+  label:
+    if: ${{ github.event.action != 'edited' || github.event.changes.title }}
+    # One run per pull request at a time: two overlapping runs would each read
+    # the labels, then each edit, and could leave two managed labels behind.
+    # Set on the job, after the condition above, so that a body edit, which
+    # skips the job, cannot cancel a title edit's run.
+    concurrency:
+      group: label-by-title-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      pull-requests: write
+    steps:
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.pull_request.number }}
+          TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          # The labels this workflow owns: one of them at a time, so a title
+          # edited from feat to fix swaps the label rather than adding one.
+          # A type not listed gets none of them and lands under Other.
+          managed="enhancement bug documentation skip-changelog"
+          conventional='^([a-z]+)(\([^)]*\))?!?: '
+          type=""
+          if [[ "$TITLE" =~ $conventional ]]; then
+            type="${BASH_REMATCH[1]}"
+          fi
+          case "$type" in
+            feat|perf) wanted=enhancement ;;
+            fix) wanted=bug ;;
+            docs) wanted=documentation ;;
+            build|ci|test|chore|refactor|style) wanted=skip-changelog ;;
+            *) wanted="" ;;
+          esac
+          current=$(gh pr view "$NUMBER" --repo "$REPO" --json labels --jq '[.labels[].name] | join(" ")')
+          args=()
+          for label in $managed; do
+            case " $current " in *" $label "*) has=1 ;; *) has=0 ;; esac
+            if [ "$label" = "$wanted" ] && [ "$has" = 0 ]; then args+=(--add-label "$label"); fi
+            if [ "$label" != "$wanted" ] && [ "$has" = 1 ]; then args+=(--remove-label "$label"); fi
+          done
+          if [ "${#args[@]}" = 0 ]; then
+            echo "#$NUMBER '$TITLE': nothing to change (${wanted:-no managed label})"
+          else
+            gh pr edit "$NUMBER" --repo "$REPO" "${args[@]}"
+            echo "#$NUMBER '$TITLE': ${args[*]}"
+          fi

package/.github/workflows/release-please.yml

@@ -0,0 +1,109 @@
+name: release-please
+
+on:
+  push:
+    branches: [main]
+  # The gate below runs release-please only for a push that carries a commit
+  # users get, so a release pull request it has already opened is not
+  # refreshed by a docs or ci merge, and a config change is exactly such a
+  # merge. This trigger re-runs it on demand, which is what rewrites an
+  # outstanding release pull request against the current configuration.
+  workflow_dispatch:
+
+permissions: {}
+
+# One release-please run at a time: a push and a manual run, or two pushes
+# landing close together, would each read the release pull request's state
+# and each write it, and the later write could undo the earlier one.
+# cancel-in-progress is false so a run already creating a tag or dispatching
+# the publish is never killed part-way. A run waiting behind it can still be
+# replaced by a newer one, which costs nothing here: release-please derives
+# the release pull request from the commit range, so the newest run produces
+# the same result the superseded one would have.
+#
+# The group is a constant rather than keyed on github.ref: the action is
+# given no target-branch, so every run, including a dispatch launched from
+# some other branch, acts on the default branch's release pull request.
+concurrency:
+  group: release-please
+  cancel-in-progress: false
+
+jobs:
+  # GitHub's release notes are never empty, so release-please would propose
+  # a release after every merge, a docs or ci change included. Only a push
+  # carrying a change users get, or the merge of the release PR itself,
+  # which is what creates the tag, goes on to it.
+  #
+  # Every commit in the push is checked, so a merge commit's PR commits count
+  # through their own subjects. A breaking change counts whatever its type, a
+  # `revert:` because what it undoes has shipped, and a `Release-As:` footer,
+  # matched in any case as release-please does, because it asks for a release
+  # on any subject. GitHub's own `Revert "…"` subject is not conventional, so
+  # release-please ignores it and it is not let through here either. The last
+  # alternative is the release PR's own title, pull-request-title-pattern in
+  # release-please-config.json, and must change with it, or the release PR's
+  # merge is judged non-releasable and no tag is ever created. The payload
+  # holds at most 2048 commits, so a push that fills it may hide more and is
+  # let through.
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      releasable: ${{ steps.check.outputs.releasable }}
+    steps:
+      # A manual run carries no commits to judge, and asking for one is the
+      # statement that it should happen, so it bypasses the check below
+      # rather than being skipped by it for having an empty payload.
+      - id: check
+        env:
+          DISPATCHED: ${{ github.event_name == 'workflow_dispatch' }}
+          MESSAGES: ${{ toJSON(github.event.commits.*.message) }}
+          RELEASABLE: '^((feat|fix|perf|revert)(\([^)]*\))?!?: |[a-z]+(\([^)]*\))?!: |chore\(release\): v?[0-9])'
+        run: |
+          if [ "$DISPATCHED" = true ]; then
+            echo "releasable=true" >> "$GITHUB_OUTPUT"
+            echo "Run requested manually; release-please not gated."
+            exit 0
+          fi
+          if jq -e --arg re "$RELEASABLE" '(length >= 2048) or ([.[] | (split("\n")[0] | test($re)) or test("\nBREAKING[- ]CHANGE: ") or test("\nrelease-as: "; "i")] | any)' <<< "$MESSAGES" > /dev/null; then
+            echo "releasable=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "releasable=false" >> "$GITHUB_OUTPUT"
+            echo "No releasable commit in this push; release-please not run."
+          fi
+
+  release-please:
+    needs: gate
+    if: ${{ needs.gate.outputs.releasable == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+      # release-please creates its `autorelease: pending` / `autorelease:
+      # tagged` labels through the issues API the first time it needs them.
+      issues: write
+    outputs:
+      releases_created: ${{ steps.rp.outputs.releases_created }}
+      tag_name: ${{ steps.rp.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v5
+        id: rp
+
+  # The tag release-please just pushed does not start release_on_tag.yml by
+  # itself: an event raised with GITHUB_TOKEN starts no workflow, with
+  # workflow_dispatch as the exception. So release_on_tag.yml is dispatched on
+  # the tag. It has to stay the file that publishes, since npm's trusted
+  # publishing is bound to that workflow file. This is its own job, so that
+  # the right to start workflows is held by nothing but this one command.
+  publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.releases_created == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: write
+    steps:
+      - env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run release_on_tag.yml --repo "$GITHUB_REPOSITORY" --ref "${{ needs.release-please.outputs.tag_name }}"

package/.github/workflows/release_on_tag.yml

@@ -1,16 +1,27 @@
+# Publishes the tag it runs on to npm. Release tags come from release-please:
+# merging its release PR creates the tag and the GitHub Release, then
+# release-please.yml dispatches this workflow on the tag. Pre-release tags
+# (-beta.N, -rc.N, -alpha.N) are pushed by hand, and only a pushed tag gets
+# its GitHub Release created here.
 name: 'Release on tag'
 
 on:
   push:
     tags:
       - 'v*'
+  # How release-please.yml starts this on a tag it created: that tag, pushed
+  # with GITHUB_TOKEN, raises no push event.
+  workflow_dispatch:
 
 concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
+  # A dispatched run is on a tag release-please made, and release-please made
+  # its Release too; creating one here would be a second for the same tag.
   release:
+    if: ${{ github.event_name == 'push' }}
     permissions:
       contents: write
     runs-on: ubuntu-latest
@@ -28,6 +39,10 @@ jobs:
 
   publish:
     needs: release
+    # Runs after the Release on a pushed tag, and without it on a dispatched
+    # one, where that job is skipped. A dispatch can name any ref; only a
+    # release tag is published.
+    if: ${{ !cancelled() && needs.release.result != 'failure' && startsWith(github.ref, 'refs/tags/v') }}
     permissions:
       id-token: write
       contents: read
@@ -43,6 +58,16 @@ jobs:
 
       - run: npm ci
 
+      - name: Verify the tag matches package.json
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG="$(node -p "require('./package.json').version")"
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match package.json version $PKG"
+            exit 1
+          fi
+          echo "tag and package.json agree on $PKG"
+
       - name: Publish to npm
         run: |
           tag="${GITHUB_REF#refs/tags/}"

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.2.1"
+}

package/AGENTS.md

@@ -0,0 +1,134 @@
+# @signalk/app-dock
+
+A Signal K server plugin plus webapp: a macOS-style dock for switching between Signal K webapps on touch screens. The
+dock page holds each app in an iframe, and a double-tap anywhere brings up the dock. User-facing behaviour is documented
+in `README.md`; this file covers what a contributor needs to keep intact.
+
+## Architecture
+
+Three surfaces ship together from one package:
+
+- **`plugin/index.js`**: the server plugin (CommonJS). It holds the schema, seeds the default apps on first start, serves
+  the dock's HTTP routes, and registers the `environment.mode` PUT handler for the night-mode button.
+- **`public/dock.js`, `dock.css`, `index.html`**: the dock itself, served as-is at `/@signalk/app-dock/`. Plain browser
+  JavaScript with **no build step**: edit and reload.
+- **`src/configpanel/`**: the React 19 config panel that the admin UI loads through Webpack Module Federation (keyword
+  `signalk-plugin-configurator`). `npm run build:config` writes `public/remoteEntry.js` and its chunks.
+
+`public/config.html` is an older standalone configurator that the schema description links to; the admin UI shows the
+React panel.
+
+## Rules to keep in mind
+
+- **Seed once, never rewrite.** `start()` seeds `DEFAULT_APPS` only when the saved `apps` is not an array. An app list
+  that already exists, even an empty one, is the user's and is never changed.
+- **The default app list lives in three places.** `DEFAULT_APPS` in `plugin/index.js`, `NO_ADMIN_DEFAULTS` in
+  `public/dock.js` (served to visitors the plugin's `/settings` refuses), and the welcome-tour text in
+  `public/index.html`. Change them together.
+- **`savePluginOptions` replaces the whole saved configuration.** Build every save from a complete configuration
+  (`running ? pluginSettings : savedSettings()`), never from a partial object.
+- **Routes must work while the plugin is stopped.** signalk-server registers the router of every loaded plugin, enabled
+  or not. A handler that needs the configuration reads `app.readPluginOptions()` when `running` is false.
+- **Access is opt-in per route.** Routes on `router` are admin-only. `router.access('readonly' | 'readwrite')`
+  (signalk-server 2.31 and later) opens a route to more users; feature-detect it (`typeof router.access === 'function'`)
+  so older servers keep working admin-only. `/config` stays admin-only on every server. When access changes, update the
+  access detection at the top of `dock.js` and the **Access** table in `README.md` with it.
+- **`/settings` is readable by every visitor with read access.** Never put credentials or anything secret in it; that
+  includes app URLs.
+- **Taps pass through.** The double-tap listener is passive, never calls `preventDefault()`, and there is no overlay
+  element. It attaches to the dock document and, recursively, to every same-origin iframe document, so apps that embed
+  other apps still open the dock.
+- **One iframe sandbox string.** `switchToApp()` and the tour's Plugin Config link in `dock.js` create iframes with the
+  same `sandbox` value; keep them identical. `allow-top-navigation-by-user-activation` is what lets a dock opened inside
+  a dock break out to the top window (the guard at the top of `dock.js`).
+- **Live config reload.** The dock polls the plugin every 5 s. A setting that changes how the dock is built belongs in
+  `STRUCTURAL_KEYS` in `dock.js` (the page reloads); app-list changes rebuild the dock in place.
+- **New settings touch four places:** the schema in `plugin/index.js`, `DEFAULTS` in `dock.js`, the config panel in
+  `src/configpanel/`, and the **Settings** table in `README.md`.
+- **Browser globals are declared.** ESLint lints `dock.js` as a classic script with an explicit globals list in
+  `eslint.config.js`; add a browser API there when `dock.js` starts using it.
+
+## Build output is committed
+
+`public/remoteEntry.js`, `public/main.js`, `public/540.js`, `public/805.js` and `public/540.js.LICENSE.txt` are Webpack
+output and are tracked in git. After changing `src/configpanel/`, run `npm run build:config` and commit the regenerated
+files with the source change. `prepublishOnly` rebuilds them at publish time. Prettier and ESLint skip them, and ESLint
+also skips `src/`.
+
+## Icons
+
+`public/app-icon.svg` is the source icon: the `signalk.appIcon` shown by the admin UI and the App Store, the favicon,
+and the dock's own logo. `public/app-icon-180.png` (apple-touch-icon) is generated from it and
+`public/app-icon-maskable.svg` is maintained by hand; see **Icon assets** in `README.md`.
+
+## Tests
+
+`npm test` runs `test/plugin.test.js` with `node:test` against a mock `app` (`createMockApp()`). Cover new routes,
+settings and seeding behaviour there. `dock.js` has no automated tests; check dock changes in a browser against a
+running server (see **Development** in `README.md`).
+
+## Workflow conventions
+
+This repo is maintained by Dirk Wahrheit.
+
+- Branch names use **hyphens**, never slashes.
+- Angular conventional commits: `<type>(<scope>): <subject>`. PR titles use the same format; the generated release
+  notes are built from them.
+- The PR title's type also picks its section in the release notes. `.github/workflows/label-by-title.yml` labels each
+  PR when it is opened or its title edited: `feat`/`perf` → `enhancement` (🚀 Features), `fix` → `bug` (🐛 Fixes),
+  `docs` → `documentation` (📖 Documentation), `build`/`ci`/`test`/`chore`/`refactor`/`style` → `skip-changelog`
+  (left out). Any other type lands under Other. A label set by hand stays until the title is next edited. Keep the
+  workflow and `.github/release.yml` naming the same labels.
+- One logical change per commit.
+- No `Co-Authored-By` lines. No "Generated with Claude Code" attribution.
+- Never commit directly to `main`. Every change goes through a PR.
+- PR descriptions: no checkboxes. "Tested" lists what actually ran, not what was planned.
+- No hand-written CHANGELOG; GitHub Releases carry generated notes.
+
+### Before opening a PR
+
+```bash
+npm run format          # prettier --write + eslint --fix
+npm run lint
+npm test
+npm run build:config    # only when src/configpanel/ changed; commit the output
+```
+
+CI (`.github/workflows/ci.yml`) calls signalk-server's shared `plugin-ci.yml`: install, `npm test`, plugin lifecycle
+and schema checks, npm-pack contents, and an App Store style `--ignore-scripts` install. It does **not** run Prettier or
+ESLint, so run them locally.
+
+### Releases
+
+Releases are cut by release-please. Every releasable push to `main` updates a standing release PR titled
+`chore(release): X.Y.Z` that bumps `version` in `package.json` and `package-lock.json`. Merging it creates the tag and
+the GitHub Release, and `.github/workflows/release-please.yml` then dispatches `release_on_tag.yml` on the tag, which
+publishes to npm with provenance (OIDC trusted publishing, no token).
+
+- **The version follows the commits:** `feat` → minor, `fix`, `perf` and `revert` → patch, `!` or a
+  `BREAKING CHANGE:` footer → major. A `Release-As: X.Y.Z` footer overrides it. Do not bump the version in an ordinary
+  PR.
+- **A push with nothing releasable leaves the release PR alone.** The `gate` job in `release-please.yml` decides what
+  counts; its comment lists the cases. Revert with a conventional `revert:` subject, since release-please ignores
+  GitHub's `Revert "…"`. Change the gate's last alternative together with `pull-request-title-pattern` in
+  `release-please-config.json`, or the release PR's merge never creates a tag.
+- **Merge the release PR once it lists your change.** release-please refreshes it a moment after each merge; a
+  release PR merged before that still ships the change (the tag is on top of it) but its notes leave it out.
+- **Pre-releases are cut by hand:** a `chore(release): X.Y.Z-beta.N` PR, then an annotated tag `vX.Y.Z-beta.N` pushed
+  on its merge commit. `release_on_tag.yml` creates their Release itself and publishes under the npm dist-tag `alpha`,
+  `beta` or `rc` that the tag contains.
+
+## File layout
+
+| Path                          | Purpose                                                                               |
+| ----------------------------- | ------------------------------------------------------------------------------------- |
+| `plugin/index.js`             | Plugin entry: schema, default-app seeding, routes, night-mode PUT handler.            |
+| `public/index.html`           | Dock page: idle screen, dock, backdrop, loading overlay, welcome tour.                |
+| `public/dock.js`              | Dock logic: access detection, config loading and polling, iframes, double-tap, dock.  |
+| `public/dock.css`             | Dock styling, magnification, positions.                                               |
+| `public/manifest.webmanifest` | PWA manifest for Add to Home Screen.                                                  |
+| `public/config.html`          | Older standalone configurator.                                                        |
+| `src/configpanel/`            | React config panel for the admin UI (Module Federation remote).                       |
+| `webpack.config.js`           | Builds `src/configpanel/` into `public/`; shares React as a singleton with the admin. |
+| `test/plugin.test.js`         | Plugin tests (`node:test`).                                                           |
+| `docs/screenshots/`           | App Store screenshots, listed in `package.json` under `signalk.screenshots`.          |

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalk/app-dock",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "macOS-style configurable app dock for switching between SignalK webapps on touch screens",
   "repository": {
     "url": "https://github.com/SignalK/app-dock"

package/public/app-icon.svg

@@ -5,10 +5,8 @@
       <stop offset="100%" stop-color="#2563eb"/>
     </linearGradient>
   </defs>
-  <!-- White base -->
-  <rect width="72" height="72" fill="#ffffff"/>
-  <!-- Background -->
-  <rect width="72" height="72" rx="16" fill="url(#bg)"/>
+  <!-- Background, full bleed: whatever displays the icon rounds the corners -->
+  <rect width="72" height="72" fill="url(#bg)"/>
   <!-- Dock pill -->
   <rect x="8" y="48" width="56" height="16" rx="8" fill="#ffffff" fill-opacity="0.25" stroke="#ffffff" stroke-opacity="0.4" stroke-width="0.5"/>
   <!-- Dock icons - 3 squares in the pill -->

package/release-please-config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "node",
+  "include-component-in-tag": false,
+  "changelog-type": "github",
+  "skip-changelog": true,
+  "pull-request-title-pattern": "chore(release): ${version}",
+  "packages": {
+    ".": {}
+  }
+}