houseplan-card/docs/superpowers/specs/2026-08-05-open-spans-delete-design.md

# Open spans + wall-centric Delete — design

> Superseded on 2026-08-06 by the accepted UX-02 decision: opening a boundary,
> closing a boundary, merging rooms, and deleting a room are separate tools.
> This file remains only as the historical rationale for the original open-span
> implementation; current work is tracked in GitHub Issues + Project v2.

Status: **approved in chat** (2026-08-05). Implementation plan follows after
spec review.

## Goal

Replace whole-boundary open-wall toggle with **partial virtual stretches**
(anchor → second point on a shared wall), and make **Delete** operate on walls
(close virtual → merge / delete room) with confirmation.

## Current behaviour (baseline)

- Tool «Открытая граница»: one click toggles `room.open_to` for a room pair;
  **all** `sharedBoundary` stretches between the pair become virtual.
- Tool «Удалить»: click inside a room → confirm → delete room.
- No geometric open-span storage; light zones use `open_to` only.

## Decisions (from brainstorming)

| Topic | Decision |
|-------|----------|
| Data model | Approach **1**: `space.open_spans` + keep `open_to` as connectivity index |
| Open target | Shared wall only; outer wall → toast |
| Gesture | Click1 = anchor P1; click2 = P2 on same edge; P2 clamped to nearest corners either side of P1 |
| Cursor (openwall) | **crosshair** (same as Draw), not pointer |
| Snap | Corner / existing open joint first; else grid projected onto the wall |
| Close virtual | Both openwall (click on span) and Delete (first hit on span) |
| Thickness on open | Clear `walls[]` cm on covered keys immediately |
| Thickness on close | Inherit cm from remaining solid collinear part of same wall; if none → `DRAW_WALL_DEFAULT_CM` (15 cm / imperial) |
| Delete + virtual | First click closes span (no confirm) |
| Delete + shared solid | Confirm → **merge** the two rooms along the **entire** shared boundary |
| Delete + outer wall | Confirm → **delete room** |
| Delete + inside room | Same as outer: confirm → delete room |
| Merge / delete room | Always `confirm()` |
| Openings on virtual | **Forbidden**; remove any openings on a span when it becomes virtual; cannot place new ones there |
| Legacy `open_to` | On read, treat full `sharedBoundary` of the pair as open spans; persist `open_spans` on first save/edit |

---

## §1 Data model

### Storage (per space)

- `open_spans: Array<{ key, … }>` — geometric virtual stretches. Keying aligns
  with `walls[]` (quantised midpoint + direction mod 180°). Store enough to
  recover segment endpoints after rekey (explicit `a`/`b` normalised coords
  and/or length along the edge — implementation detail in the plan).
- `rooms[].open_to: string[]` — symmetric room-id links for
  `openZoneOf` / glow (unchanged consumer API).

### Invariants

1. A span exists only on a **shared** boundary of exactly two rooms.
2. While a pair has ≥1 span → both rooms list each other in `open_to`.
   Removing the last span clears the link.
3. An open span and a positive `walls[]` thickness on the same covered keys
   do not coexist: opening clears thickness; closing restores per rules above.
4. Legacy: `open_to` present, `open_spans` absent/empty → **read path** expands
   each linked pair to its full `sharedBoundary` segment list as virtual spans;
   write them into `open_spans` on the next config save that touches the space
   (or any openwall/delete edit).
5. Geometry lifecycle: resize / undo / scale / split / merge **rekey** spans
   like walls; unmatched keys degrade silently; merge of a pair drops spans
   between those two rooms.

---

## §2 Gestures

### Tool: Open boundary (`openwall`)

1. **Hover** on a shared solid wall: highlight eligible wall; cursor
   **crosshair**. Outer wall: no “hot” affordance beyond default crosshair;
   click → toast (shared only).
2. **Click1**: anchor P1 on the wall (snap: corner/joint → else grid on edge).
   Remember the edge and nearest corners L, R along that edge.
