houseplan-card/legacy/specs/264-resize-controller.md

Issue #264 — отдельный контроллер Resize и commit-инвариант кладки

• Issue: https://github.com/Matysh/houseplan-card/issues/264
• Статус: первая редакция для независимого ревью; канонический статус задаётся метками issue
• Тип / приоритет: tech-debt / P1
• Оценка: пользовательская ценность 2/10; ценность для разработки 9/10; сложность 7/10; риск 8/10
• Класс изменения: A + B + C, полный процесс
• User-Visible: no — DOM, пиксели, тексты, жесты и persisted config не меняются
• Связано: #34, #253, #254, #277; docs/RESIZE.md, docs/specs/034-frontend-decomposition.md

1. Сценарий, персона и проблема

Домашний администратор на desktop открывает редактор плана существующего этажа, выбирает Resize и перетаскивает обычную либо общую стену. Для него этот слайс обязан быть полностью незаметен: допустимость ручки, движение, измерения, сохранение, отмена и повтор остаются теми же, что в выпущенном контракте #277. Задача нужна не ради нового пользовательского шага, а чтобы следующие изменения этого критичного пути можно было делать и проверять изолированно.

После #277 Resize имеет безопасный fixed-topology контракт, но его конечный автомат по-прежнему встроен в HouseplanCard: там одновременно живут pointer session, immutable snapshot, eligibility cache, live preview, измерения, fail-closed commit, Undo и восстановление wall-union cache. Любая следующая правка этого инструмента снова меняет крупнейший компонент проекта и должна доказывать корректность переходов по разрозненным полям _rsz*.

#264 — refactor-only слайс канонической декомпозиции #34. Он выносит состояние и переходы одного инструмента в отдельный typed controller. Геометрические формулы остаются в src/resize.ts, а Lit/DOM, перевод, toast, config/history, серверная запись и рендер остаются у корневого компонента.

Одновременно transaction boundary получает production-инвариант сохранения wall records. Именно нарушение этого свойства вызвало #253. Сейчас похожая проверка существует как отдельная реализация в CLI-инвариантах и как inline сравнение внутри Resize; после #264 алгоритм находится в одном production- модуле и используется обоими путями.

Что человек увидит

Ничего нового. До и после изменения:

• те же handles, disabled reasons, preview, подписи длины/площади и cursor;
• те же границы safe drag, snap и clamp;
• те же commit, Cancel/Escape, pointercancel/lostpointercapture и Undo/Redo;
• те же пиксели View, Plan и остальных редакторов;
• тот же JSON успешного Resize byte-for-byte.

Если внутренний инвариант нарушен, сохраняется уже принятое в #277 поведение: preview останавливается либо commit отменяется с существующим безопасным сообщением; config write и Undo-команда не создаются.

2. Зафиксированные решения и исходный контракт

1. #277 уже реализован и выпущен. Его ТЗ и docs/RESIZE.md являются функциональным каноном; #264 не пересматривает eligibility, geometry, disabled reasons, preview или commit semantics.
2. Старый продуктовый вопрос из тела #264 закрыт решением #277: при любом нарушении инварианта жест fail closed — без частичного применения, диагностики с пользовательскими данными, write или Undo.
3. Владелец явно выбрал #264 следующим слайсом, поэтому прежнее сомнение «сначала небольшой диалог или Resize» закрыто.
4. Schema/model version, compatibility fields и миграции не меняются.
5. allowClear для Resize всегда false. Очистка толщины относится к другому явному инструменту и не может быть побочным эффектом перемещения стены.
6. Opened/disabled handles и мышь/клавиатура/touch сохраняют поведение #277. Осознанная desktop-first деградация редакторов из docs/TOUCH-SUPPORT.md не расширяется.
7. _rszSel не имеет renderer-потребителя после #277, но не является полностью мёртвым: клик по площади комнаты запоминает latent selection, после чего первый Escape очищает её и оставляет Resize активным, а второй возвращает neutral Draw. Это наблюдаемое keyboard-поведение сохраняется. Само поле уезжает из root в controller как selectedRoomId; warm viewport продолжает переносить это session-only значение через typed getter/restore, не меняя сериализуемый config.

