houseplan-card/docs/RESIZE.md

# Room resize — the spec (source of truth)

Status: approved by the owner 2026-08-01. Dev-branch feature, **no
release**. Scope decisions final: a dedicated tool mode, wall-drag with
shared walls always moving together, a corner-scale frame for the
selected room, live numbers (wall lengths + room areas), grid snap,
Esc-cancel, one drag = one undo step.

## Principle

Until now room geometry could only be changed by split/merge or by
redrawing the outline — there was no vertex or wall dragging at all
(the `.rlhandle` corners belong to the room LABEL card, not to the
room). Resize adds exactly two mechanisms, both living ONLY inside a
dedicated Plan-editor tool «Изменение размера комнат» (`_tool ===
'resize'`). In every other tool the plan looks and behaves exactly as
before — no handles, no new hit areas.

## Mechanism A — wall drag

- Every visible room shows a small handle at the midpoint of every
  wall (handles for all rooms at once — owner's UX pick). The visible
  glyph is a compact icon — a wall segment with two arrows pointing
  perpendicular to it (the directions the wall drags), rotated to the
  wall's orientation; accent ink over a `--hp-bg` halo. It is half the
  size of the old circle, but the HIT area is an invisible circle of
  the original finger-sized radius (derived from `view.w` like
  `.vacfithandle`), so touch targets did not shrink. Cursor: `grab`,
  `grabbing` while dragging.
- Dragging a handle moves the wall along its outward normal; **both
  ends of the edge translate together** (the wall stays parallel to
  itself; adjacent walls stretch/shrink). Works for any polygon
  (L-shaped included) and for legacy `x/y/w/h` rectangles — those are
  converted through `roomPoly` and are **saved back as `poly`**.
- The moved wall position snaps to the drawing grid (`snapToGrid`,
  same pitch as the draw tool).
- **Handles own the hit test** (HP-1550-04): inside the resize tool
  openings are not editable — their transparent hit area is inert
  (`pointer-events: none`) and the resize layer renders above the
  openings, so a door sitting exactly at the midpoint of a wall can
  never shadow that wall's handle. A drag of such a wall carries the
  door along through the normal anchor pipeline; clicking over a door
  falls through to room picking. Every other Plan tool keeps the
  openings interactive exactly as before.

## Shared walls — ALWAYS together

If a stretch of the dragged wall coincides with a neighbour's boundary
(collinear overlap with an epsilon, the `sharedBoundary` notion), the
coinciding stretches of the neighbour move synchronously: your room
grows — the neighbour shrinks. Gaps and overlaps cannot appear by
construction.

Partial contact (T-junctions): only the coinciding stretch of the
neighbour moves. Where the stretch ends inside a neighbour wall, new
vertices are inserted into the neighbour outline, which may legally
become L-shaped. All of this is shown as a live preview during the
drag. On commit collinear leftovers are simplified away
(`simplifyPoly`), so geometry stays clean.

## Stops (the wall stops dead)

1. **Minimum size** — neither the own room nor a shrinking neighbour
   may get thinner than ~30 cm (`MIN_ROOM_CM`, expressed in canvas
   units through `cell_cm`). The measure is orientation-independent
   (HP-1550-02): for a wall drag it is the smallest perpendicular
   distance from the moved stretch to any part of the room boundary
   inside the band the stretch sweeps along its normal — vertices and
   crossing walls count whether parallel or not (a triangle's apex, a
   slanted obstacle), while collinear remainders and the step corners
   a T-junction inserts at the very ends of the stretch do not. For
   the scale frame it is the TRUE minimum width of the outline
   (rotating calipers over the convex hull) scaled by `k` — the
   axis-aligned bbox is never consulted, so rotation cannot hide the
   short side. Rooms that are ALREADY thinner keep their clearance
   (the drag may improve it, never worsen it).
2. **Self-intersection** — a wall never passes through the opposite
   side; the outline must stay a simple polygon with its orientation
   and a positive area.
3. **Foreign rooms** — a growing wall stops when it would overlap a
   room that is not a shared-wall neighbour (`roomsOverlap`; touching
   walls are legal, crossing is not).
4. **Island rooms** — islands inside the room (`islandsOf`) must stay
   fully inside; a wall shrinking onto an island stops.
5. **Openings are anchors** — a door/window ON the moving stretch
   travels with the wall (its `openings[].x/y` centre is shifted, the
   angle is unchanged). A wall that carries openings cannot get too
   short for them: every opening previously sitting on a wall of an
   affected room must still fit fully on some wall afterwards — for
   the own room AND for the neighbour.

## Mechanism B — the scale frame

- In the resize tool a click inside a room SELECTS it: a dashed
  bounding frame with 4 corner handles appears.
- Dragging a corner scales ALL vertices proportionally (uniform
  similarity) about the opposite bbox corner — the same maths family
  as the vacuum fit panel (`reanchorFit`), only without rotation.
- The same stops apply (minimum size, foreign overlap, islands,
  openings; self-intersection is impossible under a similarity).
- **The one exception to «shared walls always together»:** a scale
  breaks collinear coincidence (walls move apart at an angle-preserving
  ratio, not along a normal), so neighbours are NOT dragged along.
  Growing into a neighbour simply stops the scale (the neighbour is a
  wall to hit); shrinking away from a neighbour legally opens a gap.
- Openings exclusive to the scaled room follow the transform
  (position scales, physical length does not); openings on a wall
  shared with an unchanged neighbour stay with the neighbour's wall.

## Live numbers

While a handle is being dragged:

- length badges (`.measurelabel` style, `segmentCm`/`formatLength`,
  metric or imperial per the HA unit system) on the dragged wall and
  its two adjacent walls;
- the room area in m² (`polygonArea` × scale²) at the room centre,
  live; when a shared wall is dragged — the areas of BOTH rooms
  (owner picked «стены + площадь»);
- Esc cancels the current drag and puts the original geometry back;
- releasing the handle (pointerup) commits: one write through the
  standard debounced `_saveConfig` path;
- `pointercancel` / `lostpointercapture` (the system interrupted the
  stream: app switch, palm rejection) takes the CANCEL path, never the
  commit path — snapshot geometry back, no undo step, no write
  (HP-1550-03).

## Preview vs commit (HP-1550-01)

The live drag preview never touches the shared `_serverCfg`: it lives
in a separate overlay (`_rszPreview`) that `_curSpaceCfg`/`_renderCfg`
substitute into every render. Config writes are serialized and read
`_serverCfg` at the moment they run (HP-1454-03), so a debounced write
still queued from a previous edit can fire mid-drag — with the overlay
it carries only committed geometry. The overlay moves into the real
config exactly once, on pointerup; a cancel (Esc, pointercancel) just
drops the overlay, leaving nothing to restore and nothing to write.

## Undo

One operation (handle release that changed something) = one undo step.
The plan editor has no committed-operation undo stack (Ctrl+Z/Esc only
walk back draw/split points), so the resize tool keeps its own stack
of pre-drag snapshots (rooms + openings of the space, capped at 30)
and Ctrl+Z/⌘Z pops it while the tool is active.

## Out of scope / invariants

- Device positions are not touched; the room settings button (pole of
  inaccessibility) recomputes itself from the new outline.
- Saving goes through the standard config path (`houseplan/config/set`
  with `expected_rev`); backend validation already covers polygons
  (`_GEOM` ±4, `MAX_POLY_POINTS` 500) — inserted neighbour vertices are
  just polygon points, openings keep their schema, nothing new to
  validate server-side.
- Touch: handles are finger-sized, use pointer capture and swallow
  `pointerdown`, so the stage pan/pinch never fights a handle drag.
- The label-card corners (`.rlhandle`, `_rlResizeDown`) are untouched.

## Geometry home

All pure geometry lives in `src/resize.ts` (edge normals, edge move,
shared-span search and vertex insertion, all stops — including the
orientation-independent `minSpanClearance` band measure and the
`minPolyWidth` calipers width — the scale clamp, area formatting)
under node:test units in `test/resize.test.mjs`;
`src/houseplan-card.ts` only wires pointers, the preview overlay,
badges and undo.