houseplan-card/docs/USER-GUIDE.md

# House Plan — complete user guide

Current for **v1.64.0**. This guide describes the interface implemented by the
current source. [Русская версия](USER-GUIDE.ru.md).

House Plan installs two Lovelace cards together:

- `custom:houseplan-card` — the live plan, editors, state and actions;
- `custom:houseplan-space-card` — an inert rendering of one space with a link
  to the full plan.

Configuration, uploaded files and shared positions stay inside Home Assistant.
House Plan does not use a House Plan cloud service.

> **Input support.** View and kiosk are supported on phones, tablets and wall
> touch panels. Create and maintain a plan on a desktop browser with a mouse
> and keyboard. Touch editing is best effort: an operation may be awkward,
> limited or absent, but it must not corrupt data or trigger an accidental
> Home Assistant action. The authority is [TOUCH-SUPPORT.md](TOUCH-SUPPORT.md).

## Contents

1. [Data model and terms](#1-data-model-and-terms)
2. [Installation and access](#2-installation-and-access)
3. [Adding a card](#3-adding-a-card)
4. [Quick start](#4-quick-start)
5. [Interface modes](#5-interface-modes)
6. [Navigation, zoom and input](#6-navigation-zoom-and-input)
7. [Spaces](#7-spaces)
8. [Rooms and walls](#8-rooms-and-walls)
9. [Doors, windows, gates and locks](#9-doors-windows-gates-and-locks)
10. [Devices](#10-devices)
11. [Tap actions](#11-tap-actions)
12. [Device visual states](#12-device-visual-states)
13. [Room fills and light](#13-room-fills-and-light)
14. [Background editor](#14-background-editor)
15. [Sun background and window rays](#15-sun-background-and-window-rays)
16. [Robot vacuums](#16-robot-vacuums)
17. [Kiosk](#17-kiosk)
18. [Static space card](#18-static-space-card)
19. [Plan maintenance](#19-plan-maintenance)
20. [Storage, multiple cards and backups](#20-storage-multiple-cards-and-backups)
21. [Current limitations](#21-current-limitations)
22. [Troubleshooting](#22-troubleshooting)

<!-- docs-section: model -->

## 1. Data model and terms

Settings form a hierarchy. Global settings provide defaults; a space may
override them; a room may override its space; a marker may override its room.

| Level | Meaning | Stored data |
|---|---|---|
| Card | One dashboard instance | Initial space, language, icon size, value/LQI display, live state, kiosk and cycle |
| Global settings | Defaults for all spaces | Fill palette, background, Glow radius, north, sun, weather and icon rules |
| Space | Floor, yard, garage or building | Plan image, scale, rooms, walls, openings, decor and display settings |
| Room | A closed outline | Name, optional HA area, temperature/humidity source and local fill |
| Wall | A side of a room outline | Optional physical thickness and virtual spans on a shared boundary |
| Opening | Door, window or gate on a wall | Size, orientation, contact and optional lock |
| Marker | A device shown on the plan | HA binding, room, action, presentation, light role and attachments |
| Background item | Visual context | Line, shape, text, furniture or plan-image transform |

A room is the spatial unit that owns area and an optional HA area. A partition
or column affects the physical rendering and light but does not create a room.

<!-- docs-section: installation -->

## 2. Installation and access

### Requirements

| Component | Requirement |
|---|---|
| Home Assistant | 2024.6.0 or newer |
| Installation | Any installation that supports custom integrations |
| Browser | Web Components, SVG and Pointer Events |
| Editing permission | Administrators by default |

### HACS

1. Add `https://github.com/Matysh/houseplan-card` to HACS as a custom
   **Integration** repository.
2. Install House Plan and restart Home Assistant.
3. Open **Settings → Devices & services → Add integration → House Plan**.
4. Keep “administrators only” enabled unless other users must edit the plan.

The integration registers its Lovelace resource. With YAML-managed resources,
add:

```yaml
resources:
  - url: /houseplan_files/houseplan-card.js
    type: module
```

Do not use `/custom_components/houseplan/frontend/houseplan-card.js`; it is an
on-disk path, not the JavaScript URL served by Home Assistant.

### Manual installation

Copy the release folder to `config/custom_components/houseplan`, restart Home
Assistant, add the integration, then add the resource above only if Lovelace
resources are YAML-managed.

### Permissions

Every signed-in user can view the plan. Home Assistant permissions still govern
device service calls. With the default integration option, only administrators
can edit configuration or upload files. Plan optimization and its undo always
require an administrator.

## 3. Adding a card

Minimal configuration:

```yaml
type: custom:houseplan-card
title: House plan
```

| Field | Default | Purpose |
|---|---:|---|
| `title` | empty | Card title |
| `default_floor` | first/last opened | Initial space for this card |
| `language` | HA language | `auto`, `ru` or `en` |
| `icon_size` | `2.5` | Base marker size, 1–6% of plan width |
| `show_temperature` | `true` | Compact temperature and humidity values |
| `live_states` | `true` | Work/open/unavailable presentation and activity; alarms remain visible |
| `show_signal` | `true` | Base LQI display, overridable by a space |
| `kiosk` | `false` | Full plan without editors or header |
| `cycle` | `0` | Kiosk auto-cycle interval in seconds; `0` disables it |

The legacy card-level `tap_action` is ignored. Each marker owns its action.

<!-- docs-section: first-run -->

## 4. Quick start

Use this order for a first working room:

1. Add a space with **+**, or import Home Assistant floors.
2. Upload SVG/PNG/JPG/WebP, reuse an uploaded plan, or choose no image.
3. Set the real size of a grid cell. It controls wall, opening, furniture and
   area measurements.
4. In Plan choose **Walls**, draw the boundary, then click its first point to
   close the first room face.
5. Name the room and bind it to an HA area, or use **No area**.
6. Add wall thickness and openings if needed.
7. In Device, position auto-discovered markers and choose their actions.
8. In Background, align the plan image and add labels, lines or furniture.
9. Return to View and confirm live values and actions.

![Creating the first space with synthetic data](images/03-space-create.png)

![Closing a new wall chain on its first point](images/04-room-contour-close.png)

Do all plan creation on desktop. Phone, tablet and wall-panel View remain full
product surfaces after setup.

<!-- docs-section: modes -->

## 5. Interface modes

View is the state with no editor open. Close the active editor to return to it.

| Mode | Devices | Geometry | Background/openings |
|---|---|---|---|
| View | Live and actionable | Read-only; room hover shows summary | Visible according to space settings |
| Plan | Hidden | Rooms, walls, columns and openings editable | Openings always visible |
| Device | Draggable; click opens settings | Read-only background | Read-only background |
| Background | Dimmed and inert | Dimmed | Background objects editable |
| Kiosk | Actionable as in View | Read-only | Read-only; no editors |
| Static card | Not live or interactive | Render only | Render only |

Each editor has a stable primary toolbar. Tool parameters and selected-object
actions appear in a context tray over the top of the canvas. On a narrow screen
the tray scrolls horizontally instead of shrinking the plan.

<!-- docs-section: input -->

## 6. Navigation, zoom and input

The canvas grows with actual content. **Fit all** frames rooms and any distant
objects; each space keeps its local View viewport.

| Scenario | Mouse | Touch View | Touch editors | Keyboard |
|---|---|---|---|---|
| Zoom and pan | Wheel; drag empty space; `−`/`+` | Pinch; drag; double-tap resets kiosk | Available but precision is not guaranteed | — |
| Change space | Click a tab | Tap; kiosk swipe at 1:1 | Tap a tab | — |
| Device | Click/double-click per mode | Tap; safe actions equal desktop | Drag/properties are best effort | `Esc` closes the top surface |
| Draw or precise drag | Full contract | Not applicable | Best effort; use desktop for Resize and exact nodes | `Shift` changes magnet/angle; `Esc` cancels the operation |
| Editor history | Undo/Redo controls | Not applicable | Controls may work; no gesture guarantee | `Ctrl/Cmd+Z`, `Ctrl/Cmd+Shift+Z`, `Ctrl+Y` |
| Kiosk sizing | — | Hold empty space for 3 seconds | — | — |

At zoom above 1:1 a horizontal kiosk gesture pans instead of changing space.
Any manual kiosk operation pauses auto-cycle for 60 seconds.

### Cancel and undo

- `Esc` cancels an unfinished path, current drag/resize/rotation, or the top
  dialog without undoing an already committed action.
- `Ctrl/Cmd+Z` undoes an editor command; redo is `Ctrl/Cmd+Shift+Z` or `Ctrl+Y`.
- Undo/Redo stores up to 50 named commands for Plan and Background.

<!-- docs-section: spaces -->

## 7. Spaces

A space may represent a floor, garden, garage or separate structure. It stores
its image, grid scale, geometry, Background layer and display overrides.

### Plan source

- upload SVG, PNG, JPG or WebP;
- select a previously uploaded plan;
- choose no image and draw the geometry by hand.

The plan image keeps its proportions initially. Background can later move,
scale or rotate it. Detaching a plan never deletes its server file; deletion
requires an explicit user action.

### Display settings

A space can show/hide room borders, names, LQI, Background and openings. It can
override fill mode, Glow, day-cycle background, north, sun rays, room-card font
scale and which room metrics are visible.

Room cards are positioned and scaled on the plan. View renders only the metrics
enabled for that space.

![Room card with temperature, LQI and light state](images/08-room-card.png)

<!-- docs-section: plan-tools -->

## 8. Rooms and walls

### Create a room

Select **Walls** and draw one continuous chain. Every completed segment is
crash-safe. Changing tool, editor or floor finishes an open chain as ordinary
independent walls. When the latest segment creates bounded endpoint/T/X faces,
House Plan offers them from smallest to largest. Save creates that room, Keep
as walls rejects only that candidate, and Cancel restores the whole draft with
no partial rooms.

Existing segment endpoints and lines appear above walls while drawing. An
endpoint grows when the next click will join it. A point on a line shows where
the click will create a valid junction.

### Plan tools at a glance

| Tool | Result | Room area | Light and shadow | Main limit |
|---|---|---|---|---|
| Walls | Continuous wall chain; offers rooms when it closes faces and finishes open chains as independent walls | Only a confirmed room has area | Physical segments block light; openings pass it | Partial room overlap is rejected; there is no separate Partition drawing tool |
| Column | Square or circular support | Does not change area | Blocks light inside its shape | One shape/size/rotation; not a wall or room |
| Boundary | Virtual span of a shared wall | Geometry and area stay unchanged | Light passes; no physical wall is painted | Only a shared boundary between adjacent rooms |
| Opening | Door, window or gate | Does not change area | Door/gate passage follows state; window may cast sun | Must fit completely on a suitable wall segment |

Other operations edit existing geometry:

| Operation | Result |
|---|---|
| Merge | Joins adjacent rooms; a dialog chooses the surviving identity, name and area |
| Split | Cuts a room from one wall to another; the larger part keeps the original room |
| Resize | Moves a wall with shared geometry or scales a room by corner handles |
| Thickness | Changes one physical span or every wall of a room |
| Delete room | Deletes only the selected room after confirmation |

![Selected partition and its Plan context tray](images/05-plan-context-tray.png)

Wall thickness is stored in real units. A room may have different thicknesses
on different spans. Open wall branches and T-junctions are allowed; shared
geometry remains joined without painted end caps.

### HA area binding

One HA area may be bound to one room. The binding drives automatic device
placement, room LQI, light and aggregate climate. A room without an area may
still contain manually assigned devices and explicit measurement sources.

## 9. Doors, windows, gates and locks

Choose Opening, select door/window/gate, and click a wall. Defaults are 90 cm,
120 cm and 300 cm. The complete opening must fit on the wall.

An opening may bind a contact; doors and gates may also bind a lock. View paints
the moving leaf and state. A lock badge is green when locked and orange when
unlocked. A plan tap never toggles a lock. The opening card provides a labelled
lock/unlock control, with confirmation before unlocking.

Openings may slide along joined wall corners. A double click in Plan opens
properties. Thick walls keep visible jambs and align the symbol to the correct
face.

<!-- docs-section: devices -->

## 10. Devices

House Plan reads Home Assistant device, entity and area registries. A device in
a bound HA area receives an automatic marker. Service-only records, bridges and
other non-spatial records are filtered; a light group may replace its members.
Newly discovered devices get a red dot until first opened in Device.

### Bindings

| Binding | Use |
|---|---|
| HA device | Uses its related entities and resolves a primary function |
| HA entity | Exact entity binding after enabling “Show entities” |
| Virtual device | Label/icon/description only, with no live active state |

The same binding cannot be used by two markers.

### Device editor

- drag a marker to save its server-side position;
- click it to edit name, binding, room, tap action and presentation;
- **Add** creates a virtual marker or picks a binding manually;
- **Hidden and disabled** reveals user-hidden and HA-disabled records only in
  the editor;
- **Icon rules** edits the first-match regular-expression list.

The dialog shows binding provenance, exact next tap result, skipped targets and
a live presentation preview. A saved missing source is shown as missing rather
than silently replaced.

![Device editor with binding provenance and the exact action result](images/06-device-editor.png)

![Live preview of the selected device presentation](images/06-device-display-preview.png)

Hidden markers keep configuration and may still contribute to area aggregates.
An HA-disabled binding is excluded from rendering, state, actions, light and
aggregates until the same ID becomes active again.

## 11. Tap actions

| Gesture | View | Device editor |
|---|---|---|
| Short click/tap | Configured action | Open marker settings |
| Hold 600 ms | House Plan device card | No device control |
| Right click | Native HA more-info for the primary entity | Browser/editor context |

| Action | Behaviour | Safety |
|---|---|---|
| Device card | House Plan card with entities, model, description, links and files | No state change |
| HA more-info | Native dialog for the exact primary entity | No state change |
| Toggle state | Toggles the exact binding, supported device function or configured light-source group | Locks, alarm panels and protective garage/door/gate targets are no-op; confirmation is optional |
| Run | Runs an automation, script or scene | Explicit target; confirmation is optional |

A light defaults to Toggle; other devices default to the House Plan card. An
unsupported Toggle remains a visible no-op and is never changed into another
action behind the user's back.

When a device-bound marker has two or more own `light.*`/`switch.*` entities,
**Entity to toggle** appears below Toggle. It selects the exact own channel and
updates the target hint before Save. **Automatic** keeps the previous binding /
functional-role rules. A missing saved entity stays configured, shows a
warning and temporarily falls back; returning the same entity restores the
choice. This setting is independent from **Leading light entity**. With an
explicit external controls group, an explicitly selected own entity joins the
group; without a selection existing groups remain external-only.

![House Plan device card with state and safe actions](images/09-device-info.png)

<!-- docs-section: visual-states -->

## 12. Device visual states

Presentation has three independent layers: stable marker background, icon or
value, and optional activity pulse. Priority is **alarm → working → open →
neutral**.

| State | Meaning | Examples |
|---|---|---|
| Red alarm | Critical condition, even with live states disabled | Smoke, gas, CO, leak, tamper/problem/safety, triggered alarm |
| Yellow | Device is doing its main job | Light/switch/fan on, active climate, vacuum cleaning, known appliance work |
| Orange | Physically open or unlocked | Door/window contact, unlocked lock, opening valve |
| Faded | Data unavailable | All relevant entities unknown, unavailable or absent |
| Neutral | No alarm, work or open condition | Off, closed, idle, standby, docked |

For a composite appliance with a dedicated Power switch, Power=`on` alone
remains neutral. If Home Assistant also exposes a strict lifecycle entity such
as Status/Run state/Job state, active values (`start`, `running`, `washing`,
`rinse`, and similar work states) make the marker yellow; idle, paused and
terminal values remove it. Power=`off` or unavailable still fades the marker
even if the lifecycle value is stale. Mode, Program, Stage and remaining time
are not treated as independent proof of work, and an ordinary lone relay keeps
its existing yellow-on behaviour.

Activity may be a finite three-wave event, persistent presence, a travelling
transition, or persistent work. `prefers-reduced-motion` replaces ordinary
motion with a compact indicator while the alarm remains clear.

The four display choices are icon + state; icon + state + activity; value +
state; and always-static icon. A separate value badge can show an entity state,
useful attribute, average LQI or linked light state on any side of the marker.

Virtual devices use the ordinary neutral/hover background with a dashed outer
circle. They cannot have active state or pulse. Unavailable keeps the ordinary
presentation with the standard icon opacity reduction. Zigbee LQI remains a
separate badge.

## 13. Room fills and light

Space fill modes include user colour, temperature comfort range and LQI. Room
settings may override the space. Glow is independent from the base fill.

A light source may come from automatic classification, an explicit Always
role, or a controlled source group. Walls, partitions and columns occlude Glow;
open passages transmit it. When a configured light source disappears or loses
its valid binding, its contribution is removed instead of keeping stale light.

Overlapping Glow pools add brightness and colour where browser SVG blending is
supported; otherwise House Plan uses a safe normal blend without changing the
saved setting.

<!-- docs-section: background -->

## 14. Background editor

The authoritative technical interaction contract is
[DECOR-EDITOR.md](DECOR-EDITOR.md).

| Tool | Create | Edit |
|---|---|---|
| Select | Select an item | Move, scale, rotate; double click properties; Delete/Backspace removes |
| Backdrop | Available when a plan image exists | Move, corner-scale, rotate; double click numeric size/angle |
| Line | Drag endpoints | Colour/opacity, physical thickness and solid/dashed style |
| Rectangle | Drag diagonal; Shift makes a square | Stroke plus independent fill, size and angle |
| Oval | Drag bounds; Shift makes a circle | Stroke plus independent fill, radii and angle |
| Text | Click to open dialog | Multiline text, HA tokens, colour, physical size and angle |
| Furniture | Pick symbol, then click | Symbol, size, colour, outline and wall magnet |
| Erase | Click an item | Confirmed deletion, undoable |

Creation and transform snap to the grid plus nearby room/background anchors.
The plan image is interactive only with Backdrop selected. Undo/Redo shares the
50-command editor history.

![Selected line in the Background editor](images/07-background-editor.png)

Live text accepts `{sensor.entity}` and
`{climate.entity:current_temperature}` tokens. Missing, unavailable or complex
object values render as `—`; long values are shortened.

## 15. Sun background and window rays

These are independent features. **Follow the sun** changes the background from
day through golden hour to night and can fall back to browser time. Window rays
require `sun.sun`, a configured north direction and suitable exterior windows.
Weather cloud cover may reduce ray intensity.

For window rays, point the compass N arrow toward the place where true north
actually lies on the drawing. The value is the literal clockwise direction
from canvas-up to north, not an opposite correction for a rotated plan. If you
previously mirrored the compass to compensate for the old ray-direction bug,
return it to the real north after updating.

Rays remain visual only: they do not change Home Assistant state. Walls and
physical obstacles clip them; changing north or window geometry recalculates
the result.

## 16. Robot vacuums

The dock marker stays at its saved location while a live puck and path follow a
supported map source. Calibration maps source coordinates to plan coordinates.
Automatic room-name matching is a starting point; manual drag/stretch corrects
it. A diagnostic source picker reports missing or incompatible sources instead
of silently rebinding.

Multiple maps are represented as distinct sources/calibrations. A vacuum is
shown only in the space whose saved mapping currently matches the active map;
the dock remains in its configured space. See [VACUUM.md](VACUUM.md) for the
source dialect and calibration contract.

## 17. Kiosk

Set `kiosk: true` on a card in a Panel view. Editors and the ordinary header are
removed. Pinch/drag navigate, double-tap resets, and a 1:1 horizontal swipe
changes space. Holding empty space for three seconds opens per-display icon and
text sizing. `cycle` enables automatic space changes; interaction pauses it for
60 seconds.

## 18. Static space card

`custom:houseplan-space-card` renders one configured space without live states,
hover, drag, more-info or actions. A footer button opens the full plan. Use it
for compact dashboard navigation, not for home control.

```yaml
type: custom:houseplan-space-card
space: ground
```

## 19. Plan maintenance

Optimization compacts old off-grid geometry and unused layout records while
preserving rooms, bindings and supported settings. It does not delete plan
images or attachments merely because nothing currently references them.

Optimization creates one server-side undo point. Any later edit makes that undo
stale, so create a Home Assistant backup before a large maintenance operation.

<!-- docs-section: multiple-cards -->

## 20. Storage, multiple cards and backups

### Portable JSON backup

**Global settings → Backup and transfer** exports either the complete House
Plan model or the current space. Import first shows a server-side preview with
type, versions, object counts, source and content-link state; nothing is written
until confirmation.

A full import replaces the model and creates one undo point. A space import
assigns new internal IDs and adds the copy without replacing global settings.
Internal uploaded files are not embedded in JSON; an import to another HA
instance must explicitly detach those links.

For **Current space**, enable **Plan only** to transfer the architectural
template without devices or Home Assistant bindings. It keeps rooms, walls,
openings, decor, backdrop transforms and manually positioned room labels at
their chosen scale, but removes real and virtual markers, device positions,
Area assignments,
temperature/humidity sources and opening contacts/locks. Live values in text
labels become `—`; surrounding static text stays intact. The import preview
marks this file as plan-only and adds it through the normal space-import flow.

Plan-only is not full anonymisation: space and room names, static text, file
names, exact coordinates and external URLs remain in the JSON. Internal plan
files are still referenced rather than embedded and may need to be detached on
another Home Assistant instance.

### Storage locations

| Data | Location |
|---|---|
| Spaces, geometry, Background and marker settings | HA storage `houseplan.config` |
| Marker and room-card positions | HA storage `houseplan.layout` |
| Plan files | `config/houseplan/plans` |
| Marker attachments | `config/houseplan/files` |
| Vacuum path | Separate House Plan HA storage |
| Cache, viewport and kiosk scale | That browser's `localStorage` |

### Several cards and clients

Several `custom:houseplan-card` instances may use different `default_floor`
values. This is the supported way to start one wall display on the ground floor
and another on a garage or upper floor.

- configuration, rooms, Background and device layout are shared server data;
- `default_floor` is an initial choice for that card;
- current mode, selected space, zoom/pan and kiosk sizing are local;
- WebSocket broadcasts saved changes and revision checks reject a stale write;
- avoid editing the same object in two browsers: the second save may need a
  refresh and manual reapplication.

### Files and quotas

Plan files accept SVG/PNG/JPG/WebP up to 8 MB, with a 200-file/256-MB total.
Marker attachments accept PDF/PNG/JPG/WebP/TXT up to 50 MB, with a
1000-file/1-GB total and 50 links per marker. Writes are also refused below
512 MB free disk space. Detached files remain until explicitly deleted.

<!-- docs-section: limits -->

## 21. Current limitations

| Limitation | Practical effect |
|---|---|
| Rooms must be closed | An open path is walls, not a room with area |
| One HA area per room | To split one HA area visually, assign devices manually |
| Boundary requires adjacent rooms | It cannot open an exterior wall or branch from empty space |
| Editors are desktop-first | Touch editing may be awkward, limited or absent |
| Room details use hover in View | A touch-only user may need an editor or another visible metric |
| Sun has no exterior 3D model | It cannot know shadows from trees, awnings or neighbouring structures |
| Icon rules use regular expressions | First matching rule wins and invalid expressions are rejected |

Storage guards allow up to 50 spaces, 400 rooms per space, 2,000 markers, 500
openings, 1,000 Background items, 500 wall records and 500 virtual spans per
space. The configuration package is limited to 2 MB.

<!-- docs-section: diagnostics -->

## 22. Troubleshooting

### Card does not load

| Symptom | Check |
|---|---|
| `Custom element doesn't exist: houseplan-card` | Integration loaded; resource is `/houseplan_files/houseplan-card.js` with type `module`; hard-refresh |
| MIME `text/plain` | Replace `/custom_components/...` with `/houseplan_files/...` |
| Integration missing | Folder is exactly `custom_components/houseplan`; restart HA; inspect import errors |

### Devices or values are missing

- confirm the room's HA-area binding and the device/entity registry area;
- open Device → Hidden and disabled;
- verify the selected source still exists and is available;
- remember that a virtual marker has no active state;
- inspect the dialog's exact target and skipped-target explanation.

### Geometry looks wrong

- confirm grid cell size before judging physical dimensions;
- use Fit all to include distant objects;
- check wall thickness and whether a shared span is a virtual Boundary;
- use desktop for precise nodes, Split and Resize.

### Vacuum does not move

- confirm the active map source and map identity;
- check calibration anchors and current source availability;
- verify that the active map is assigned to this space;
- open source diagnostics instead of deleting/recreating the marker.

When reporting a problem, include House Plan version, HA version, browser,
console/server errors and reproducible steps. Replace private entity IDs and
plans with synthetic equivalents.