Открытых продуктовых вопросов нет.

3. Термины

• Root / host — HouseplanCard, composition shell, владелец браузерных и инфраструктурных side effects.
• Controller — новый ResizeController, единственный владелец состояния жеста и допустимых переходов.
• Adapter / port — typed callback, которым root предоставляет controller текущие данные или выполняет host-specific операцию без обратной записи в controller internals.
• Geometry snapshot — immutable JSON-снимок SpaceGeometryState перед pointerdown плюс identity/fingerprint, с которым сверяется pointerup.
• Preview candidate — полный exact space candidate, построенный только из pre-drag snapshot; он никогда не является частью _serverCfg.
• Commit outcome — typed значение controller, разрешающее root применить ровно этот preview candidate одной geometry-командой.
• Wall record profile — мультимножество конечных числовых cm у записей walls; в exact-режиме включает 0, потому что после #306 это значимое состояние стены.

4. Архитектурная граница

4.1 Controller владеет

Новый src/resize-controller.ts владеет только Resize orchestration:

1. состояниями idle и dragging; наличие принятого preview — часть dragging, не параллельный флаг; idle дополнительно хранит необязательный selectedRoomId, который сохраняет существующую двухшаговую Escape-ветку;
2. pointer id, start point, SafeResizePlan, immutable rooms/openings/options, snapshot identity, current accepted delta, moved flag, changed room ids и однократным preview-rejection notification flag;
3. eligibility cache, ограниченным одним space/snapshot/grid context;
4. ссылкой на exact accepted preview, live measurement model и retained pre-drag wall-union token как opaque generic value;
5. переходами select/clearSelection, resolve → begin → move* → finish и begin/move → cancel; wrong pointer id даёт no-op;
6. вызовом существующих pure safeResizePointerDisplacement, snap adapter, clampSafeResize, applySafeResize и validateSafeResize в прежнем порядке;
7. правилом «failed projection сохраняет последний полный accepted preview, delta и labels»;
8. формированием typed commit | no-op | rejected | cancelled outcome.

Controller не экспортирует изменяемые поля. Root читает immutable getters/ snapshots (dragging, preview, liveLabels) и меняет состояние только публичными командами controller.

4.2 Root сохраняет

src/houseplan-card.ts остаётся владельцем:

• DOM/PointerEvent: preventDefault, stopPropagation, pointer capture, перевод координат через _svgPoint и маршрутизация событий;
• Lit reactivity и requestUpdate;
• _t, disabled-reason copy и toast;
• получение current rooms/openings/obstacles/thickness/options из модели;
• построение preview space, rekey wall metadata и wall-segment endpoints;
• common physical geometry preflight и retained wall geometry/cache;
• построение локализованных live labels и их DOM/SVG render;
• _serverCfg, _cfgEpoch, geometry command stack, suppression synthetic click, _commitPhysicalGeometry и serialized write queue;
• tool/mode/space lifecycle и сброс других инструментов.

Root handlers после выноса являются тонкими adapters: переводят Event в primitive input, вызывают controller, исполняют outcome и запрашивают render. Они не держат зеркальных _rszDrag/_rszPreview/_rszLive полей и не дублируют проверки state transition.

4.3 Что остаётся pure geometry

src/resize.ts остаётся единственным источником topology/eligibility/range/ candidate math. Controller импортирует его функции, но не копирует алгоритмы. src/resize-labels.ts остаётся единственным источником placement math.

Не создаются второй room model, второй wall model, новый render tree или общий framework контроллеров для остальных инструментов.

5. Typed ports и outcomes

Конкретные имена типов могут уточняться при реализации, но граница обязательна:

