Dashboard Studio 2.0.0: Admin, Builder and Dashboard screens, roles, Haven

- Home Assistant administrators are admins: Dashboard, Builder and Admin screens
- Everyone else only sees the dashboards an admin chose, always in kiosk mode;
  the server enforces it (saving, people, devices, history are admin-only, and
  the websocket only allows reading states and controlling devices)
- Admin screen: dashboards, people and what each sees (with preview), devices,
  messages to the screens, the Haven app, activity, about
- Haven: new Android app (haven/) that only shows dashboards; replaces the
  Dashboard Studio Android app and signs in through Home Assistant's page
- Screens pick up dashboard and access changes within a minute
- Version history records who made each change; panel visible to all users

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

dashboard_studio/DOCS.md

@@ -1,16 +1,51 @@
 # Dashboard Studio
 
-A drag-and-drop dashboard builder that lives in its own sidebar tab.
+A drag-and-drop dashboard builder that lives in its own sidebar tab, with **Haven**, an Android app that shows the dashboards to everyone in your home.
 
-## Using it
+## Admins and everyone else
+
+Dashboard Studio follows Home Assistant's own **Administrator** setting (Settings, People):
+
+- **Admins** (Home Assistant administrators) get three screens, switched at the top right:
+  - **Dashboard:** use your dashboards.
+  - **Builder:** build and change them.
+  - **Admin:** manage the dashboards, choose who sees what, name devices, set up Haven and see who changed what.
+- **Everyone else** only sees the dashboards an admin chose for them, full screen in kiosk mode, on every device. They can't change anything. Tapping the kiosk corner five times switches between their dashboards (and turns guest mode on or off); there's no way out of kiosk mode. Someone with no dashboard chosen yet sees a short note saying so, which updates by itself once an admin picks one.
+
+This is enforced by Dashboard Studio itself, not just hidden: only administrators can save, see the people and devices or the history, and the connection to Home Assistant only lets everyone else read states and control devices, as Home Assistant itself would. Home Assistant's settings, other apps and its own dashboards stay out of reach.
+
+Everyone with a login sees Dashboard Studio in the Home Assistant sidebar.
+
+## The Admin screen
+
+- **Dashboards:** every dashboard as a card, with who sees it. **Open** shows it, **Build** opens it in the builder, and **⋯** renames, duplicates, shows the version history, shares, exports or deletes it. At the top: a new dashboard, one made from your devices, importing a file, and importing one of Home Assistant's own dashboards.
+- **People:** everyone with a Home Assistant login. Admins see everything. For everyone else, choose **All dashboards** or **Only these** and tick the dashboards, plus the one that **Opens first**. **Everyone else** at the top sets this for people without their own choice, and for anyone added to Home Assistant later. **Preview** shows the dashboards exactly as that person gets them; **Stop preview** brings you back.
+- **Devices:** every phone, tablet and computer that opened Dashboard Studio, with who used it, whether it was Haven or a browser, and when. Name a device, give it its own dashboard (that comes before the person's choice, handy for a wall tablet), have admins start it in kiosk mode, or forget it. **Send a message to the screens** puts a full-screen message on all screens in kiosk mode, or on one named device.
+- **Haven app:** a QR code to download Haven on a phone, the address to enter in it, and how signing in works.
+- **Activity:** who changed which dashboard, and when, with a shortcut to its versions.
+- **About:** the version, what's new and the source code.
+
+Screens pick up what an admin changes, a dashboard or who sees what, within a minute, without reloading.
+
+## Haven, the Android app
+
+Haven shows the dashboards and nothing else: no builder and no Admin screen, for admins too.
+
+1. On the phone, scan the QR code under **Admin → Haven app** (or tap **Download Haven** on the phone itself), open the file and allow installing apps from that source when Android asks (once).
+2. Open Haven and enter the address you use for Home Assistant. On the phone itself, **Open in Haven** fills it in.
+3. Sign in with your own Home Assistant login, once.
+
+From then on Haven opens straight on your dashboard, full screen with its own icon, and keeps you signed in. It works with plain http addresses too. Kiosk mode keeps the screen on and hides Android's bars. To connect to another Home Assistant: tap the phone button in the top bar (admins) or the kiosk corner five times (everyone else), then **Change address**. Haven needs Android 7 or newer. The earlier *Dashboard Studio* Android app is replaced by Haven; you can uninstall it.
+
+## Building
 
 1. Open **Dashboard Studio** in the Home Assistant sidebar.
-2. Press **Edit**. Pick widgets from the left panel, drag them anywhere on the grid, and resize from the bottom-right corner. Other widgets move out of the way.
+2. Switch to **Builder**. Pick widgets from the left panel, drag them anywhere on the grid, and resize from the bottom-right corner. Other widgets move out of the way.
 3. Set up the selected widget in the right panel: entity, labels, icon, thresholds, colors.
 4. With nothing selected, the right panel holds dashboard settings: theme, tile style, colors, background image, grid and kiosk options.
-5. Press **Done**. Changes save automatically.
+5. Switch back to **Dashboard**. Changes save automatically.
 
-Keyboard shortcuts in edit mode: arrow keys move, Shift+arrows resize, ⌘D or Ctrl+D duplicates, Delete removes, ⌘Z or Ctrl+Z undoes, and ⇧⌘Z or Ctrl+Shift+Z redoes.
+Keyboard shortcuts in the builder: arrow keys move, Shift+arrows resize, ⌘D or Ctrl+D duplicates, Delete removes, ⌘Z or Ctrl+Z undoes, and ⇧⌘Z or Ctrl+Shift+Z redoes.
 
 More editing tools:
 
@@ -68,7 +103,7 @@ Pick a weather entity in the clock's settings to show the current conditions and
 
 ### Horizontal scroll and swipe cards
 
-These cards hold other cards. Select one in edit mode, pick a card type under **Cards** and press **Add**. The new card opens straight away so you can set it up; **←** takes you back. Use the arrows to reorder cards, and open a card to change or remove it.
+These cards hold other cards. Select one in the builder, pick a card type under **Cards** and press **Add**. The new card opens straight away so you can set it up; **←** takes you back. Use the arrows to reorder cards, and open a card to change or remove it.
 
 - **Horizontal scroll** puts its cards in a row you can scroll sideways, by touch, trackpad or the arrow buttons that appear on hover. Set the card width in pixels, or as the number of cards visible at once (2.5 lets half a card peek out, so it's clear the row scrolls). A single card can get its own width in its settings. Add an optional title. The row keeps its scroll position when something inside it changes.
 - **Swipe cards** shows one card at a time, filling the whole card. Swipe with a finger or drag with the mouse: the card follows along, resists at the first and last card, and a quick flick is enough. The left and right arrow keys work too. Small dots appear at the bottom while you swipe or hover, and hide again after a few seconds; tap one to jump to that card. It can also move to the next card automatically every few seconds. Touching it pauses that for 20 seconds, and it stops completely when the system's "reduce motion" setting is on.
@@ -206,35 +241,32 @@ The card follows the style of the Tesla app, with two designs:
 
 ## Conditional widgets
 
-Any widget can be shown only under certain conditions. Select it in edit mode, then under **Visibility** choose **Add condition**. Pick an entity, a comparison (*is*, *is not*, *above*, *below*) and a value. For example: *switch.coffee_machine is on*, or *sensor.washer_power above 5*. With several conditions, choose whether all of them or just one must be true.
+Any widget can be shown only under certain conditions. Select it in the builder, then under **Visibility** choose **Add condition**. Pick an entity, a comparison (*is*, *is not*, *above*, *below*) and a value. For example: *switch.coffee_machine is on*, or *sensor.washer_power above 5*. With several conditions, choose whether all of them or just one must be true.
 
-In edit mode, hidden widgets stay visible but faded, with a **Hidden now** label, so you can still edit them. On the dashboard they disappear, and rows that only held hidden widgets close up so no gaps are left. Changes happen live as the entities change.
+In the builder, hidden widgets stay visible but faded, with a **Hidden now** label, so you can still edit them. On the dashboard they disappear, and rows that only held hidden widgets close up so no gaps are left. Changes happen live as the entities change.
 
 ## Phone dashboards
 
 Turn on **Designed for phones** under **Grid** in the dashboard settings. The dashboard switches to a 4-column layout that you design at phone width, so what you see while editing is what the phone shows. Existing widgets are converted: small tiles become half width, larger cards full width, and nothing overlaps. Turning it off converts back to 12 columns.
 
-On a phone, such a dashboard fills the whole screen, without the top bar with the dashboard picker and **Edit**. To bring the bar back, tap the round **⋯** button in the top right corner (or touch and hold an empty spot); it hides again after 15 seconds or when you tap **⋯** again. On a computer, a phone dashboard shows as a phone-width column. Dashboards that aren't designed for phones keep reflowing into two columns on phones, with the top bar. With the phone on its side, a phone dashboard shows two columns of its layout next to each other.
+On a phone, such a dashboard fills the whole screen, without the top bar with the dashboard picker and the screen switcher. To bring the bar back, tap the round **⋯** button in the top right corner (or touch and hold an empty spot); it hides again after 15 seconds or when you tap **⋯** again. On a computer, a phone dashboard shows as a phone-width column. Dashboards that aren't designed for phones keep reflowing into two columns on phones, with the top bar. With the phone on its side, a phone dashboard shows two columns of its layout next to each other.
 
 ### On phones
 
-- **Install as an app:** tap the phone button in the top bar (or **⋯ → Install as an app…** in edit mode). What it offers depends on the phone:
-  - **Android:** the Dashboard Studio app. Tap **Download the app**, open the downloaded file and allow installing apps from that source when Android asks (once). Then come back and tap **Open in the app**, or open the app and enter the address you use for Home Assistant. Sign in to Home Assistant once in the app; after that it opens straight on Dashboard Studio, full screen with its own icon and the dashboard's colors in the status bar, and keeps you signed in. Kiosk mode keeps the screen on and hides Android's bars. To connect to another Home Assistant, choose **Install as an app → Change address** in the app. The app finds Dashboard Studio by itself if you sign in as an administrator; other people can tap **Open in the app** on their phone instead.
-  - **From the browser** (Android and computers): the browser can also install Dashboard Studio as a web app, but only when Home Assistant is opened over **https** (for example Home Assistant Cloud or your own certificate). Home Assistant's own page can't be installed, so open Dashboard Studio in its own tab first (the dialog has a button for it).
-  - **iPhone and iPad:** apps on the home screen get their own storage there, without Home Assistant's sign-in, so they can't open an app that runs inside Home Assistant. Use Dashboard Studio from the sidebar in the Home Assistant app.
-- **Shortcuts:** tick **Shortcut on the app icon** in the settings of a button, tile, light, thermostat or garage card. When Dashboard Studio is installed from the browser on Android, long-press its icon to run one straight away (up to four shortcuts; the Android app and iPhones don't support this).
+- **Install as an app:** on Android, use **Haven** (see above). The phone button in the top bar explains the other options: browsers can install Dashboard Studio as a web app when Home Assistant is opened over **https** (open Dashboard Studio in its own tab first); on iPhone and iPad, apps on the home screen can't use Home Assistant's sign-in, so use the sidebar in the Home Assistant app.
+- **Shortcuts:** tick **Shortcut on the app icon** in the settings of a button, tile, light, thermostat or garage card. When Dashboard Studio is installed from the browser on Android, long-press its icon to run one straight away (up to four shortcuts; Haven and iPhones don't support this).
 - **Offline:** each device keeps the last known states of its dashboard. When the connection drops, the dashboard keeps showing them with a small note saying from when, and catches up when it reconnects.
 - **Swipe** left or right over the dashboard to go to the next or previous tab (not over cards that swipe or scroll themselves).
 - **Pull down** at the top of the dashboard to reload every state.
 - **Popups** open as sheets from the bottom; drag one down to close it.
 - **Vibration:** buttons, switches and sliders give a short tick on phones that support it (not iPhones). Turn this off under **This device**. Wall tablets can play a soft click instead: turn on **A soft click when something is pressed** in the **Kiosk** settings.
 - **Show on:** under **Visibility**, a widget can be shown on all screens, only on phones, or only on larger screens.
-- **Editing on the phone:** **Edit** works on a phone too. The bar at the bottom opens the widget list (**Add**) and the settings as sheets. Tap a widget to select it, then drag it or its corner; tap it again for its settings.
+- **Building on the phone:** the **Builder** works on a phone too. The bar at the bottom opens the widget list (**Add**) and the settings as sheets. Tap a widget to select it, then drag it or its corner; tap it again for its settings.
 - **Away from home:** in the **Tabs** settings, **When you're away from home, open** picks a tab, such as cameras, the garage or the alarm, that opens while you're away, and the dashboard goes back when you're home. It follows the person signed in on the device, or a person you choose. Not used in kiosk mode.
 
 ## Tabs and side menu
 
-A dashboard can have several tabs, each with its own widgets, for example *Overview*, *Household* and *Cameras*. To set them up, deselect all widgets in edit mode and use the **Tabs** section of the dashboard settings:
+A dashboard can have several tabs, each with its own widgets, for example *Overview*, *Household* and *Cameras*. To set them up, deselect all widgets in the builder and use the **Tabs** section of the dashboard settings:
 
 - **Add tab** creates a tab and turns on the menu.
 - Each tab has a name and an icon (an icon name or an emoji). Use the arrows to reorder tabs and the bin to delete one; ⌘Z undoes this.
@@ -287,30 +319,24 @@ Dashboard Studio is available in English and Dutch (Nederlands). By default it f
 
 ## Several dashboards
 
-Use **＋** for a new dashboard. You can start empty, from your devices, or from a template that fills itself with your devices: *Wall tablet* (clock, weather, calendar, rooms and cameras), *Phone* (people, lights, climate and media in the phone layout), *Energy* (power flow, solar forecast, water and gas, graphs) or *Family* (who's home, calendar, shopping list, parcels and weather).
+Use **＋** (or **New dashboard** on the Admin screen) for a new dashboard. You can start empty, from your devices, or from a template that fills itself with your devices: *Wall tablet* (clock, weather, calendar, rooms and cameras), *Phone* (people, lights, climate and media in the phone layout), *Energy* (power flow, solar forecast, water and gas, graphs) or *Family* (who's home, calendar, shopping list, parcels and weather).
 
-The **⋯** menu (in edit mode) can rename, duplicate, export, import or delete a dashboard. Exported JSON files can be imported on another Home Assistant install.
+On the Admin screen, a dashboard's **⋯** renames, duplicates, exports or deletes it; **Import file** brings an exported one back. Exported JSON files can be imported on another Home Assistant install. In the builder, the **⋯** menu keeps what concerns the dashboard you're building: rename, devices not on a dashboard, version history, undo history, share and export.
 
-**Import from Home Assistant…** turns one of your existing Home Assistant dashboards into a new dashboard here, with a tab for each view. Entities, tile, button, light, thermostat, sensor, gauge, graph, weather, media, camera, calendar, to-do, alarm, area and markdown cards become matching widgets, and stacks and grids are taken apart; other cards are skipped and counted. The original stays as it is. Dashboards that Home Assistant generates itself (without cards of their own) can't be imported.
+**Import from Home Assistant** (on the Admin screen) turns one of your existing Home Assistant dashboards into a new dashboard here, with a tab for each view. Entities, tile, button, light, thermostat, sensor, gauge, graph, weather, media, camera, calendar, to-do, alarm, area and markdown cards become matching widgets, and stacks and grids are taken apart; other cards are skipped and counted. The original stays as it is. Dashboards that Home Assistant generates itself (without cards of their own) can't be imported.
 
 **Share…** shows a link and a QR code for the dashboard, optionally opening in kiosk mode. It opens on any device that is signed in to Home Assistant.
 
-**Version history…** in the **⋯** menu lists the earlier saves of the dashboard, up to 30, with the time and the number of widgets. Changes made within five minutes of each other count as one version. **Restore** brings a version back; ⌘Z undoes that.
+**Version history…** (in the builder's **⋯** menu, or a dashboard's **⋯** on the Admin screen) lists the earlier saves of the dashboard, up to 30, with the time and the number of widgets. Changes made within five minutes of each other count as one version. **Restore** brings a version back; ⌘Z undoes that.
 
 ## Which dashboard opens where
 
-Use **⋯ → Who sees which dashboard…** in edit mode to choose the dashboard that opens first:
-
-- **This device:** give the device a name, for example *Kitchen tablet*, and pick its dashboard. Tick **Kiosk** to have it start in kiosk mode.
-- **Other devices** you have named appear in the list too, so you can change them from anywhere.
-- **People:** pick a dashboard per Home Assistant user. People appear once they've opened Dashboard Studio, or when they have a person entity.
-
-A device's choice comes before a person's. Without either, the last dashboard used on that device opens. A link with `#view=…` or a shared link always wins. You can still switch dashboards at any time.
+The first dashboard to open on a device is, in this order: one from a link (`#view=…` or a shared link), the device's own dashboard (**Admin → Devices**), the person's **Opens first** (**Admin → People**), and otherwise the last one used on that device. People who aren't admins only ever get dashboards they may see, plus the one an admin gave their device.
 
 ## Version and updates
 
-The version you're running is shown at the bottom of the dashboard settings, under **About** (deselect all widgets in edit mode). **What's new** there shows the changelog, which is also on the app's **Changelog** tab in Home Assistant. After an update, a short message points you to it. After Home Assistant installs an update, screens that are open reload themselves within a few minutes, which is handy for wall tablets. While you're editing, you get a message instead, so nothing you're working on is interrupted.
+The version you're running is shown under **Admin → About**, and at the bottom of the dashboard settings in the builder. **What's new** there shows the changelog, which is also on the app's **Changelog** tab in Home Assistant. After an update, a short message points you to it. After Home Assistant installs an update, screens that are open reload themselves within a few minutes, which is handy for wall tablets. While you're editing, you get a message instead, so nothing you're working on is interrupted.
 
 ## Data
 
-Dashboards and presets are stored in the app's `/data/dashboards.json`, and their version history in `/data/history/`, so both are included in Home Assistant backups. Night mode, guest mode started with the button, vibration and the last known states are kept on each device.
+Dashboards, presets and who sees what are stored in the app's `/data/dashboards.json`, their version history (with who made each change) in `/data/history/`, and the devices that opened Dashboard Studio in `/data/devices.json`, so all of it is included in Home Assistant backups. Night mode, guest mode started with the button, vibration and the last known states are kept on each device.