@signalk/app-dock 1.1.0-beta.2 → 1.2.0-beta.1

package/README.md

@@ -13,6 +13,8 @@ A macOS-style app dock for switching between Signal K webapps on touch screens.
 - **Autostart** -- optionally load a default app immediately on open
 - **keep-alive or destroy** iframe lifecycle
 - **Night/day mode toggle** -- optional sun/moon button that flips `environment.mode` via a PUT handler
+- **Fullscreen toggle** -- optional button that hides browser chrome via the Fullscreen API; feature-detected, so hidden on devices without API support (notably iPadOS Safari -- use Add to Home Screen there)
+- **Installable as an app** -- ships a web app manifest and apple-touch-icon so iOS, Android, and desktop browsers can install the dock to the home screen and launch it in standalone mode (no browser chrome). Works over plain HTTP -- no SSL required
 - **Active dot indicator**, label tooltip, haptic feedback
 - **Embedded config panel** in the admin UI with webapp discovery, drag-to-reorder, and live preview
 
@@ -59,15 +61,30 @@ Open **Plugin Config > App Dock** in the admin UI. The embedded configurator pro
 
 ### Settings
 
-| Setting               | Default      | Description                                                                                      |
-| --------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
-| `position`            | `bottom`     | Dock edge: `bottom`, `top`, `left`, `right`                                                      |
-| `iframeMode`          | `keep-alive` | `keep-alive` loads each app once and hides/shows (faster, more RAM); `destroy` reloads each time |
-| `iconSize`            | `56`         | Base icon size in px                                                                             |
-| `magnification`       | `true`       | Enable macOS-style magnification effect                                                          |
-| `magnificationScale`  | `1.7`        | Max icon scale (1.0-2.5)                                                                         |
-| `showNightModeButton` | `true`       | Show sun/moon button in dock; PUT-writes `environment.mode`                                      |
-| `showExitButton`      | `false`      | Show X button that returns to the Signal K admin UI                                              |
+| Setting                | Default      | Description                                                                                      |
+| ---------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
+| `position`             | `bottom`     | Dock edge: `bottom`, `top`, `left`, `right`                                                      |
+| `iframeMode`           | `keep-alive` | `keep-alive` loads each app once and hides/shows (faster, more RAM); `destroy` reloads each time |
+| `iconSize`             | `56`         | Base icon size in px                                                                             |
+| `magnification`        | `true`       | Enable macOS-style magnification effect                                                          |
+| `magnificationScale`   | `1.7`        | Max icon scale (1.0-2.5)                                                                         |
+| `showNightModeButton`  | `true`       | Show sun/moon button in dock; PUT-writes `environment.mode`                                      |
+| `showFullscreenButton` | `false`      | Show fullscreen toggle in dock; hidden automatically where the Fullscreen API is unavailable     |
+| `showExitButton`       | `false`      | Show X button that returns to the Signal K admin UI                                              |
+
+## Access
+
+With security enabled, what the dock offers depends on the visitor:
+
+| Visitor                                        | Apps shown | Night-mode toggle | "Don't show again" in the tour |
+| ---------------------------------------------- | ---------- | ----------------- | ------------------------------ |
+| admin                                          | configured | yes               | yes                            |
+| readwrite user                                 | configured | yes               | yes                            |
+| readonly user                                  | configured | no                | no                             |
+| not signed in, server allows read-only access  | configured | no                | no                             |
+| not signed in, server refuses read-only access | built-in   | no                | no                             |
+
+Visitors who are not admins reach the plugin's routes through `router.access()`, which signalk-server 2.31 added. On older servers they get the built-in list, the same apps the plugin seeds on its first start. Only admins can open **Plugin Config**, and "Don't show again" hides the tour for every visitor. Everyone who gets the configured apps can also read their URLs from the plugin's `/settings`, so keep credentials out of app URLs.
 
 ## Development
 

package/package.json

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

package/plugin/index.js

