mirror of
https://github.com/Matysh/houseplan-card
synced 2026-07-31 16:38:31 +00:00
Matysh
f5e6c0318d
Owner's batch: - zoom now opens on what is DRAWN (rooms + 5% margin) for spaces with no background image; with one the image is the plan and still fits whole. A small plan on the square canvas no longer opens as a speck. - swiping between spaces, and the kiosk carousel, slide sideways; honours prefers-reduced-motion. - the room settings button reads 'Room settings' and lightens on hover. - 'curation' is filtering everywhere: UI strings, docs, code. Checked the yard while I was there: its drawing sits off-centre because it was drawn that way — before the migration x spanned 0.12..0.54 with 0.12 and 0.46 of margin. The migration added 0.1465 on each side, symmetrically. Content-fit zoom makes it moot anyway. From the v1.47.0 review: - HP-1470-02: the picker let you delete the plan you had just selected — it is not in the stored config yet, so the server rightly called it free, and the save then stored a url with no file. The button is disabled, and since two clients can do this in either order, config/set now verifies every internal plan url against the disk under the write lock and answers . External and legacy urls are not ours to police. - HP-1470-01: growth is bounded at the door rather than by deleting old files — that mistake cost real plans twice. check_quota refuses an upload that would push the store past 256 MB / 200 plans (1 GB / 1000 attachments) or leave less than 512 MB free. The plan list is capped at 60 newest with a total, and thumbnails load lazily. - HP-1470-03: picking a saved plan waited for nothing and stored a fallback ratio when the signature had not arrived — a square plan came out stretched. It waits for the signature, binds the result to the dialog that asked, and the dialog preview is signed too. - report §5: the last lifecycle comments still described age-based collection. Not released yet — the owner asked for a release once the batch is done.
124 lines
7.1 KiB
Markdown
Executable File
124 lines
7.1 KiB
Markdown
Executable File
# Product scope — what House Plan is and is not
|
||
|
||
*Fixed with the owner on 2026-07-22. This document is a guard rail: features are
|
||
built, improved and accepted **only** if they serve a job listed here. When a new
|
||
idea appears, first find its row in this file; if there is none — it belongs to
|
||
HA core, to another card, or nowhere. Companion documents: PRODUCT.md (market),
|
||
ROADMAP.md (order of work), UX-MODES.md (interaction model).*
|
||
|
||
## Mission
|
||
|
||
House Plan is the **spatial "at a glance + quick act" layer** for a Home
|
||
Assistant home. Upload or draw a floor plan, outline rooms bound to HA areas,
|
||
and the home's devices appear on a live, tappable map: states, climate, alerts,
|
||
guarded quick actions. Setup is GUI-only — no Inkscape, no YAML, no external
|
||
editors. Everything that is not "look at the home spatially and act on the
|
||
obvious" is somebody else's job.
|
||
|
||
## Target audience
|
||
|
||
| Persona | Role | Surface |
|
||
|---|---|---|
|
||
| **Home admin** (primary) | HA enthusiast, house/large flat, 20–200 devices, several floors; sets up and maintains the plan | Desktop browser (both editors live here) |
|
||
| **Household members** | Non-technical; consume the plan daily, never edit | Wall tablet (kiosk), phone (companion app) |
|
||
| **Guests / kiosk** | View-only glance at the home | Wall tablet |
|
||
|
||
Design consequence: **View mode is the product** for two of the three personas.
|
||
Editors are admin-only tools and must never leak interactions into View
|
||
(established by UX-MODES; lock guard, inert openings, no drag in View).
|
||
|
||
## Core user jobs — the component must close these
|
||
|
||
| # | Job (user's words) | Status |
|
||
|---|---|---|
|
||
| J1 | "Show the whole home and what's happening right now" — live spatial overview: device states, room fills (light/temp/LQI), values, multi-floor tabs | **Closed** |
|
||
| J2 | "Something is wrong — show me *where*" — leak/smoke/gas pulse, open doors/windows, unlocked locks, red dot on devices HA added silently | **Closed** |
|
||
| J3 | "Let me act on the obvious right from the plan" — tap-to-toggle for safe domains, info cards, guarded lock action | **Closed** |
|
||
| J4 | "From zero to a working plan in one evening, no Inkscape/YAML" — image/PDF/draw, floors-import wizard, room polygons bound to areas, filtered auto-placement, editable icon rules | **Closed**; onboarding polish is *partial* (no registry-driven room suggestions) |
|
||
| J5 | "Room climate at a glance" — per-room temperature/humidity, comfort-range fills, room-card metrics | **Closed** |
|
||
| J6 | "Keep the plan true as the home evolves" — new-device flag, two editors, drag/resize, merge/split, multi-client live sync, optimistic locking | **Closed** |
|
||
| J7 | "Is my Zigbee mesh healthy *here*?" — LQI badges, per-room average, LQI fill | **Closed** (kept deliberately: cheap, spatial by nature, no in-plan competitor) |
|
||
|
||
## Partially covered — improvement backlog stays inside these
|
||
|
||
- **Touch ergonomics of the editors**: corner handles and grid clicks are small on
|
||
tablets; editors are desktop-first today. Improve, don't redesign.
|
||
- **Value display**: single current value per device; units/precision follow HA
|
||
formatting only.
|
||
- **Accessibility**: `prefers-reduced-motion` only; no keyboard navigation in
|
||
editors, no ARIA labelling of the plan.
|
||
- **Docs/screenshots**: README predates the two-editor redesign.
|
||
|
||
## Known gaps that fit the mission (build only on owner's request)
|
||
|
||
- Person/presence shown in rooms (classic floorplan ask; pure J1).
|
||
### The lock invariant, stated precisely (review CR-1)
|
||
|
||
No lock or alarm panel is ever actuated **by a tap on the plan**: icons, lock
|
||
badges, `marker.controls[]` and the device card all refuse (`resolveTapAction`
|
||
+ `TOGGLE_FORBIDDEN_DOMAINS`, `isControllable`, `_cardToggle`). There is exactly
|
||
**one** sanctioned actuation surface: the labeled Unlock/Lock button inside an
|
||
opened door card, which additionally confirms before unlocking. That is a
|
||
product decision (2026-07-22), not an oversight — but it means the invariant is
|
||
"never by accident", not "never at all". Any new actuation path must either
|
||
refuse locks or be added to this paragraph.
|
||
|
||
- Plan-level "security glance": one badge for "all locked / N open" (J2).
|
||
- Threshold colouring for room-card metrics (J5).
|
||
|
||
## Standing rule: never delete a user's file on an inference
|
||
|
||
Fixed with the owner on 2026-07-28, after automatic collection removed two
|
||
detached floor plans. The component may delete a file only when the user's
|
||
action says so — replacing a plan, removing an attachment, deleting a device.
|
||
"Nothing points at this any more" is not such an action: detaching a plan is one
|
||
click and reversible, and the editor tells the user the file stays.
|
||
|
||
The asymmetry is the whole argument. Wasted disk is visible, cheap and
|
||
reversible; a deleted file is none of those. Where the evidence is weak, keep
|
||
the file — and if a future version wants to reclaim that space, it asks.
|
||
|
||
## Out of scope — never build, point users to the right tool
|
||
|
||
- Automations, scenes, scripts, notifications → HA core.
|
||
- Device/entity administration (rename, reassign area, disable) → HA registry
|
||
UIs. We *read* the registry, we never manage it.
|
||
- History, graphs, statistics → recorder/history cards. We show now, not then.
|
||
- Camera streams, media controls → their own cards; our more-info opens HA's.
|
||
- Energy monitoring/analytics → HA Energy.
|
||
- 3D / isometric / photorealistic rendering, furniture drawing → niche tools
|
||
(easy-floorplan et al.); we are a schematic live map, not an interior editor.
|
||
- A general dashboard framework (menus, popups, theming engine) → Bubble Card,
|
||
Dwains and friends.
|
||
|
||
## Excess-functionality audit (2026-07-22)
|
||
|
||
- **Device metadata: links & PDF manuals** — not spatial, but tiny, server-side,
|
||
and used in real installs. Verdict: **keep, frozen** (no growth).
|
||
- **Virtual devices** — placeholders for not-yet-installed hardware; serves J6.
|
||
Verdict: **keep, frozen**.
|
||
- **LQI diagnostics** — promoted to J7 (differentiator), not excess.
|
||
- Nothing found that warrants removal; the mode redesign already moved every
|
||
interaction to where it belongs.
|
||
|
||
## The component in one breath (README/HACS copy)
|
||
|
||
> **House Plan** turns your Home Assistant into a live map of your home. Upload
|
||
> a plan image (or draw one), outline rooms and bind them to HA areas — your
|
||
> devices appear in place, automatically, with live states. Glance at the wall
|
||
> tablet: what's on, what's open, what's too cold, what's leaking, what's new.
|
||
> Tap to act — safely: locks never toggle by accident. Two built-in editors
|
||
> (plan and devices) mean no Inkscape, no YAML, no external tools — ever.
|
||
|
||
**Tasks it closes:** whole-home live overview · spatial alerts (leak/smoke/open/
|
||
unlocked/new device) · safe quick actions · per-room climate · Zigbee mesh
|
||
health · zero-to-plan GUI onboarding · keeping the plan true over years.
|
||
|
||
**Where users are:** Telegram chat https://t.me/ha_houseplan (support, feature
|
||
signals, screenshots) — treat it as the primary source of field feedback.
|
||
|
||
**Pains it removes:** hand-crafted SVG + YAML floorplans · entity-list
|
||
dashboards that hide *where* things happen · silent device sprawl · accidental
|
||
toggles of security devices · per-device dashboards that non-technical family
|
||
members can't read.
|