3. **Preview**: segment P1→cursor, clamped to [L, R] on the same edge.
4. **Click2**: P2 in [L, R]. If length below minimum → toast, clear anchor.
   Else write span, clear thickness on covered keys, remove openings on the
   span, refresh `open_to`.
5. **Click on existing virtual span**: close that span; restore thickness
   (neighbour solid / default 15); no confirm.
6. **Esc**, click away, tool change, leave markup: clear in-progress anchor.

### Tool: Delete (`delroom` — wall-centric)

Hit priority: virtual span → shared solid wall → outer wall → point inside room.

| Hit | Action |
|-----|--------|
| Virtual span | Close span (no confirm), same as openwall |
| Shared solid wall | Confirm → merge both rooms (entire shared boundary) |
| Outer wall | Confirm → delete the room that owns that outer edge |
| Inside room | Confirm → delete that room |
| Miss | No-op (optional light toast) |

After closing a virtual span, a later Delete click on that now-solid shared
wall runs the merge path (with confirm).

---

## §3 Thickness, openings, errors, tests

### Thickness

- Opening a span: strip `walls[]` entries (or null cm) for keys covered by the
  span (atomic collinear pieces under the segment).
- Closing a span: if a collinear solid remainder of the same wall still has cm,
  copy that cm onto the newly solid stretch; else apply `DRAW_WALL_DEFAULT_CM`.
- Wall-thickness tool continues to refuse open stretches (toast).

### Openings (doors / windows)

- **Not allowed** on virtual spans.
- When a stretch becomes virtual: **delete** any openings whose centre lies on
  that stretch (same association rules as wall bodies / angle-aware hit).
- Opening tool: refuse placement on a virtual span (toast).

### Errors / cancel

- Outer / not-a-wall / too short / click2 off the anchored edge → toast and
  clear the in-progress anchor.
- Merge and room delete always go through `confirm()`; cancel → no-op.
- Saves stay optimistic like other plan edits.

### Testing

**Unit**

- Clamp P2 to nearest corners; min length.
- Span write ↔ `open_to` add/remove.
- Thickness clear on open; restore from neighbour / default 15 on close.
- Legacy `open_to` → virtual full sharedBoundary spans.
- Rekey after edge move / scale; degrade orphans.
- Opening removal when span opens; placement blocked on virtual.

**Smoke**

- Anchor + P2 → dashed span; glow crosses only when span links rooms.
- Close via openwall and via Delete.
- Delete merge / delete-room confirms; outer open attempt toasts.
- Crosshair cursor in openwall tool.

### Docs / i18n

- Update `docs/ARCHITECTURE.md` (open boundaries), `WALL-THICKNESS.md` (open
  refuses thickness + clear on open), `UX-MODES` / TESTING hints, CHANGELOG.
- New toasts: shared-only, short segment, openings removed, delete/merge
  confirms copy; refresh `title.markup_openwall` / `delroom` hints.

### Out of scope

- Partial merge along only the former virtual segment (explicitly rejected: merge is whole shared boundary).
- Outer-wall virtual openings (“to outdoors”).
- Restoring thickness from pre-open snapshot (neighbour / default only).
- Changing glow math beyond “any span ⇒ rooms linked”.

---

## Implementation sketch (not a plan)

1. Pure helpers: expand legacy, clamp segment, span CRUD, thickness
   clear/restore, opening purge on span, rekey/degrade.
2. Card: openwall two-click state machine; Delete hit priority + confirms.
3. Render: dashed strokes from `open_spans` (fallback legacy expand); trim
   outlines/cuts from span list.
4. Smokes + unit tests; docs/i18n; version bump when shipping.

## Open points for the implementation plan only

- Exact JSON shape of one `open_spans` entry (`key` only vs `key`+`a`+`b`).
- Minimum segment length (e.g. `gridPitch` or fixed cm).
- Whether Delete merge reuses the existing merge-tool code path verbatim.