type ResizeControllerOutcome<TSpace, TSnapshot, TWallUnion> =
  | { kind: 'commit'; preview: Readonly<ResizePreview<TSpace>>;
      before: TSnapshot }
  | { kind: 'rejected'; reason: 'stale-snapshot' | 'invalid-topology'
      | 'invalid-candidate' | 'wall-records' }
  | { kind: 'no-op' }
  | { kind: 'cancelled'; restoreWallUnion: TWallUnion | null };

Controller получает через typed inputs/ports:

• current context identity и immutable snapshot;
• snap(point);
• resolve(roomId, edge) либо данные для вызова pure resolver;
• project(snapshot, candidate) → success с exact preview/retained geometry либо bounded failure reason;
• validatePreview(exactPreview) — common physical preflight на pointerup;
• measure(candidate, plan) — presentation model без DOM measurement.

Ports не получают controller instance и не могут менять его поля. Exceptions adapter'ов перехватываются на границе и превращаются в bounded fail-closed failure; exception text, ids и координаты не попадают в UI.

Root исполняет только kind: 'commit' и только один раз. Любой другой outcome сначала удаляет overlay/controller session, затем приводит render к committed модели и не вызывает _commitPhysicalGeometry.

6. Конечный автомат

Текущее состояние	Команда	Условие	Результат
idle	resolve	тот же context identity	cache hit либо один pure resolver call
idle	selectRoom	клик по площади комнаты	сохранить latent selectedRoomId, без visual/config effect
idle	escape	selectedRoomId существует	очистить selection, остаться в Resize
idle	escape	selection отсутствует	typed outcome exit-tool; root включает Draw
idle	begin	tool Resize, enabled plan	dragging, immutable session captured
idle	begin	disabled	idle, no capture/preview/write; root показывает reason
dragging	move	wrong pointer id	no-op
dragging	move	delta прежний	no-op
dragging	move	projection valid	replace exact preview/delta/labels atomically
dragging	move	projection invalid/throws	retain last accepted triple; notification only once
dragging	finish	no movement/zero delta/no preview	clear session, no-op
dragging	finish	stale snapshot, invalid topology/candidate/invariant	clear session, rejected, zero write/Undo
dragging	finish	all guards pass	clear session, one commit with exact preview
dragging	cancel/pointer cancel/lost capture/Escape/Ctrl+Z/tool/space/mode exit	matching active session	clear session, cancelled, zero write/Undo; eligible cache invalidated as today
idle	cancel/finish	—	no-op

Every transition is synchronous and deterministic for the same inputs. A late lostpointercapture after successful pointerup sees idle and cannot cancel or commit twice.

7. Preview и transaction boundary

1. begin captures exact snapshot once. Every move projects from a fresh deep copy of that snapshot, never from previous preview or mutable _serverCfg.
2. Projected rooms, openings, walls and wall_segments are the same objects subsequently shown by render and offered for commit.
3. Preview success is atomic: preview, accepted delta and live labels replace the previous accepted triple together. Failure replaces none of them.
4. Candidate projection keeps the existing fixed-topology rekeyWallsAfterMoveChecked(..., 'fixed-topology'), changed-record carrier check and common physical preflight.
5. Immediately after rekey, exact wall-record preservation is checked against the immutable before snapshot. Failure returns bounded wall-metadata and cannot publish the preview.
6. finish proves current snapshot identity, validateSafeResize, identity of the accepted preview, common physical preflight and exact wall-record preservation again immediately before returning commit.
7. Root copies exactly rooms, openings, walls and wall_segments from commit outcome and calls one named history command. No simplify/rebuild or second candidate computation is allowed between outcome and write.

8. Один инвариант wall records

Новый src/wall-record-preservation.ts является единственным алгоритмом:

checkWallRecordsPreserved(before, after, {
  allowClear?: boolean,
  exactMultiplicity?: boolean,
}): WallRecordViolation[]

Контракт:

• allowClear: true явно отключает проверку; Resize его не передаёт;
• default/CLI mode сохраняет текущую семантику #254: каждое положительное конечное значение cm, существовавшее before, должно присутствовать after хотя бы один раз; законная merge одинаковых записей не считается потерей;
• exactMultiplicity: true сравнивает полное мультимножество всех конечных числовых cm, включая 0; это режим fixed-topology Resize;
• порядок records, key и endpoints не участвуют в профиле: их корректность отдельно доказывают rekey/carrier/physical checks;
• NaN, infinity и non-number не превращаются неявно в 0; такие записи не маскируют потерю валидной записи и проверяются существующими model gates;
• violation — bounded structured data без room ids/coordinates.

scripts/model-invariants.mjs удаляет собственную реализацию и re-export/import production helper из test-build, который команда npm run invariants уже собирает до запуска CLI. Это тот же действующий паттерн, что production preflight и near-axis в этом script. Unit tests проверяют обе семантики через один импорт и отдельно доказывают, что Resize вызывает exact mode на preview и finish.

9. Lifecycle, cache и восстановление

• Eligibility cache key сохраняет семантику #277: space, cell/grid scale и exact geometry snapshot. Snapshot вычисляется root один раз на layer render, а controller cache хранит results по (roomId, edge).
• Cache очищается при successful commit, tool/mode/space lifecycle reset и при смене context identity. Он bounded одной Map текущего context.
• Cancel восстанавливает retained pre-drag wall-union alias только если root подтверждает прежнюю snapshot identity, как сейчас; иначе cache silently отбрасывается.
• Preview по-прежнему увеличивает structural epoch и запрещает reuse clean-floor cache. После cancel/no-op/reject root возвращается к committed model.
• Warm remount не переносит active gesture/preview. WarmViewport.rszSel продолжает сохранять latent selection, но читает/восстанавливает его только через controller API; это module/session state, не сериализуемый config.
• dispose/disconnect, tool switch, space switch and mode exit must leave controller idle and release opaque retained references.

10. В скоупе

• новый controller и перенос в него Resize state/transitions/cache;
• typed root adapters и commit outcome;
• extraction единого production wall-record invariant;
• удаление controller-owned _rsz* mirrors из root и перенос latent _rszSel-семантики в controller;
• unit tests state machine/invariant, source-boundary guard и действующие production pointer smokes;
• актуализация architecture/Resize/testing/status docs;
• синхронизация tracked bundle как обычный результат build.

11. Не входит

• изменение geometry, UI, CSS, i18n, disabled reasons или hotkeys;
• изменение schema/model version/migrations/compatibility JSON;
• перенос _wallThick*, _opening*, drawing, labels renderer или общего geometry command stack;
• новый общий controller framework/base class/dependency injection container;
• переработка src/resize.ts и оптимизация boolean geometry;
• новое логирование, telemetry или пользовательский recovery dialog;
• cleanup иных мёртвых полей монолита.

Найденные вне этой границы дефекты получают отдельные issue и не исправляются попутно.

12. Ошибки и edge cases

Обязательная матрица:

1. disabled handle mouse/keyboard/touch — controller не входит в dragging;
2. synthetic pointer, на котором capture throws, не ломает session;
3. wrong pointer id на move/up/cancel — no-op;
4. repeated identical move — не перестраивает preview/labels;
5. first failed projection — preview отсутствует, pointer визуально остаётся на committed model, toast один;
6. failed projection after success — остаётся последний полный safe preview;
7. failure adapter exception — то же bounded поведение;
8. zero-delta pointerup — no write/Undo;
9. stale config/space snapshot на pointerup — reject, zero write/Undo;
10. topology validation failure — reject, zero write/Undo;
11. wall record count/value loss, включая cm:0 — preview/commit reject;
12. reordered records с тем же exact profile — разрешено;
13. carrier/physical preflight failure — reject;
14. Escape, Ctrl/Cmd+Z, pointercancel, lost capture, tool/mode/space exit — один cancel, exact committed geometry, zero write/Undo;
15. late cancel after up — no second outcome;
16. success — one outcome, one history command, one scheduled write;
17. room-area click в idle Resize + Escape + Escape сохраняет текущую последовательность «очистить latent selection → выйти в Draw»;
18. Undo/Redo/reload — exact parity с поведением #277;
19. disconnected root не оставляет controller references/timers/listeners.

