mirror of
https://github.com/Matysh/houseplan-card
synced 2026-09-29 11:18:48 +00:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Cursor AgentandMatysh
|
99f7c3a4a9 |
@@ -0,0 +1,154 @@
|
||||
# Audit — functional integrity & gaps
|
||||
|
||||
> Snapshot: **2026-08-05**, product **v1.58.0**.
|
||||
> Cross-check of claimed surface (README / STATUS / SCOPE) against code and
|
||||
> tests. Mission lens: SCOPE.md — *spatial at-a-glance + quick act*.
|
||||
|
||||
## 1. Mission fit
|
||||
|
||||
SCOPE personas:
|
||||
|
||||
| Persona | Primary mode | Fit |
|
||||
|---|---|---|
|
||||
| Home admin | Plan / Devices / Background editors | Strong — full geometry + marker tooling |
|
||||
| Household members | View | Strong — tap toggles, room cards, glow/climate |
|
||||
| Guests / kiosk | View + `kiosk: true` | Strong — editors blocked, swipe/cycle |
|
||||
|
||||
Jobs J1–J7 are marked **Closed** in SCOPE; J4 (onboarding) still **partial**
|
||||
(floors-import exists; registry-driven room *suggestions* do not). That matches
|
||||
code reality.
|
||||
|
||||
**Systematicity grade: high.** Features hang off a coherent model:
|
||||
|
||||
- spaces → rooms (polygons) → derived walls → openings
|
||||
- markers bound to device/entity/virtual → layout points
|
||||
- settings tiers: global → space → room → device
|
||||
- View is the product; editors are admin-colored frames (UX-MODES)
|
||||
|
||||
Excess features (PDF manuals, virtual devices, LQI) are consciously **kept /
|
||||
frozen** rather than deleted — unusual and correct for a shipping tool.
|
||||
|
||||
## 2. Claim ↔ code matrix
|
||||
|
||||
| Feature area | Claimed | Implemented | Tested | Notes |
|
||||
|---|---|---|---|---|
|
||||
| One HACS package (integration + card) | ✓ | ✓ | CI hacs/hassfest | Matches |
|
||||
| GUI room markup (no SVG/YAML) | ✓ | ✓ | smokes + logic units | Matches |
|
||||
| Doors/windows + lock invariant | ✓ | ✓ | smoke_lock_*, logic | CR-1 held |
|
||||
| Islands / merge / split / open_to | ✓ | ✓ | units + smokes | Matches |
|
||||
| Room resize | ✓ | `resize.ts` | units + smokes | Matches |
|
||||
| Decor + backdrop transform | ✓ | ✓ (v1.58) | backdrop tests/smokes | Paper = room contours |
|
||||
| Infinite / square canvas | ✓ | ✓ | canvas smokes | Matches CANVAS.md |
|
||||
| Align-to-grid | ✓ | `align-grid.ts` | units | Matches |
|
||||
| Auto devices by HA area | ✓ | `devices.ts` | units | Matches |
|
||||
| Explicit hide-from-plan | ✓ | ✓ | smokes | FILTERING.md |
|
||||
| Editable icon rules | ✓ | ✓ | — | Matches |
|
||||
| Tap: info / more-info / toggle / run / cover | ✓ | ✓ | logic + smokes | Security model intact |
|
||||
| Glow + door sectors | ✓ | ✓ | smokes | Island light block = known limit |
|
||||
| Temp / LQI / light fills | ✓ | ✓ | units/smokes | Matches |
|
||||
| Room cards + per-room settings | ✓ | ✓ | smokes | Matches |
|
||||
| Kiosk | ✓ | ✓ | smokes | Matches |
|
||||
| Vacuums + server trails | ✓ | `vacuum.ts` + `trails.py` | units + smokes | Display-only (intentional) |
|
||||
| Sun / daynight / wedges | ✓ | `sun.ts` | units + smokes | Matches |
|
||||
| `houseplan-space-card` | ✓ | ✓ | smokes | Matches |
|
||||
| Signed content + SVG sandbox | ✓ | ✓ | HA tests + smokes | Matches |
|
||||
| en/ru i18n | ✓ | ✓ | key-parity test | Matches |
|
||||
| Floors-import wizard | ✓ | ✓ | — | Exists; suggestions gap below |
|
||||
| Registry room suggestions | PRODUCT / J4 | **Partial / missing** | — | Gap |
|
||||
| Music notes / TV ripples | UX backlog | **Absent** | — | Intentional not-planned |
|
||||
| Furniture / wall CAD | competitor feature | **Absent** | — | Non-goal |
|
||||
| Vacuum commands | user ask often | **Absent** | — | VACUUM.md non-goal |
|
||||
| Cloud sync | — | **Absent** | — | Non-goal |
|
||||
|
||||
**Integrity conclusion:** marketed surface and shipped surface align unusually
|
||||
well. The main integrity risks are **docs drift** (ARCHITECTURE/UX-MODES/PRODUCT)
|
||||
and **auth UI↔API default mismatch** (see AUDIT-QUALITY), not phantom features.
|
||||
|
||||
## 3. Cross-cutting integrity themes
|
||||
|
||||
### 3.1 Coordinate & geometry story — coherent after evolution
|
||||
|
||||
Legacy fixed pixel canvas → normalized square → infinite canvas with bounds.
|
||||
Migrations + `geometry/repair` + dual-store `geom_pending` show the team treats
|
||||
coordinate changes as product-critical (correct). Frontend `space-geometry.ts`
|
||||
and backend `validation.py` intentionally mirror limits (±5000) — two sources of
|
||||
truth, but tested.
|
||||
|
||||
### 3.2 Security story — mostly coherent
|
||||
|
||||
| Surface | Policy | Coherent? |
|
||||
|---|---|---|
|
||||
| Lock / alarm from plan icon | Never actuate | Yes — tested |
|
||||
| Lock via door-card button | Explicit labeled control | Yes — SCOPE CR-1 |
|
||||
| SVG plans | Sandbox CSP + signing | Yes |
|
||||
| Config/layout writes | `may_write` | **Split** with UI admin gate |
|
||||
| `run` tap | automation/script/scene only + optional confirm | Yes |
|
||||
|
||||
### 3.3 Multi-client story — mostly coherent
|
||||
|
||||
Config writes: CAS + write chain. Layout point updates: rev bumps but **no**
|
||||
conflict surface — fine for one editor, weak for two tablets dragging at once.
|
||||
|
||||
### 3.4 Filtering story — cleaned up
|
||||
|
||||
Old hardcoded “dacha DNA” filters → editable icon rules + explicit hide flags
|
||||
(v1.51). Documented in FILTERING.md. Good systematic cleanup.
|
||||
|
||||
## 4. Gaps (build only with intent)
|
||||
|
||||
### In-mission polish (SCOPE already lists most)
|
||||
|
||||
| Gap | Persona impact | Notes |
|
||||
|---|---|---|
|
||||
| Registry-driven room suggestions | Admin first-run | J4 partial; biggest *product* unlock left |
|
||||
| Touch ergonomics of editors | Admin on tablet | Partial |
|
||||
| Value-display richness | Household | Partial |
|
||||
| a11y beyond `prefers-reduced-motion` | All | Keyboard/ARIA weak |
|
||||
| Plan-level security glance (“N open / all locked”) | Household / kiosk | SCOPE known gap |
|
||||
| Person / presence in rooms | Household | SCOPE known gap; presence ripples exist at marker level |
|
||||
| Threshold colouring for room metrics | Household | SCOPE known gap |
|
||||
| README / screenshot lag vs redesign | Adoption | Distribution, not function |
|
||||
|
||||
### Engineering gaps that feel like product bugs
|
||||
|
||||
| Gap | Why it matters |
|
||||
|---|---|
|
||||
| Default `admin_only=False` while UI hides editors from non-admins | Non-admin can still mutate via raw WS — surprise vs household persona |
|
||||
| Opening-measure magnet placement flake under pinned Chromium | One smoke red; pixel-precision path |
|
||||
| Demo.html needs hass nudge / F5 for icons | Harness quirk; confuses manual demo in a raw browser |
|
||||
|
||||
### Explicit non-gaps (do not “fix” by building these)
|
||||
|
||||
- 3D / glb
|
||||
- Furniture / wall drawing (easy-floorplan territory)
|
||||
- Vacuum start/zone commands
|
||||
- History graphs, cameras, energy
|
||||
- Cloud collaboration
|
||||
- Becoming a general dashboard framework
|
||||
|
||||
## 5. Systematicity scorecard
|
||||
|
||||
| Question | Answer |
|
||||
|---|---|
|
||||
| Is there one mental model? | Yes — spaces/rooms/markers/settings tiers |
|
||||
| Do modes prevent tool leakage? | Mostly — UX-MODES + kiosk hard-block; View is default |
|
||||
| Are overrides predictable? | Yes — more specific settings win |
|
||||
| Do security rules have a single owner? | Tap: `resolveTapAction`. Write: `may_write` (UI duplicate — debt) |
|
||||
| Are frozen excesses documented? | Yes — SCOPE excess audit |
|
||||
| Is the roadmap still pointing at the mission? | Phase 8–10 are quality/distribution; Phase 9 leftovers are registry/docs — aligned |
|
||||
|
||||
**Grade: A− for functional systematicity.** The product feels designed, not
|
||||
accreted — with the structural exception of the Lit shell size (quality debt,
|
||||
not a feature-model debt).
|
||||
|
||||
## 6. Suggested integrity checks for future agents
|
||||
|
||||
Before merging a feature:
|
||||
|
||||
1. Does it serve J1–J7 or a SCOPE “known gap”? If neither → reject or rewrite.
|
||||
2. Does it introduce a second policy for taps, writes, or file deletion? → fold
|
||||
into `resolveTapAction` / `may_write` / collection rules.
|
||||
3. Does it need a migration? → dual-store / repair path, not silent reshape.
|
||||
4. Is it tested at the right layer? Pure math → `npm test` / pytest; pointer UX
|
||||
→ smoke with `check`/`finish`; never a smoke that always exits 0.
|
||||
5. Dual CHANGELOG + STATUS/ARCHITECTURE/TESTING updates in the **same** commit.
|
||||
@@ -0,0 +1,112 @@
|
||||
# Audit — market potential & competitors
|
||||
|
||||
> Snapshot: **2026-08-05**. Star counts via GitHub API the same day.
|
||||
> Supersedes the competitor table in `PRODUCT.md` (2026-07-05) until that
|
||||
> file is rewritten. Re-verify numbers before any public claim.
|
||||
|
||||
## 1. Demand shape
|
||||
|
||||
| Signal | Evidence |
|
||||
|---|---|
|
||||
| Persistent pain | HA Community “Floorplan” category; “100% Floorplan UI” mega-thread (500k+ views historically) |
|
||||
| 2025–2026 wave | Multiple GUI floorplan projects launched within months (easy-floorplan May 2026, Padraigggs Mar 2026, House Plan Jul 2026, plus older SVG/YAML tools) |
|
||||
| Audience | Enthusiasts with wall tablets / panel dashboards — **niche but sticky** |
|
||||
| Adjacent proof | Bubble Card (~4.4k★) shows polished GUI Lovelace cards can go quasi-mainstream; ha-floorplan (~1.6k★) with a hostile workflow shows a demand floor for *spatial* UIs |
|
||||
|
||||
**Verdict:** demand is real. The bottleneck is not “do people want a plan?” —
|
||||
it is “which GUI-first story wins attention before HA core ships something
|
||||
spatial.”
|
||||
|
||||
## 2. Competitive landscape (2026-08-05)
|
||||
|
||||
| Project | ★ | Updated | Approach | Overlaps us | Where we still win | Where they win |
|
||||
|---|---:|---|---|---|---|---|
|
||||
| [ha-floorplan](https://github.com/ExperienceLovelace/ha-floorplan) | **1584** | 2026-07 | Hand SVG + YAML/TS rules | Visualization power | Zero Inkscape/YAML barrier; shared server config | Max customization, mature ecosystem, contributors |
|
||||
| [easy-floorplan](https://github.com/nicosandller/easy-floorplan) | **430** | 2026-08-04 | In-card draw walls/furniture/devices | **Direct peer** — GUI, no YAML | HA **integration** + `.storage`, area-bound rooms, auto devices, vacuums/sun/glow/kiosk, quality-scale CI | Furniture drawing, faster growth, press (DE blogs), simpler “draw a house” story |
|
||||
| native `picture-elements` | built-in | — | % coords in YAML | Overlay icons on image | Editor + zones + shared layout | Zero install, official |
|
||||
| native Areas / Home dashboard | built-in | evolving | Grid by area/floor | “At a glance” home | **Spatial** plan | First-party discoverability |
|
||||
| [Padraigggs interactive floorplan](https://github.com/Padraiggg/Padraigggs-ha-interactive-floorplan) | 42 | 2026-04 | Editor + viewer cards, push to dashboard YAML | GUI editor | Server store, room polygons↔areas, overlays | Polygon light zones, camera animations, YAML export |
|
||||
| [zigbee-floorplan-card](https://github.com/TheLarsinator/zigbee-floorplan-card) | 73 | 2026-04 | LQI over image | LQI overlay | Full product, not single-purpose | Narrow clarity |
|
||||
| Dwains / Bubble Card | 2k / 4.4k | — | Dashboards / card kits | GUI quality bar | Spatial niche | Distribution, brand |
|
||||
| **House Plan** (us) | **21** | 2026-08-05 | Integration + card, room markup, server layout | — | See §3 | Traction, HACS default pending |
|
||||
|
||||
### Critical change since PRODUCT.md (2026-07-05)
|
||||
|
||||
`easy-floorplan` was listed at **11★ / immature**. One month later it is
|
||||
**≈430★**, actively released (v0.8.x), and getting third-party blog coverage.
|
||||
That collapses the old claim that the GUI-floorplan niche is “currently
|
||||
unoccupied.” The niche is now a **race**, and they are ahead on attention.
|
||||
|
||||
House Plan is **not** the same product: we refuse furniture/wall CAD
|
||||
(SCOPE / ROADMAP non-goal) and instead ship a **storage integration**,
|
||||
area-linked rooms, multi-client layout, and curated overlays. That moat is
|
||||
real — but only if users *find* us and understand the difference in one
|
||||
demo GIF.
|
||||
|
||||
## 3. Our moat (still valid)
|
||||
|
||||
Nobody else currently combines all of:
|
||||
|
||||
1. **Server-side config** — HA integration, `.storage`, optimistic `expected_rev`,
|
||||
live multi-client sync, survives dashboard YAML edits.
|
||||
2. **In-card room polygon editor** bound to HA **areas** → auto device placement.
|
||||
3. **Curated overlays** — glow pools, temp/LQI fills, sun wedges, vacuum trails,
|
||||
cover morph, lock invariant.
|
||||
4. **Operational maturity** — quality_scale.yaml, 4-layer tests, signed content +
|
||||
SVG CSP, diagnostics/repairs/system_health, dual en/ru docs.
|
||||
|
||||
Card-only peers store config in Lovelace YAML (or push into it). That is fine
|
||||
for one admin laptop; it is weaker for family tablets and multi-user homes —
|
||||
exactly our persona split in SCOPE.md.
|
||||
|
||||
## 4. Potential (honest)
|
||||
|
||||
| Horizon | Realistic outcome | Depends on |
|
||||
|---|---|---|
|
||||
| Near (HACS default + demo assets) | Low hundreds of ★; Telegram + forum traction | #9004 merge, GIF/video, EN forum/Reddit posts |
|
||||
| Medium (12 months of polish + registry depth) | Contender in the GUI-floorplan shortlist; maybe 0.5–1.5k★ if narrative sticks | Differentiation messaging vs easy-floorplan; onboarding magic |
|
||||
| Ceiling | Unlikely to dethrone ha-floorplan’s power-user base; unlikely Bubble-scale | Niche size + single maintainer |
|
||||
|
||||
**Usefulness:** high for the target personas (admin builds once; household/kiosk
|
||||
use View). **Commercialization:** none intended (MIT, local-first) — success =
|
||||
installs and unpaid maintenance load.
|
||||
|
||||
## 5. Strategic risks
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
|---|---|---|
|
||||
| easy-floorplan owns the “no YAML floorplan” mindshare | **High** | Sharpen README differentiation (server sync, areas, overlays); ship demo GIF now |
|
||||
| HA core ships a native spatial plan | **High (latent)** | Deepen floors/areas registry integration; speed of iteration |
|
||||
| HACS default #9004 stuck for months | **Medium** | Custom-repo path works; social proof before merge |
|
||||
| Single-maintainer bus factor | **Medium** | Docs + tests already strong; avoid feature sprawl |
|
||||
| Frontend API churn (`hass` internals) | **Medium** | Minimal surface; CI against current HA in harness |
|
||||
| Scope creep toward furniture CAD | **Self-inflicted** | SCOPE non-goals — do not chase easy-floorplan feature-for-feature |
|
||||
|
||||
## 6. Positioning recommendation
|
||||
|
||||
**One sentence:** *House Plan is the shared, area-aware live map of your Home
|
||||
Assistant home — not a drawing app for furniture.*
|
||||
|
||||
Lead with: multi-device sync, bind room→area→devices appear, glow/climate/sun/
|
||||
vacuums, kiosk for wall tablets. Acknowledge: if you want to *draw walls and
|
||||
sofas from scratch*, use easy-floorplan; if you have a plan image and a real HA
|
||||
registry, use House Plan.
|
||||
|
||||
## 7. Distribution checklist (status)
|
||||
|
||||
| Lever | State (2026-08-05) |
|
||||
|---|---|
|
||||
| Public demo | **Live** — https://demo.houseplan.tech (`demo`/`demo`) |
|
||||
| Dev stand | https://dev.houseplan.tech |
|
||||
| Telegram | https://t.me/ha_houseplan |
|
||||
| HACS custom install | Works |
|
||||
| HACS default | **Queued** — hacs/default#9004 open since 2026-07-06 |
|
||||
| Demo GIF / video in README | Still a ROADMAP Phase 10 open item |
|
||||
| Forum Floorplan + Reddit posts | Drafts exist off-repo; posting still open |
|
||||
| Stars | **21** — traction problem, not a product-depth problem |
|
||||
|
||||
## 8. What to refresh next
|
||||
|
||||
When stars or competitor maturity move materially, update **this file first**,
|
||||
then sync the table in `PRODUCT.md`. Do not leave PRODUCT as the only market
|
||||
doc — it already went a month stale while easy-floorplan 40×’d.
|
||||
@@ -0,0 +1,132 @@
|
||||
# Audit — implementation quality
|
||||
|
||||
> Snapshot: **2026-08-05**, product **v1.58.0**.
|
||||
> Severity: **critical / major / minor / nit**. No critical RCE found under
|
||||
> normal HA session auth.
|
||||
|
||||
## 1. Architecture snapshot
|
||||
|
||||
```
|
||||
src/ Lit 3 Lovelace cards (houseplan + space-card)
|
||||
houseplan-card.ts ~8691 LOC — orchestration god-object
|
||||
logic.ts / devices.ts / … extracted pure modules (good)
|
||||
styles.ts ~2223 LOC CSS-in-JS
|
||||
custom_components/houseplan/ HA integration (storage, WS, HTTP, trails)
|
||||
dist/ + frontend/ committed bundle (CI byte-compares)
|
||||
demo/ Playwright harness + smoke_*.mjs
|
||||
tests_backend/ pure + HA-harness pytest
|
||||
```
|
||||
|
||||
Bundle: **≈449 KB** raw / **≈128 KB** gzip — acceptable for a full editor+viewer.
|
||||
|
||||
## 2. What is strong
|
||||
|
||||
### Backend
|
||||
|
||||
- Single write-auth helper (`auth.may_write`) with **fail-closed** when entry
|
||||
missing (audit B2 lesson documented in the module).
|
||||
- Voluptuous validation with **cross-language option-list tests** that parse
|
||||
`DISPLAY_MODES` / `TAP_ACTIONS` from `logic.ts` — rare and valuable.
|
||||
- Config CAS via `expected_rev`; plan COW + quotas; never-delete-on-inference
|
||||
file policy (SCOPE).
|
||||
- Geometry migration with durable `geom_pending` intent (HP-1490 class).
|
||||
- Content HTTP: `requires_auth`, signed URLs for `<image href>`, SVG CSP sandbox.
|
||||
- Diagnostics / repairs / system_health present; `quality_scale.yaml` mostly
|
||||
**honest** (`test-coverage`, `strict-typing`, docs todos marked todo).
|
||||
|
||||
### Frontend (extracted brain)
|
||||
|
||||
- Tap security model in `resolveTapAction` — locks/alarms never toggle from the
|
||||
plan; cover garage/door/gate guarded; `run` limited to automation/script/scene.
|
||||
- Pure geometry / devices / sun / vacuum / resize / align-grid / signing modules
|
||||
with solid `node:test` coverage (~270 tests).
|
||||
- Shared `config-store` + space-geometry/render for `houseplan-space-card`.
|
||||
- Optimistic UI without rollback is **documented intentional** (ARCHITECTURE).
|
||||
|
||||
### Process
|
||||
|
||||
- Four test layers + smoke policy (“`[manual]` must have a failing auto check”).
|
||||
- Dual CHANGELOG (en/ru), SCOPE guard rail, CONTRIBUTING five-minute loop.
|
||||
- CI: hacs + hassfest + frontend + backend + smoke job.
|
||||
|
||||
## 3. Findings (ranked)
|
||||
|
||||
| # | Sev | Finding | Where |
|
||||
|---|---|---|---|
|
||||
| 1 | **major** | God-object card: ~8691 LOC, ~359 methods, ~125 private fields; `render()` ~382 lines. Smokes-only coverage for orchestration. | `src/houseplan-card.ts` |
|
||||
| 2 | **major** | `strict: true` hollowed by `noImplicitAny: false`; ~200 `any` sites in the card alone; `hass: any` everywhere | `tsconfig.json`, card / devices / logic |
|
||||
| 3 | **major** | Write-policy split: UI `_canEdit` is always admin-gated; API default `admin_only=False` lets **any** authenticated user write via WS/HTTP | `houseplan-card.ts` ≈L247–249, `auth.py` |
|
||||
| 4 | **major** | `_canEdit` fails **open** when `hass.user` is missing (`is_admin !== false`) | card ≈L248 |
|
||||
| 5 | **major** | `styles.ts` ~2223 LOC — second maintainability sink; untested | `src/styles.ts` |
|
||||
| 6 | **minor** | `layout/update` has no `expected_rev` — multi-tablet last-writer-wins per point | `websocket_api.py` |
|
||||
| 7 | **minor** | Marker `binding` is bare `str`; `ripple_color` not hex-matched; decor `w`/`h` allow negatives via `_NORM` | `validation.py` |
|
||||
| 8 | **minor** | Card-level `tap_action` / `resolveTapAction` cardDefault is dead / ignored — confusing API surface | `types.ts`, click path |
|
||||
| 9 | **minor** | Store `_async_migrate_func` is a no-op; real migrations live ad-hoc in setup | `store.py`, `__init__.py` |
|
||||
| 10 | **nit** | `quality_scale.yaml` cites `test_config_flow.py`; file is `test_ha_config_flow.py` | quality_scale.yaml |
|
||||
| 11 | **nit** | Duplicated `fireEvent` / `navigate` in card + space-card | both files |
|
||||
| — | positive | Forbidden-domain tap model + confirm + cover guards | `logic.ts` |
|
||||
| — | positive | Signed content + SVG sandbox | `http_api.py`, `signing.ts` |
|
||||
|
||||
**No critical** auth bypass of HA sessions found. Closest systemic issue is
|
||||
finding #3 (API openness vs UI) under the default options.
|
||||
|
||||
## 4. TypeScript & tooling
|
||||
|
||||
| Item | State |
|
||||
|---|---|
|
||||
| `tsc --noEmit` in build | Yes — correct (rollup TS plugin can warn-and-ship) |
|
||||
| ESLint / Prettier | **Absent** |
|
||||
| `noImplicitAny` | **Off** |
|
||||
| Frontend unit of the Lit class | **None** |
|
||||
| mypy strict (backend) | quality_scale **todo** |
|
||||
|
||||
## 5. Test map
|
||||
|
||||
| Layer | What it proves | Gap |
|
||||
|---|---|---|
|
||||
| `npm test` (~270) | Pure logic, i18n parity, tap security, geometry | Not the card shell |
|
||||
| `pytest` pure | validation.py without HA | — |
|
||||
| HA-harness (py≥3.13) | setup, WS races, auth, upload, geometry repair | Coverage % unmeasured |
|
||||
| `demo/smoke_*.mjs` (~100) | Real pointer/UI against fake hass | Pixel flakes (`smoke_opening_measure`); no Safari/Companion matrix |
|
||||
|
||||
Human checklist in TESTING.md last full self-run recorded at **v1.21.1** while
|
||||
product is at **v1.58.0** — auto net grew; documented human pass did not.
|
||||
|
||||
## 6. Docs drift (quality of truth)
|
||||
|
||||
| Doc | Drift |
|
||||
|---|---|
|
||||
| `ARCHITECTURE.md` intro | Still mentions old `src/data/house.ts` / 1489×1053 era in places; square/infinite canvas sections newer |
|
||||
| `UX-MODES.md` header | Still says “No code has been changed yet” — Phase 11 shipped |
|
||||
| `PRODUCT.md` competitor table | **Stale** — easy-floorplan 11→430★ (see AUDIT-MARKET) |
|
||||
| `STATUS.md` | Generally current as of 2026-08-04 |
|
||||
|
||||
Docs discipline is a project strength; these drifts are fixable and should be
|
||||
treated as debt, not ignored.
|
||||
|
||||
## 7. Top 10 technical debt (actionable)
|
||||
|
||||
1. Split `houseplan-card.ts` into shell + Plan/Devices/Decor editors + dialogs.
|
||||
2. Turn on `noImplicitAny` incrementally; type a thin `Hass` surface.
|
||||
3. Align write policy: wire UI to `admin_only`, or default `admin_only=True`.
|
||||
4. Fail closed on missing `hass.user`.
|
||||
5. Add CAS / expected_rev to `layout/update` (or document single-writer assumption).
|
||||
6. Split `styles.ts` by feature surface.
|
||||
7. Tighten MARKER_SCHEMA (`binding`, colors, decor extents, space ids).
|
||||
8. Unit-test orchestration hotspots (`_clickDevice`, write-chain conflicts, modes).
|
||||
9. Real Store migrations or document setup-time migrations as the only path.
|
||||
10. Remove or re-wire dead card-level `tap_action` / cardDefault.
|
||||
|
||||
Detailed priority and sequencing: [`AUDIT-RECOMMENDATIONS.md`](AUDIT-RECOMMENDATIONS.md).
|
||||
|
||||
## 8. Quality-scale honesty check
|
||||
|
||||
| Claim | Audit view |
|
||||
|---|---|
|
||||
| Bronze structural items `done` | Accurate |
|
||||
| Silver unloading / owner `done` | Accurate |
|
||||
| Gold diagnostics / repairs `done` | Accurate |
|
||||
| `test-coverage` / `strict-typing` / docs examples `todo` | Accurate — keep them todo until measured |
|
||||
| `config-flow-test-coverage` path typo | Nit — fix filename in yaml |
|
||||
|
||||
Overall: self-assessment is trustworthy; do not mark coverage done without a number.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Audit — prioritized recommendations
|
||||
|
||||
> Snapshot: **2026-08-05**. Priorities for humans and agents.
|
||||
> P0 = do soon (risk or traction). P1 = next engineering cycle.
|
||||
> P2 = important but schedulable. P3 = niceties / when touching adjacent code.
|
||||
>
|
||||
> Status column: update in-place when an item ships (`done YYYY-MM-DD` or
|
||||
> `dropped — reason`).
|
||||
|
||||
## P0 — traction & trust (this month)
|
||||
|
||||
| ID | Action | Why | Status |
|
||||
|---|---|---|---|
|
||||
| P0-1 | Ship **demo GIF/video** on README (real product motion: glow + tap light + kiosk) | Biggest adoption lever; ROADMAP Phase 10; easy-floorplan is winning attention without our counter-demo | open |
|
||||
| P0-2 | Publish EN **forum Floorplan + Reddit** posts (drafts exist off-repo) | Social proof before/while HACS #9004 waits | open |
|
||||
| P0-3 | Refresh **README differentiation** vs easy-floorplan (server sync, areas→devices, overlays — not furniture CAD) | PRODUCT table is a month stale; narrative gap is urgent | open |
|
||||
| P0-4 | Align **write policy**: either default `admin_only=True` **or** drive `_canEdit` from the same option; fail closed if `hass.user` missing | UI↔API inconsistency; household persona assumption | open |
|
||||
| P0-5 | Keep watching **hacs/default#9004** — no code action; do not spam maintainers | Queue is months-scale; custom-repo remains the path | open |
|
||||
|
||||
## P1 — maintainability (next engineering focus)
|
||||
|
||||
| ID | Action | Why | Status |
|
||||
|---|---|---|---|
|
||||
| P1-1 | **Extract** from `houseplan-card.ts`: Plan editor, Devices editor, Decor/backdrop tools, dialogs → separate modules/components; keep pure math where it is | 8691 LOC god-object is the #1 engineering risk | open |
|
||||
| P1-2 | Enable **`noImplicitAny`** in stages (devices → logic → card shell); introduce a thin typed `Hass` facade | `strict` is currently nominal | open |
|
||||
| P1-3 | Split **`styles.ts`** by surface (view / editors / dialogs / kiosk) | 2223 LOC CSS sink | open |
|
||||
| P1-4 | Unit-test **orchestration hotspots**: `_clickDevice` policy wiring, config write-chain conflict, mode enter/exit | Smokes-only today | open |
|
||||
| P1-5 | Add **`expected_rev` (or per-key CAS)** to `layout/update` *or* document “single active editor” as the contract in ARCHITECTURE | Multi-tablet drag races | open |
|
||||
|
||||
## P2 — product depth inside SCOPE
|
||||
|
||||
| ID | Action | Why | Status |
|
||||
|---|---|---|---|
|
||||
| P2-1 | **Registry-driven room suggestions** after floors-import (bind suggested polygons/areas) | SCOPE J4; PRODUCT “next move”; moat vs card-only peers | open |
|
||||
| P2-2 | Plan-level **security glance** badge (all locked / N open) | SCOPE known gap; kiosk value | open |
|
||||
| P2-3 | Touch ergonomics pass on Plan/Devices editors | Admin-on-tablet persona | open |
|
||||
| P2-4 | Options-flow richness: expose exclude domains / LQI thresholds / clearer `admin_only` | ROADMAP Phase 8 | open |
|
||||
| P2-5 | Plan upload **auto-downscale** / max-dimension guidance | ROADMAP Phase 9; prevents huge SVG pain | open |
|
||||
| P2-6 | Replace remaining **real-house README screenshots** with synthetic | STATUS privacy watchlist | open |
|
||||
|
||||
## P3 — quality-scale & hygiene
|
||||
|
||||
| ID | Action | Why | Status |
|
||||
|---|---|---|---|
|
||||
| P3-1 | Measure backend coverage; drive toward **≥95%** or revise the goal honestly | quality_scale todo | open |
|
||||
| P3-2 | **mypy strict** (or staged) | Platinum todo | open |
|
||||
| P3-3 | `docs-troubleshooting` + `docs-examples` (Gold) | quality_scale todo | open |
|
||||
| P3-4 | Tighten MARKER_SCHEMA (`binding` pattern, hex `ripple_color`, positive decor sizes, space id regex) | Validation gaps | open |
|
||||
| P3-5 | Fix quality_scale filename (`test_ha_config_flow.py`); remove or re-wire dead card `tap_action` | Nits that confuse agents | open |
|
||||
| P3-6 | Refresh stale doc headers: ARCHITECTURE tree, UX-MODES “no code yet”, PRODUCT competitor table | Truth decay | open |
|
||||
| P3-7 | Investigate / soften `smoke_opening_measure` magnet `1e-6` placement checks | Known env-sensitive red | open |
|
||||
| P3-8 | Exception / icon translations | ROADMAP Phase 8 | open |
|
||||
| P3-9 | Resource cleanup on integration removal + YAML-mode fallback doc | ROADMAP Phase 8 | open |
|
||||
|
||||
## Explicit do-not-do (reaffirmed)
|
||||
|
||||
Do **not** prioritize these even if competitors ship them:
|
||||
|
||||
1. Furniture / wall CAD (easy-floorplan’s game).
|
||||
2. 3D / glb viewers.
|
||||
3. Vacuum clean/zone **commands** (display-only stays).
|
||||
4. Cloud sync / accounts.
|
||||
5. Music-note / directional TV ripple polish from issue #3 backlog.
|
||||
6. History rewrite to purge old house assets from git (breaks HACS tags).
|
||||
|
||||
## Suggested sequencing for an agent sprint
|
||||
|
||||
```
|
||||
Week theme A — Trust & story
|
||||
P0-3 README diff → P0-1 demo video → P0-2 forum/Reddit
|
||||
P0-4 write-policy alignment (small code + options default)
|
||||
|
||||
Week theme B — Carve the god-object
|
||||
P1-1 extract one editor (Devices is smallest) + P1-4 tests for the seam
|
||||
P1-2 noImplicitAny on the extracted module only
|
||||
|
||||
Week theme C — Moat feature
|
||||
P2-1 registry room suggestions (design in ARCHITECTURE first)
|
||||
```
|
||||
|
||||
Avoid mixing A+B+C in one PR. Distribution P0s do not require waiting on P1.
|
||||
|
||||
## Success metrics (lightweight)
|
||||
|
||||
| Metric | Now (2026-08-05) | Near-term target |
|
||||
|---|---|---|
|
||||
| GitHub ★ | 21 | 100+ after GIF + posts + HACS visibility |
|
||||
| HACS default | #9004 open | merged (external) |
|
||||
| `houseplan-card.ts` LOC | ~8691 | <5000 after first extract wave |
|
||||
| Backend coverage | unmeasured | number published in quality_scale comment |
|
||||
| Open P0 items | 5 | 0 |
|
||||
|
||||
## Pointers
|
||||
|
||||
- Market context: [`AUDIT-MARKET.md`](AUDIT-MARKET.md)
|
||||
- Quality detail: [`AUDIT-QUALITY.md`](AUDIT-QUALITY.md)
|
||||
- Gaps / matrix: [`AUDIT-FUNCTIONAL.md`](AUDIT-FUNCTIONAL.md)
|
||||
- Guard rail: [`SCOPE.md`](SCOPE.md)
|
||||
- Living ops: [`STATUS.md`](STATUS.md)
|
||||
@@ -0,0 +1,75 @@
|
||||
# Project audit — index
|
||||
|
||||
> **Audience:** future humans and agents. Read this before proposing features,
|
||||
> refactors, or go-to-market work. Snapshot date: **2026-08-05**. Product
|
||||
> version audited: **v1.58.0**.
|
||||
>
|
||||
> **Policy:** this pack supplements (does not replace) `PRODUCT.md`,
|
||||
> `STATUS.md`, `SCOPE.md`, `ARCHITECTURE.md`, `ROADMAP.md`. When they disagree
|
||||
> on *current* market numbers, prefer this pack until `PRODUCT.md` is refreshed.
|
||||
|
||||
## Pack contents
|
||||
|
||||
| File | What it answers |
|
||||
|---|---|
|
||||
| [`AUDIT-MARKET.md`](AUDIT-MARKET.md) | Potential, demand shape, competitors, positioning, risks |
|
||||
| [`AUDIT-QUALITY.md`](AUDIT-QUALITY.md) | Implementation quality, architecture, security, tests, tech debt |
|
||||
| [`AUDIT-FUNCTIONAL.md`](AUDIT-FUNCTIONAL.md) | Feature integrity, systematicity, claim↔code parity, gaps |
|
||||
| [`AUDIT-RECOMMENDATIONS.md`](AUDIT-RECOMMENDATIONS.md) | Prioritized actions (P0–P3) with rationale |
|
||||
|
||||
## Executive verdict (one screen)
|
||||
|
||||
**House Plan is a high-craft, scope-disciplined product in a niche that suddenly
|
||||
got a fast-growing peer.** Engineering quality (validation, tap security, CI
|
||||
layers, quality-scale honesty, docs discipline) is well above typical HACS
|
||||
cards. The dominant risks are no longer “can we build it?” — they are
|
||||
**discoverability**, **maintainability of a 8.7k-LOC Lit god-object**, and
|
||||
**losing the GUI-floorplan narrative to easy-floorplan** (≈430★ vs our ≈21★
|
||||
as of 2026-08-05; a month earlier PRODUCT.md listed easy-floorplan at 11★).
|
||||
|
||||
| Dimension | Grade | One-line |
|
||||
|---|---|---|
|
||||
| Product mission / scope discipline | **A** | SCOPE.md is unusually sharp; non-goals held |
|
||||
| Feature depth vs mission | **A−** | Jobs J1–J7 closed; a few polish gaps |
|
||||
| Implementation quality (backend) | **A−** | Strong WS/HTTP/auth/file races; coverage % still todo |
|
||||
| Implementation quality (frontend) | **B** | Pure modules good; card shell is a maintainability bomb |
|
||||
| Test strategy | **A−** | 4 layers + smoke policy; human matrix stale |
|
||||
| Competitive moat (technical) | **A−** | Server-side storage + area-bound rooms still unique |
|
||||
| Competitive position (market) | **C+** | Traction lagging the wave; HACS default still queued |
|
||||
| Distribution / social proof | **C** | Demo stand exists; forum/Reddit/GIF still open |
|
||||
| Bus factor / docs | **B+** | Excellent docs; single maintainer |
|
||||
|
||||
**Do not** expand into 3D, furniture CAD, vacuum commands, or cloud — SCOPE
|
||||
forbids them and competitors already own parts of that surface. **Do** close
|
||||
the distribution gap and keep the moat (registry depth, multi-client storage,
|
||||
overlays that feel like a home — not a drawing app).
|
||||
|
||||
## How agents should use this
|
||||
|
||||
1. Before a feature: check `SCOPE.md` → then `AUDIT-FUNCTIONAL.md` gaps → then
|
||||
`AUDIT-RECOMMENDATIONS.md` priority.
|
||||
2. Before a refactor: read `AUDIT-QUALITY.md` top-10 debt; prefer extracting
|
||||
from `houseplan-card.ts`, not rewriting working pure modules.
|
||||
3. Before go-to-market or README claims: read `AUDIT-MARKET.md` — star counts
|
||||
and competitor maturity change monthly; re-verify with GitHub API.
|
||||
4. After acting on a P0/P1 item: update the relevant AUDIT file’s “Status”
|
||||
line in the same commit (short note + date), and bump STATUS.md watchlist
|
||||
if the project-level state changed.
|
||||
|
||||
## Method
|
||||
|
||||
- Read: PRODUCT, STATUS, ARCHITECTURE, ROADMAP, SCOPE, UX-MODES, TESTING,
|
||||
CONTRIBUTING, quality_scale.yaml, manifest, key `src/` + `custom_components/`
|
||||
modules.
|
||||
- Metrics: `wc -l`, bundle size, `npm`/`pytest` inventory, GitHub API star
|
||||
counts (2026-08-05), hacs/default#9004 state.
|
||||
- Code-quality pass: god-object sizing, auth UI↔API, tap-action model,
|
||||
validation parity, test layer map.
|
||||
- Explicitly **not** a full security penetration test or coverage measurement.
|
||||
|
||||
## Related living docs
|
||||
|
||||
- Market rationale (older): `PRODUCT.md` — refresh after this audit lands.
|
||||
- Guard rail: `SCOPE.md`
|
||||
- Current ops snapshot: `STATUS.md`
|
||||
- Design: `ARCHITECTURE.md`, `CANVAS.md`, `BACKDROP.md`, `VACUUM.md`, `SUN.md`
|
||||
+21
-9
@@ -3,6 +3,15 @@
|
||||
*Written 2026-07-05. Sources: GitHub API star counts and HA docs verified 2026-07-06;
|
||||
see links inline. Update this file when the landscape shifts.*
|
||||
|
||||
> **2026-08-05 refresh.** A full audit pack now lives under
|
||||
> [`docs/AUDIT.md`](AUDIT.md) (market / quality / functional / recommendations).
|
||||
> **Critical market change:** [easy-floorplan](https://github.com/nicosandller/easy-floorplan)
|
||||
> grew from **11★ → ≈430★** in ~one month and is a real GUI peer — the July claim
|
||||
> that the niche is “currently unoccupied” is **obsolete**. Our technical moat
|
||||
> (server-side integration, area-bound rooms, overlays, quality-scale) still
|
||||
> holds; traction and messaging do not. Prefer [`AUDIT-MARKET.md`](AUDIT-MARKET.md)
|
||||
> for current competitor numbers until this file is rewritten.
|
||||
|
||||
## What the product is
|
||||
|
||||
An interactive floor plan for Home Assistant delivered as one HACS package:
|
||||
@@ -23,7 +32,7 @@ live robot vacuums, en/ru localization). GUI-first: no YAML, no hand-made SVG.
|
||||
| [zigbee-floorplan-card](https://github.com/TheLarsinator/zigbee-floorplan-card) | 71 | LQI over a plan image | single-purpose; validates our LQI feature |
|
||||
| [kishorviswanathan/ha-floorplan](https://github.com/kishorviswanathan/ha-floorplan) (2026-01) | 155 | external web editor → YAML export | editor outside HA, still YAML at runtime |
|
||||
| [Padraigggs-ha-interactive-floorplan](https://github.com/Padraiggg/Padraigggs-ha-interactive-floorplan) (2026-03) | 41 | editor+viewer cards, "no YAML" | weeks old, card-only, no server-side integration |
|
||||
| [easy-floorplan](https://github.com/nicosandller/easy-floorplan) (2026-05) | 11 | draw walls/furniture in the card | drawing-centric, immature |
|
||||
| [easy-floorplan](https://github.com/nicosandller/easy-floorplan) (2026-05) | 11→**≈430 by 2026-08-05** | draw walls/furniture in the card | drawing-centric (still our non-goal) but **no longer immature** — fastest GUI peer; see AUDIT-MARKET |
|
||||
|
||||
**Demand evidence:** a dedicated [Floorplan forum category](https://community.home-assistant.io/c/third-party/floorplan/28);
|
||||
the "100% Floorplan UI" mega-thread (500k+ views); a visible 2025–2026 wave of new
|
||||
@@ -42,14 +51,17 @@ hundreds of stars in the first year *if* discoverability is solved (HACS default
|
||||
demo GIF + forum post). Bubble Card (4.4k★) proves polished GUI cards can go
|
||||
quasi-mainstream; ha-floorplan's 1.5k★ with a hostile workflow shows the demand floor.
|
||||
|
||||
**Unique position — currently unoccupied.** Nobody else combines: server-side config
|
||||
(integration + `.storage`, survives dashboard edits, shared across users/devices,
|
||||
optimistic locking, live multi-client sync) + in-card room polygon editor bound to HA
|
||||
areas + curated auto-placement + drag layout + LQI/temperature overlays + config flow +
|
||||
en/ru localization + CI/quality-scale discipline. The newcomers are card-only toys so
|
||||
far; the incumbent is powerful but YAML/SVG-locked. Our moat grows if we integrate
|
||||
deeper with the areas/floors registry (Phase 9) — that is the direction HA core itself
|
||||
is signalling with the native Areas dashboard.
|
||||
**Unique technical position — still real; market exclusivity — gone.** Nobody else
|
||||
combines: server-side config (integration + `.storage`, survives dashboard edits,
|
||||
shared across users/devices, optimistic locking, live multi-client sync) + in-card
|
||||
room polygon editor bound to HA areas + curated auto-placement + drag layout +
|
||||
LQI/temperature/glow/sun/vacuum overlays + config flow + en/ru localization +
|
||||
CI/quality-scale discipline. The incumbent (ha-floorplan) is still YAML/SVG-locked.
|
||||
But **easy-floorplan** (2026-08) is a shipping GUI card with an order of magnitude
|
||||
more stars than us — card-only / furniture-drawing, yet owning the “no YAML” mindshare.
|
||||
Our moat grows if we integrate deeper with the areas/floors registry (Phase 9) and
|
||||
*tell that story* in the README/demo — that is the direction HA core itself is
|
||||
signalling with the native Areas dashboard.
|
||||
|
||||
**Risks.**
|
||||
1. *HA core ships a native spatial plan.* The Areas dashboard is grid-based today, but
|
||||
|
||||
@@ -148,6 +148,11 @@
|
||||
|
||||
## Open items / watchlist
|
||||
|
||||
0. **Full project audit (2026-08-05)** — pack at [`docs/AUDIT.md`](AUDIT.md)
|
||||
(market, quality, functional integrity, prioritized recommendations). Key
|
||||
takeaway: engineering depth is strong; **easy-floorplan ≈430★** is now the
|
||||
traction threat; P0s are demo GIF + forum posts + write-policy UI↔API align.
|
||||
Agents: read the pack before proposing features or refactors.
|
||||
1. **hacs/default PR #9004** — accepted by the bot into the review queue ('New default
|
||||
repository' label). Minor issues ⇒ the bot drafts the PR (fix and re-ready).
|
||||
2. GitHub auth: fine-grained PAT (Contents R/W, issued 2026-07-23) in the sandbox
|
||||
|
||||
Reference in New Issue
Block a user