houseplan-card/docs/specs/373-space-card-house-fit.md

# #373 — Tight house framing for `houseplan-space-card`

Issue: [#373](https://github.com/Matysh/houseplan-card/issues/373)

## Scenario

The **home administrator** embeds `custom:houseplan-space-card` in a compact
Home Assistant dashboard for household members, a wall tablet or a phone. The
stored space also contains a large backdrop or auxiliary objects outside the
building, but this card is meant to show the house itself as large as possible.

The administrator selects a tighter frame for this one card instance. View and
kiosk consumers then see the complete structural plan without the ordinary
outer breathing room; no editor is involved.

## What the person sees before and after

Before, the static card keeps a 5% outer frame and lets non-house content widen
the view; after opting in, the complete house geometry touches the available
frame without intentional padding, while backdrop, decor, labels and devices
outside the house no longer make the house smaller.

## Problem

`renderSpaceStatic()` currently calls `spaceFrame(space, placed, 0.05)` (or the
per-edge #372 variant for `title: ""`). That frame is deliberately the broad
content frame from `docs/CANVAS.md`: rooms, the transformed backdrop and visible
placed objects can all vote, and the result is padded by 5% of its longer side.
This is correct for the existing default and for the full interactive card, but
it wastes scarce dashboard area when the embedded card is intended to show the
building rather than every auxiliary object.

The reporter chose the non-cropping alternative in the latest issue comment:
remove the 5% padding, keep all house geometry visible, and derive the fit from
room/house geometry instead of backdrop or decorative objects. A CSS-`cover`
mode that can crop the house is explicitly not requested.

## Scope

- only `custom:houseplan-space-card`;
- one opt-in Lovelace card setting, `fit: house`;
- visual-editor choice between the existing frame and the tight house frame;
- a zero-intentional-padding structural frame containing every rendered room,
  room wall, independent wall/draft, column, zero-thickness wall and visible
  door/window/gate symbol;
- exclusion of backdrop image, decor, room labels, device markers and their
  badges from the `house` frame vote;
- safe fallback to the existing frame when the space has no valid structural
  geometry;
- consistent geometry, themes and touch/desktop View behaviour;
- en/ru/de/fr UI strings, RU/EN user guide, architecture/canvas contract,
  changelogs and targeted tests.

## Non-scope

- any change to the full `custom:houseplan-card`, its Fit all action, View,
  kiosk, editors, zoom, pan or outlier hint;
- CSS `cover`, aspect-ratio distortion or any mode allowed to crop structural
  house geometry;
- hiding, deleting or moving backdrop, decor, labels, markers or devices;
- changing marker size, room-label position, Glow, sunlight, wall geometry,
  opening state or HA actions;
- changing the stored House Plan model, backend schema, `space.view_box`,
  config/layout revisions, exports or imports;
- arbitrary user-configurable padding values;
- changing the #372 meaning of `title: ""` in the default frame;
- automatically enabling the new mode for existing cards.

## Behaviour contract

### Public card configuration

```yaml
type: custom:houseplan-space-card
space: ground_floor
fit: house
```

1. `fit` accepts `content | house`.
2. Missing, empty or unknown `fit` resolves fail-safe to `content`.
3. `content` is the exact current behaviour: the current content voters,
   main-mass/outlier policy and 5% padding remain unchanged. Existing YAML
   without `fit` must produce the same frame.
4. `house` selects the new tight structural frame described below. It never
   becomes the implicit default.

### Tight structural frame

5. The structural frame contains the union of all finite, sane visible
   architectural extents for the selected space:
   - room polygon/rectangle floors;
   - the complete outer envelope of positive-thickness room walls;
   - independent walls, saved wall drafts and columns;
   - zero-thickness room and independent wall axes;
   - the full visible state-independent envelope of door, window and gate
     symbols, including wall jambs, leaf tips and swing arcs in either state.
     An open passage contributes through its structural wall/tunnel geometry
     and has no extra standalone symbol.
6. All structural items participate. The broad content-frame outlier vote may
   not discard a detached room or wing in `house` mode: sane structural
   geometry is part of the house and must stay visible.
7. The resolved structural union receives **zero intentional padding** on all
   four sides. Bounds still include the actual rendered wall/symbol stroke
   envelope, so “zero padding” may not clip a stroke by half its width.
8. Backdrop image, decor, room labels, device markers, value/LQI badges, pulse
   shells and purely visual Glow/sun extents do not enlarge this frame. They
   remain rendered in the same coordinate system and may be clipped when they
   lie outside the structural house frame; this is the user-confirmed trade-off.
9. The SVG, marker layer, room-label layer, backdrop, day-cycle environment and
   continuity overlay all consume the single resolved `viewBox`. Nothing is
   independently translated or scaled after the fit is chosen.
10. If no valid structural item exists (for example an image-only or empty
    space), `house` falls back atomically to the ordinary `content` frame. It
    must not create an empty, zero-sized, NaN or infinite `viewBox`.
11. Structural computation is state-independent. Opening sensor changes,
    device state updates, Glow animation and language/theme changes do not
    resize the card or move the house inside it.

### Interaction with existing options

12. `title`, `show_button`, `light_pools`, state/value options and footer deep
    links retain their existing semantics.
13. With `fit: content`, explicit `title: ""` keeps #372: only the top 5%
    padding disappears, while side/bottom padding remains.
14. With `fit: house`, all four intentional frame paddings are already zero;
    `title: ""` only removes the header and does not change the structural
    `viewBox` further.

## UX and accessibility

- The Lovelace visual editor exposes one dropdown labelled **Framing** with:
  - **All visible content** → `content`;
  - **Tight to house geometry** → `house`.
- A missing legacy value is displayed as **All visible content**. A subsequent
  visual-editor save may materialise `fit: content`; this is semantically
  lossless.
- No crop/cover choice is shown.
- The schematic remains `pointer-events:none`, non-focusable and read-only.
  The existing footer button remains the only interactive element.
- No new hover, gesture or animation is introduced. The frame is identical on
  fine/coarse pointers, narrow/wide cards and light/dark themes.

## Data model, migration and compatibility

The field belongs only to the Lovelace card instance:

```ts
interface SpaceCardConfig {
  fit?: 'content' | 'house';
}
```

- no House Plan server-config or layout field is added;
- no model/store/schema version or backend validation changes;
- no data migration and no write to Home Assistant storage;
- old cards and old YAML remain on the `content` path;
- current code normalises only at read/render and visual-editor boundaries;
- an older frontend ignores the unknown Lovelace key and renders its historical
  content frame, without damaging House Plan data;
- rollback is therefore data-free.

## i18n

Add complete keys to `src/i18n/{en,ru,de,fr}.json` for:

- Framing;
- All visible content;
- Tight to house geometry.

The technical YAML literals `content` and `house` are not translated. Missing
translations may not leave a raw key or an unlabelled select option.

## Performance and bundle

- Frame resolution remains one bounded O(rooms + walls + openings + columns)
  pass per structural render candidate.
- HA state-only ticks reuse/calculate the same structural fingerprint; they may
  not introduce DOM measurement or `getBBox()` layout reads.
- No second hidden SVG, canvas raster scan, network request or dependency.
- Existing `fit: content` cost and output remain unchanged.
- Initial View bundle budget is not raised.

## Touch and themes

- `houseplan-space-card` is a View surface, so narrow phone and wall-tablet
  rendering is release-blocking.
- The new mode is presentation-only and must not cause horizontal overflow,
  clipped structural strokes or a zero-height card at representative 320 px
  and 900 px widths.
- Pointer/tap behaviour is unchanged; the stage stays inert and the footer tap
  target stays usable.
- Light/dark and day-cycle modes share exactly the same structural frame.

## Affected files and modules

- `src/space-card.ts` — public `fit` type/default and static-render projection;
- `src/space-editor.ts` — localised framing dropdown and legacy/default
  projection;
- `src/space-render.ts` — select ordinary vs structural frame and keep one `vb`;
- a narrow pure helper in `src/space-geometry.ts`, `src/render/opening-symbol.ts`
  or a dedicated static-frame module — finite structural items and opening
  envelopes without DOM measurement;
- `src/i18n/{en,ru,de,fr}.json` — editor labels;
- `test/**` — pure frame/config/opening-envelope regressions;
- `demo/smoke_space_card.mjs` — real-card comparison and View/touch contract;
- `docs/USER-GUIDE.md`, `docs/USER-GUIDE.ru.md`, `docs/ARCHITECTURE.md`,
  `docs/CANVAS.md` — public and canonical contracts;
- `docs/CHANGELOG.md`, `docs/CHANGELOG.ru.md` — release bullet linked to #373.

## Acceptance criteria

- **AC1 — default compatibility:** missing/empty/unknown `fit` and explicit
  `fit: content` produce the same numeric `viewBox`, stage aspect and #372
  title interaction as the pre-change control fixture. **Evidence:** unit tests
  plus `demo/smoke_space_card.mjs` comparing four configurations.
- **AC2 — tight structural frame:** on a fixture with an oversized transformed
  backdrop, far decor, far marker and room label, `fit: house` excludes those
  items from its bounds, removes all four intentional 5% pads and yields a
  strictly tighter frame than `content`. **Evidence:** pure unit assertions and
  browser smoke over the rendered SVG `viewBox`.
- **AC3 — no structural crop:** rooms, positive/zero walls, independent walls,
  drafts, columns and door/window/gate envelopes in their extreme states are
  all within the `house` frame including visible strokes. **Evidence:** pure
  geometry table tests and a browser semantic-pixel/bounds witness that fails
  when any structural edge is clipped.
- **AC4 — stable and safe fallback:** an empty space, image-only space,
  collinear structural geometry and invalid/unknown `fit` always produce a
  finite positive frame; image-only `house` equals the ordinary content frame.
  Opening/device state ticks do not change it. **Evidence:** unit + browser
  smoke with state substitution.
- **AC5 — editor/i18n contract:** the GUI displays the default and house choices
  in en/ru/de/fr, saves exact literals, reloads them, and never offers cover.
  **Evidence:** unit/source contract plus browser editor smoke or review of an
  existing faithful `ha-form` harness.
- **AC6 — View/touch parity:** tight mode renders without horizontal overflow
  at 320 px and 900 px, in light/dark/day-cycle, keeps the stage inert and keeps
  the footer action unchanged. **Evidence:** targeted browser smoke and code
  review.
- **AC7 — performance:** state-only rerenders do not perform DOM geometry reads
  and the structural pass stays bounded; bundle budget remains green.
  **Evidence:** code review, `npm run bundle:budget` and existing static-card
  performance profile before beta.
- **AC8 — documentation and release:** RU/EN guide documents `fit`, its default,
  the intentional auxiliary-object crop and its interaction with `title: ""`;
  architecture/canvas docs describe the second static-only frame; both
  changelogs link #373. **Evidence:** docs/process gates and code review.

## Automated test plan

1. Pure unit: validate the `fit` resolver (`undefined`, `content`, `house`,
   unknown) and prove the default branch retains current padding.
2. Pure unit: build a synthetic structural scene containing a polygon room,
   thick wall envelope, zero wall, independent wall/draft, column and every
   opening type; compare exact finite structural bounds and zero padding.
3. Pure unit: substitute closed/open/extreme opening amounts and prove the
   state-independent envelope and resulting frame do not change.
4. Pure unit: add far backdrop/decor/marker/label items; prove ordinary content
   widens while house bounds do not. Add a detached valid room and prove it is
   retained rather than outlier-rejected.
5. Pure unit: empty/image-only/collinear/invalid inputs fall back to a finite
   positive ordinary frame.
6. Extend `demo/smoke_space_card.mjs` with control, explicit `content`, `house`
   and `house + title:""` cards. Assert numeric frames, no clipped structural
   edge, common overlay coordinates, unchanged footer deep link and inert stage.
7. Repeat tight mode at narrow light and wide dark widths and change a door
   sensor/device state; the viewBox remains stable and no overflow appears.
8. In the implementation cycle run `npm run typecheck`, `npm test`,
   `npm run build`, `npm run bundle:sync`, `npm run bundle:budget`,
   `node scripts/no-new-any.mjs --base origin/dev --head HEAD`,
   `node scripts/check-docs.mjs`, smoke selection and the named target smoke.
   Run full golden/smoke/performance and exact-SHA Linux Validate before beta,
   following the process.

## Risks

- **Zero padding clips the outer half of a wall or opening stroke.** Mitigated
  by structural visible-envelope math and AC3, not by reintroducing arbitrary
  padding.
- **Backdrop/decor still votes through `spaceFrame()`.** Mitigated by a separate
  explicit structural-item path and AC2; the ordinary helper remains untouched.
- **Stateful door movement resizes the card.** Mitigated by one conservative
  state-independent opening envelope and AC3/AC4.
- **A detached building is mistaken for an outlier.** Mitigated by using all
  sane structural items for the house union and the detached-room test.
- **The default changes accidentally.** Mitigated by an explicit resolver whose
  fallback is `content`, numeric compatibility tests and no implicit opt-in.
- **Auxiliary content is intentionally clipped but undocumented.** Mitigated by
  the GUI wording, guide warning and AC8.
- **Static and full cards drift.** The new path is static-only by contract; all
  existing shared geometry primitives stay canonical, while the full card's
  content frame remains unchanged and covered by existing canvas tests.
- **Docs screenshot fingerprint changes after `src/**`.** The canonical Docs
  screenshots workflow/acceptance remains required by the repository process.

## Rollback

Remove the `fit` projection/editor option and always call the existing content
frame path. Existing cards without the option are already on that path; cards
with `fit: house` become ordinary content-framed cards when read by the rolled
back frontend. No House Plan config/layout data, migration or cleanup is needed.

## Release artifacts

- `docs/CHANGELOG.md` and `docs/CHANGELOG.ru.md`: opt-in tight house frame with
  a link to #373;
- `docs/USER-GUIDE.md` and `docs/USER-GUIDE.ru.md`: YAML/table/default,
  auxiliary crop and `title: ""` interaction;
- `docs/ARCHITECTURE.md` and `docs/CANVAS.md`: static-only structural frame and
  its relation to the canonical content frame;
- targeted `demo/smoke_space_card.mjs` result with numeric and semantic visual
  evidence for standard/tight, narrow/wide and light/dark;
- full existing golden verify to prove no default-path visual regressions; a
  new baseline is added only if targeted semantic evidence cannot make AC2/AC3
  unambiguous, and may be accepted only from the reviewed complete Linux
  artifact;
- canonical Docs screenshots artifact accepted with
  `npm run docs:accept -- --reviewed --from=<artifact>` because `src/**` changes;
- no backend, migration or security artifact; initial bundle budget and the
  static-card performance profile remain mandatory before beta.

## Assumptions accepted provisionally; reviewer may change freely

- the public literals are `fit: content | house`; names of internal helpers and
  exact file placement are technical choices;
- `content` is explicit current semantics rather than a newly invented mode;
- “house geometry” means the complete structural list in contract item 5, not
  room polygons alone, because room-only bounds would cut thick outer walls and
  opening leaves;
- objects deliberately excluded from bounds remain in DOM/SVG and may be
  clipped; they are not hidden or deleted;
- `house` falls back to `content` when no structure exists rather than framing
  an arbitrary stored square or rendering an empty card;
- a conservative analytic opening envelope is acceptable if it is tight to the
  maximum rendered symbol and state-independent; DOM `getBBox()` is forbidden;
- exact synthetic fixture names and sub-pixel tolerances belong to the test
  implementation, provided a one-pixel crop causes a deterministic failure.