13. Performance

Изменение не должно ухудшить действующие бюджеты #277:

• handle layer computes geometry snapshot once per render, not per edge;
• warm eligibility cache не вызывает повторный resolver для того же key;
• pointermove p95 на large-house fixture ≤16 ms и ≤20% хуже same-run baseline;
• pointerup preflight p95 ≤75 ms;
• commit invariant O(number of wall records), без polygon work и без JSON stringify каждого record сверх уже необходимого snapshot;
• controller создаёт не более одного accepted preview на успешный distinct delta и не сохраняет историю preview после завершения session.

Отдельной новой performance feature нет; доказательство — существующий benchmark:safe-resize, render benchmark/call-count и review профиля diff.

14. Touch и accessibility

View/kiosk не затронуты. Plan editor остаётся desktop-first, но safety floor обязателен на touch: finger-sized handles, disabled reason on tap, pointer id guard, pointercancel/lost capture and pinch cancellation remain exactly as in #277. Controller receives primitives after DOM event handling and therefore не может отменить preventDefault, aria attributes, focusability или hit area.

15. Файлы и модули

Планируемый diff:

• src/resize-controller.ts — новый controller и typed outcomes;
• src/wall-record-preservation.ts — единый invariant;
• src/houseplan-card.ts — composition/adapters/render wiring, удаление mirrors;
• scripts/model-invariants.mjs — import/re-export production invariant;
• tsconfig.test.json — test-build новых production modules;
• test/resize-controller.test.mjs — state transition matrix;
• test/wall-record-preservation.test.mjs и/или test/model-invariants.test.mjs — shared semantics;
• test/resize-production-path.test.mjs — source boundary/exact guard;
• существующие demo/smoke_room_resize.mjs, demo/smoke_resize_pointer_real_plan.mjs, demo/smoke_resize_wall_thickness.mjs, demo/smoke_resize_inner_dimensions.mjs — behavioral parity;
• docs/ARCHITECTURE.md, docs/RESIZE.md, docs/TESTING.md, docs/STATUS.md — фактическая граница и проверка.

Иные файлы добавляются только если smoke-select/build sync механически этого требуют. RU/EN i18n и changelog не меняются, потому что User-Visible: no.

16. Критерии приёмки

AC	Критерий	Доказательство
AC1	В root нет mutable _rszDrag, _rszPreview, _rszLive, _rszEligibilityCache и _rszSel; состояние и cache принадлежат одному ResizeController.	Source guard + code review.
AC2	Controller реализует таблицу §6: wrong pid/duplicate events/no-op/cancel/reject/success дают ровно один детерминированный outcome.	Unit.
AC3	Preview строится из immutable pre-drag snapshot, никогда не пишет _serverCfg; failed projection сохраняет последний полный accepted preview/delta/labels и уведомляется один раз.	Unit + production pointer smoke.
AC4	Pointerup возвращает commit только для exact displayed preview после snapshot/topology/common-preflight checks; root выполняет ровно одну geometry command/write, остальные outcomes — 0.	Unit + production pointer smoke.
AC5	Cancel/Escape/Ctrl+Z/pointercancel/lost capture/tool/mode/space exit возвращают committed model, 0 Undo/write и не допускают late double outcome.	Unit + browser smoke.
AC6	Один production helper сохраняет старую CLI presence-семантику и exact Resize-семантику, включая cm:0; script не содержит копии counting/comparison algorithm.	Unit + source guard + npm run invariants.
AC7	Exact invariant вызывается при projection и повторно в final controller guard; искусственная потеря/изменение multiplicity даёт fail-closed до commit.	Injectable unit + production-path test.
AC8	Safe Resize #277 остаётся функционально идентичным: eligibility, clamp, opening stops, preview, measurements, Undo/Redo/reload и disabled a11y проходят существующие тесты.	Existing units + selected smokes.
AC9	Handle render вычисляет snapshot один раз, warm cache bounded текущим context и не повторяет resolver; бюджеты §13 зелёные.	Call-count unit + benchmark.
AC10	DOM/CSS/i18n/config schema и tracked visual baselines не меняются; targeted golden verify не показывает diff.	Source/diff review + golden verify.
AC11	Typecheck, unit, build, docs and model-invariant gates зелёные; tracked bundle синхронизирован.	Local gates + CI.
AC12	Architecture/Resize/testing/status docs описывают controller boundary, single-source invariant и refactor-only status; changelog не изменён.	Docs gate + review.