@@ -12,9 +12,9 @@ const DEFAULT_APPS = [
   {
     enabled: true,
     autostart: false,
-    url: '/@mxtommy/kip/',
-    label: 'KIP',
-    icon: '/@mxtommy/kip/assets/icon-72x72.png',
+    url: '/@halos-org/skip/',
+    label: 'Skip',
+    icon: '/@halos-org/skip/assets/icon-72x72.png',
     color: ''
   },
   {
@@ -30,6 +30,26 @@ const DEFAULT_APPS = [
 module.exports = (app) => {
   let pluginSettings = {}
   let resolvedApps = []
+  let running = false
+
+  function resolveApps(settings) {
+    return (Array.isArray(settings.apps) ? settings.apps : [])
+      .filter((a) => a.enabled !== false)
+      .map((a) => ({
+        label: a.label || a.url,
+        url: a.url,
+        icon: a.icon || null,
+        color: a.color || null,
+        autostart: a.autostart || false
+      }))
+  }
+
+  // The configuration as saved, the one /config serves. While the plugin is
+  // not running, pluginSettings is empty (never started) or holds what the
+  // last start() got, which a later save may have replaced.
+  function savedSettings() {
+    return app.readPluginOptions().configuration || {}
+  }
 
   function getWebapps() {
     return (app.webapps || [])
@@ -83,26 +103,27 @@ module.exports = (app) => {
         )
       }
 
-      resolvedApps = (settings.apps || [])
-        .filter((a) => a.enabled !== false)
-        .map((a) => ({
-          label: a.label || a.url,
-          url: a.url,
-          icon: a.icon || null,
-          color: a.color || null,
-          autostart: a.autostart || false
-        }))
+      resolvedApps = resolveApps(settings)
+      running = true
 
       app.debug('App Dock: resolved %d apps: %s', resolvedApps.length, resolvedApps.map((a) => a.label).join(', '))
     },
 
-    stop() {},
+    stop() {
+      running = false
+    },
 
     registerWithRouter(router) {
-      router.get('/settings', (req, res) => {
+      // Routes registered on the router itself are admin-only. signalk-server
+      // 2.31 and later add router.access(), which opens a route to readonly or
+      // readwrite users; on older servers every route stays admin-only.
+      const openTo = (level) => (typeof router.access === 'function' ? router.access(level) : router)
+
+      openTo('readonly').get('/settings', (req, res) => {
+        const settings = running ? pluginSettings : savedSettings()
         res.json({
-          ...pluginSettings,
-          apps: resolvedApps
+          ...settings,
+          apps: running ? resolvedApps : resolveApps(settings)
         })
       })
 
@@ -110,13 +131,15 @@ module.exports = (app) => {
         res.json(getWebapps())
       })
 
-      router.get('/mode', (req, res) => {
+      openTo('readonly').get('/mode', (req, res) => {
         const current = app.getSelfPath('environment.mode')
         res.json({ value: (current && current.value) || 'day' })
       })
 
-      router.post('/dismiss-tour', (req, res) => {
-        const updated = { ...pluginSettings, tourDismissed: true }
+      openTo('readwrite').post('/dismiss-tour', (req, res) => {
+        // savePluginOptions replaces the whole saved configuration, so the
+        // update starts from a complete one.
+        const updated = { ...(running ? pluginSettings : savedSettings()), tourDismissed: true }
         app.savePluginOptions(updated, (err) => {
           if (err) {
             app.error('App Dock: failed to save tourDismissed: ' + err.message)

package/public/dock.js

@@ -41,11 +41,12 @@
     apps: []
   }
 
-  // Fallback app list used when we can't read server config — i.e. the
-  // visitor has no admin access (/plugins/* requires admin in signalk-server,
-  // so anonymous, readonly and readwrite users all 401/403). Mirrors the
-  // server-side DEFAULT_APPS in plugin/index.js so the demo at
-  // demo.signalk.org behaves sensibly for non-admin visitors.
+  // Fallback app list for a visitor who is not an admin when the plugin's
+  // /settings refuses them. signalk-server before 2.31 keeps every plugin
+  // route admin-only, and any version refuses a visitor who is not signed in
+  // unless it allows read-only access. Mirrors the server-side DEFAULT_APPS
+  // in plugin/index.js so the demo at demo.signalk.org behaves sensibly for
+  // non-admin visitors.
   const NO_ADMIN_DEFAULTS = {
     showNightModeButton: true,
     apps: [
@@ -60,9 +61,9 @@
       {
         enabled: true,
         autostart: false,
-        url: '/@mxtommy/kip/',
-        label: 'KIP',
-        icon: '/@mxtommy/kip/assets/icon-72x72.png',
+        url: '/@halos-org/skip/',
+        label: 'Skip',
+        icon: '/@halos-org/skip/assets/icon-72x72.png',
         color: ''
       },
       {
@@ -76,24 +77,26 @@
     ]
   }
 
-  // ─── Detect admin access ────────────────────────────────────────────────────
-  // /skServer/loginStatus is public even when allow_readonly is on and
-  // /plugins/* is admin-gated. Only logged-in admins can read plugin
-  // settings — anonymous, readonly and readwrite users all 401/403. We set
-  // noAdminAccess accordingly and take the fallback path for all of them.
+  // ─── Detect access level ────────────────────────────────────────────────────
+  // /skServer/loginStatus is public. Only an admin can read the plugin's
+  // /config (signalk-server keeps it admin-only), so every other visitor has
+  // noAdminAccess and reads the dock from /settings instead. canWrite marks
+  // the users signalk-server lets write: admins and readwrite users.
   // When authenticationRequired is false (no-auth / dummy-security setups),
   // /plugins/* is reachable without a login, so treat the visitor as
   // full-access instead of falling through to the hardcoded fallback list.
   // Try /skServer/loginStatus first, fall back to the legacy /loginStatus.
   let noAdminAccess = false
+  let canWrite = true
   for (const url of ['/skServer/loginStatus', '/loginStatus']) {
     try {
       const res = await fetch(url)
       if (res.ok) {
         const data = await res.json()
         const authOff = data.authenticationRequired === false
-        const isAdmin = data.status === 'loggedIn' && data.userLevel === 'admin'
-        noAdminAccess = !authOff && !isAdmin
+        const level = data.status === 'loggedIn' ? data.userLevel : undefined
+        noAdminAccess = !authOff && level !== 'admin'
+        canWrite = authOff || level === 'admin' || level === 'readwrite'
         break
       }
     } catch {
@@ -101,10 +104,31 @@
     }
   }
 
+  // The dock as the plugin serves it on /settings: the plugin configuration
+  // with the enabled apps resolved. The plugin opens this route to every user
+  // with read access on signalk-server 2.31 and later. Null when the route
+  // refuses this visitor or answers without an app list.
+  async function fetchSharedConfig() {
+    try {
+      const res = await fetch('/plugins/signalk-app-dock/settings')
+      if (!res.ok) return null
+      const data = await res.json()
+      return Array.isArray(data.apps) ? { ...DEFAULTS, ...data } : null
+    } catch {
+      return null
+    }
+  }
+
   // ─── Load config from plugin endpoints ───────────────────────────────────────
   let cfg = { ...DEFAULTS }
+  // Whether the dock keeps calling the plugin's routes after loading: always
+  // for an admin, and for anyone else once /settings has served them the dock
+  // (the plugin opens /settings and /mode to the same users).
+  let pluginReachable = !noAdminAccess
   if (noAdminAccess) {
-    cfg = { ...DEFAULTS, ...NO_ADMIN_DEFAULTS }
+    const shared = await fetchSharedConfig()
+    pluginReachable = shared !== null
+    cfg = shared || { ...DEFAULTS, ...NO_ADMIN_DEFAULTS }
   } else {
     try {
       const [configRes, settingsRes] = await Promise.all([
@@ -147,9 +171,13 @@
 
   // ─── Night mode state ────────────────────────────────────────────────────────
   let currentMode = 'day'
+  // The button reads the mode from the plugin's /mode and switches it with a
+  // PUT that signalk-server accepts from admins and readwrite users only, so
+  // only visitors who can do both get the button.
+  const nightModeUsable = pluginReachable && canWrite
 
   async function fetchCurrentMode() {
-    if (noAdminAccess) return
+    if (!pluginReachable) return
     try {
       const res = await fetch('/plugins/signalk-app-dock/mode')
       if (res.ok) {
@@ -171,7 +199,7 @@
   }
 
   async function toggleNightMode() {
-    if (noAdminAccess) return
+    if (!nightModeUsable) return
     await fetchCurrentMode()
     const newMode = currentMode === 'night' ? 'day' : 'night'
     try {
@@ -338,7 +366,8 @@
     const radius = Math.round(sz * 0.25) + 'px'
     const lblCls = labelClass()
 
-    if (cfg.showNightModeButton) {
+    const showNightMode = cfg.showNightModeButton && nightModeUsable
+    if (showNightMode) {
       $dockInner.appendChild(createUtilityItem('dock-item-nightmode', '\u2600\uFE0F', 'Night mode', toggleNightMode))
     }
 
@@ -346,7 +375,7 @@
       $dockInner.appendChild(createUtilityItem('dock-item-fullscreen', '\u26F6', 'Fullscreen', toggleFullscreen))
     }
 
-    if (cfg.showNightModeButton || (cfg.showFullscreenButton && fullscreenSupported())) {
+    if (showNightMode || (cfg.showFullscreenButton && fullscreenSupported())) {
       $dockInner.appendChild(createSeparator())
     }
 
@@ -587,8 +616,10 @@
 
     hideIdleHint()
 
-    document.querySelectorAll('.dock-item').forEach((el, i) => {
-      el.classList.toggle('active', i === index)
+    // The night-mode and fullscreen buttons are .dock-items too; only app
+    // items carry a data-index.
+    document.querySelectorAll('.dock-item').forEach((el) => {
+      el.classList.toggle('active', el.dataset.index === String(index))
     })
 
     const alreadyLoaded = !!iframes[app.url]
@@ -767,7 +798,7 @@
   // ─── Init ────────────────────────────────────────────────────────────────────
   buildDock()
 
-  if (cfg.showNightModeButton && !noAdminAccess) {
+  if (cfg.showNightModeButton && nightModeUsable) {
     fetchCurrentMode()
     setInterval(fetchCurrentMode, 5000)
   }
@@ -791,21 +822,25 @@
 
   async function refreshConfig() {
     try {
-      const [configRes, settingsRes] = await Promise.all([
-        fetch('/plugins/signalk-app-dock/config'),
-        fetch('/plugins/signalk-app-dock/settings')
-      ])
       const prev = cfg
       let next = cfg
-      if (configRes.ok) {
-        const data = await configRes.json()
-        const pluginCfg = data.configuration || data
-        next = { ...DEFAULTS, ...pluginCfg, apps: prev.apps }
-      }
-      if (settingsRes.ok) {
-        const data = await settingsRes.json()
-        if (Array.isArray(data.apps) && data.apps.length > 0) {
-          next = { ...next, apps: data.apps }
+      if (noAdminAccess) {
+        next = (await fetchSharedConfig()) || prev
+      } else {
+        const [configRes, settingsRes] = await Promise.all([
+          fetch('/plugins/signalk-app-dock/config'),
+          fetch('/plugins/signalk-app-dock/settings')
+        ])
+        if (configRes.ok) {
+          const data = await configRes.json()
+          const pluginCfg = data.configuration || data
+          next = { ...DEFAULTS, ...pluginCfg, apps: prev.apps }
+        }
+        if (settingsRes.ok) {
+          const data = await settingsRes.json()
+          if (Array.isArray(data.apps) && data.apps.length > 0) {
+            next = { ...next, apps: data.apps }
+          }
         }
       }
       const structuralChanged = STRUCTURAL_KEYS.some((k) => prev[k] !== next[k])
@@ -824,7 +859,7 @@
     }
   }
 
-  if (!noAdminAccess) setInterval(refreshConfig, 5000)
+  if (pluginReachable) setInterval(refreshConfig, 5000)
 
   // ─── Welcome tour ────────────────────────────────────────────────────────────
   const $tourOverlay = document.getElementById('tour-overlay')
@@ -843,11 +878,13 @@
 
   if ($tourGotIt) $tourGotIt.addEventListener('click', hideTour)
 
-  // Anonymous visitors can't persist tour dismissal server-side (POST
-  // /dismiss-tour requires auth), so we drop the "Don't show again" button
-  // rather than advertise a setting we can't honour. The tour reappears on
-  // next visit — correct semantics for a read-only visitor.
-  if (noAdminAccess) {
+  // "Don't show again" POSTs /dismiss-tour, which saves tourDismissed in the
+  // plugin configuration, so it applies to every user. The plugin opens that
+  // route to readwrite users. Everyone else who is not an admin, and anyone
+  // /settings did not serve the dock to, gets no button rather than one that
+  // advertises a setting we can't honour. The tour reappears on their next
+  // visit.
+  if (!pluginReachable || !canWrite) {
     if ($tourDismiss) $tourDismiss.remove()
     document.getElementById('tour-buttons')?.style.setProperty('justify-content', 'center')
   } else if ($tourDismiss) {

package/public/index.html

@@ -52,7 +52,7 @@
             <strong>Double-tap anywhere</strong> on the screen to open the dock, then tap an icon to launch that app.
           </p>
           <p>
-            Freeboard-SK is loading in the background and KIP is one tap away. Customize the apps, dock position, and
+            Freeboard-SK is loading in the background and Skip is one tap away. Customize the apps, dock position, and
             more in
             <a id="tour-link" href="#">Plugin Config</a>.
           </p>

package/test/plugin.test.js

@@ -13,6 +13,7 @@ function createMockApp(webapps = []) {
     debug: () => {},
     error: () => {},
     savePluginOptions: (opts, cb) => cb(null),
+    readPluginOptions: () => ({}),
     registerPutHandler: () => {},
     handleMessage: () => {},
     getSelfPath: () => null
@@ -220,6 +221,85 @@ describe('settings endpoint', () => {
     }
     routes['/settings']({}, res)
   })
+
+  it('serves the saved configuration before the plugin has started', (t, done) => {
+    const app = createMockApp()
+    app.readPluginOptions = () => ({
+      enabled: false,
+      configuration: {
+        position: 'right',
+        apps: [
+          { url: '/a/', label: 'A', enabled: true },
+          { url: '/b/', label: 'B', enabled: false }
+        ]
+      }
+    })
+    const plugin = pluginFactory(app)
+
+    const routes = {}
+    plugin.registerWithRouter({
+      get: (path, handler) => {
+        routes[path] = handler
+      },
+      post: () => {}
+    })
+
+    const res = {
+      json: (data) => {
+        assert.equal(data.position, 'right')
+        assert.deepEqual(data.apps, [{ label: 'A', url: '/a/', icon: null, color: null, autostart: false }])
+        done()
+      }
+    }
+    routes['/settings']({}, res)
+  })
+
+  it('serves no apps when the saved apps value is not an array', (t, done) => {
+    const app = createMockApp()
+    app.readPluginOptions = () => ({ enabled: false, configuration: { apps: {} } })
+    const plugin = pluginFactory(app)
+
+    const routes = {}
+    plugin.registerWithRouter({
+      get: (path, handler) => {
+        routes[path] = handler
+      },
+      post: () => {}
+    })
+
+    const res = {
+      json: (data) => {
+        assert.deepEqual(data.apps, [])
+        done()
+      }
+    }
+    routes['/settings']({}, res)
+  })
+
+  it('serves the saved configuration after stop()', (t, done) => {
+    const app = createMockApp()
+    app.readPluginOptions = () => ({ enabled: false, configuration: { position: 'top', apps: [] } })
+    const plugin = pluginFactory(app)
+    plugin.start({ position: 'left', apps: [{ url: '/a/', label: 'A' }] })
+    plugin.stop()
+
+    const routes = {}
+    plugin.registerWithRouter({
+      get: (path, handler) => {
+        routes[path] = handler
+      },
+      post: () => {}
+    })
+
+    const res = {
+      json: (data) => {
+        assert.equal(data.position, 'top')
+        assert.deepEqual(data.apps, [])
+        done()
+      }
+    }
+    routes['/settings']({}, res)
+  })
 })
 
 describe('default apps seeding', () => {
@@ -237,7 +317,7 @@ describe('default apps seeding', () => {
     assert.ok(savedOptions)
     assert.equal(savedOptions.apps[0].url, '/@signalk/freeboard-sk/')
     assert.equal(savedOptions.apps[0].autostart, true)
-    assert.equal(savedOptions.apps[1].url, '/@mxtommy/kip/')
+    assert.equal(savedOptions.apps[1].url, '/@halos-org/skip/')
     assert.equal(savedOptions.apps[1].autostart, false)
     assert.equal(savedOptions.apps[2].url, '/admin/')
     assert.equal(savedOptions.apps[2].label, 'Settings')
@@ -445,6 +525,35 @@ describe('dismiss-tour endpoint', () => {
     }
     routes.post['/dismiss-tour']({}, res)
   })
+
+  it('keeps the saved configuration when the plugin is not running', (t, done) => {
+    const app = createMockApp()
+    const apps = [{ url: '/a/', label: 'A', enabled: true }]
+    app.readPluginOptions = () => ({ enabled: false, configuration: { position: 'right', apps } })
+    let saved = null
+    app.savePluginOptions = (opts, cb) => {
+      saved = opts
+      cb(null)
+    }
+    const plugin = pluginFactory(app)
+
+    const routes = {}
+    plugin.registerWithRouter({
+      get: () => {},
+      post: (path, handler) => {
+        routes[path] = handler
+      }
+    })
+
+    const res = {
+      json: (data) => {
+        assert.equal(data.tourDismissed, true)
+        assert.deepEqual(saved, { position: 'right', apps, tourDismissed: true })
+        done()
+      }
+    }
+    routes['/dismiss-tour']({}, res)
+  })
 })
 
 describe('mode endpoint', () => {
@@ -495,6 +604,51 @@ describe('mode endpoint', () => {
   })
 })
 
+describe('route access', () => {
+  // Records each route with the level it is registered at: 'admin' for a
+  // route registered on the router itself, the access() level otherwise.
+  function recordingRouter({ withAccess }) {
+    const levels = {}
+    const registrar = (level) => ({
+      get: (path) => {
+        levels[`GET ${path}`] = level
+      },
+      post: (path) => {
+        levels[`POST ${path}`] = level
+      }
+    })
+    const router = registrar('admin')
+    if (withAccess) router.access = registrar
+    return { router, levels }
+  }
+
+  it('opens /settings and /mode to readonly users and /dismiss-tour to readwrite users', () => {
+    const plugin = pluginFactory(createMockApp())
+    const { router, levels } = recordingRouter({ withAccess: true })
+    plugin.registerWithRouter(router)
+
+    assert.deepEqual(levels, {
+      'GET /settings': 'readonly',
+      'GET /webapps': 'admin',
+      'GET /mode': 'readonly',
+      'POST /dismiss-tour': 'readwrite'
+    })
+  })
+
+  it('registers every route on the router itself when it has no access()', () => {
+    const plugin = pluginFactory(createMockApp())
+    const { router, levels } = recordingRouter({ withAccess: false })
+    plugin.registerWithRouter(router)
+
+    assert.deepEqual(levels, {
+      'GET /settings': 'admin',
+      'GET /webapps': 'admin',
+      'GET /mode': 'admin',
+      'POST /dismiss-tour': 'admin'
+    })
+  })
+})
+
 describe('public files', () => {
   const publicDir = path.join(__dirname, '..', 'public')