17. План тестирования

Unit

• fake typed ports без DOM для каждой строки автомата §6 и edge cases §12;
• prove a failed state transition by mutation/negative input, not only happy snapshots;
• presence/exact/allowClear profiles: duplicates, count decrease, count increase, reordered values, zero, invalid numeric values;
• controller exact-guard call count at preview and finish;
• eligibility cache hit/miss/invalidation and one snapshot per rendered layer.

Production path / browser

• update source contract so tests forbid state mirrors and inline wall-cm comparison in root;
• execute real pointerdown/move/up and cancel paths through bundled card;
• selected existing smokes from node scripts/smoke-select.mjs --base origin/dev --head HEAD, at minimum safe Resize, wall thickness and inner dimensions;
• verify one write/Undo on success and zero on every fail/cancel path.

Visual / performance

• targeted existing Resize golden scenes in light/dark must match committed baselines; new baselines are forbidden unless review proves unrelated drift;
• existing safe-resize and safe-resize-render benchmarks stay inside §13.

Full prerelease smoke/golden/performance matrix remains a release-stage gate, not a substitute for targeted implementation checks.

18. Документация, compatibility и release artifacts

• Schema/migration: none; successful persisted payload byte-equivalent.
• i18n: no keys added/changed/removed.
• Changelog RU/EN: no entries; refactor-only, User-Visible: no.
• User guide: no change.
• Architecture/engineering docs: update files from §15 in implementation commit.
• Golden/screenshots: verify only; no accepted visual delta expected.
• Security/backend: no impact.

19. Риски и меры

Риск	Мера
Shallow extraction leaves two owners of state	AC1 forbids mirrors; root gets immutable getters and outcomes only.
Controller absorbs renderer/HA and becomes a second monolith	Explicit ownership matrix §4; no Lit/DOM/i18n/config write imports.
Preview and commit diverge during refactor	Exact preview object identity + final guards + AC3/AC4.
Common invariant weakens #277 exact contract to coarse CLI presence	Two modes in one helper; Resize always exact, AC6/AC7 include multiplicity and zero walls.
Zero-thickness walls from #306 disappear silently	Exact profile includes finite numeric cm:0.
Adapter exception leaks partial state	Boundary catches and maps to bounded reject, state cleared atomically.
Cancel loses expensive pre-drag wall union reuse	Opaque retained token and snapshot-identity restore test.
Перенос _rszSel меняет warm/Escape behavior	Controller сохраняет latent selection, warm getter/restore и двухшаговый Escape; dedicated unit/browser assertion.
Large mechanical diff hides behavior change	Separate spec and implementation commits, targeted source guard, selected smokes, golden no-diff and independent review.

20. Rollback

Rollback is a normal revert of the implementation commit(s), including generated bundle and documentation. There is no data migration, feature flag or persisted new field to undo. Because successful payloads remain byte-identical, a plan edited by the refactored controller opens unchanged after rollback.