houseplan-card/docs/BACKDROP.md

The backdrop picture — the spec (source of truth)

Owner-approved 2026-08-04. Companion to docs/CANVAS.md (the plane the picture lives on) and docs/RESIZE.md (the other transform frame).

Until v1.58.0 an uploaded plan image was nailed to the canvas: centred, at its own proportions, filling the square. If it did not line up with the rooms you had drawn — or with the rooms you were about to draw — the only recourse was to edit the file. And because it filled the canvas, it also decided where the opaque paper was, which quietly made a picture plan and a drawn plan two different kinds of thing.

This closes both. The picture is now one of the objects on the plane: it can be moved and scaled like anything else, it counts as content for the frame, and it no longer makes paper of its own.

---

§1 Model — three optional numbers

A space gains three optional fields, next to plan_url / plan_aspect:

Field	Meaning	Units	Range
plan_x	offset of the image's top-left corner from its default place	normalised (as rooms, decor, openings)	±CANVAS_LIMIT (±5000)
plan_y	the same, vertically	normalised	±CANVAS_LIMIT
plan_scale	one uniform multiplier for both sides, anchored at the (already offset) top-left corner	multiplier	0.01 … 100

There is no rotation and no independent width/height: the picture keeps its own aspect ratio for ever, which is what makes "scale" a single number.

The absence of all three is exactly the pre-v1.58.0 behaviour. No migration runs, nothing is written into anybody's store, and a plan that has never been through the backdrop editor renders bit-identically. Junk (a string, NaN, a zero or negative scale) is treated as absence, not as an error — the same reading rule the rest of the geometry uses.

One function owns the arithmetic, planRect() in src/space-geometry.ts:

base   = fitInSquare(plan_aspect, 1000)      // the centred default
rect.x = base.x + plan_x * 1000
rect.y = base.y + plan_y * 1000
rect.w = base.w * plan_scale
rect.h = base.h * plan_scale

spaceModels() calls it, so every consumer — the full card, the static houseplan-space-card, the kiosk, the content frame — reads the same rectangle. The card's model cache key (_cfgFingerprint) carries the three fields, so a drag invalidates the memo.

validation.py mirrors the ranges (PLAN_SCALE_MIN / PLAN_SCALE_MAX alongside CANVAS_LIMIT). Detaching the image (space dialog → «Нарисую комнаты вручную») deletes all three: there is nothing left for them to describe, and a stale transform must not silently apply to the next upload.

---

§2 The transform frame

Where. The backdrop editor (mode: 'decor', «Редактор подложки»). The frame is on screen as soon as that editor opens (tools select and «Картинка-подложка»); the drawing tools own the drag, so the frame steps aside for them. Nowhere else: View, the Plan editor, the Device editor and the kiosk never touch the picture. A space with no image never grows a frame, and its toolbar is unchanged.

What. A dashed outline on the picture's rectangle plus four corner handles. Two radii, one gesture: the HIT circle is 2 % of the visible view — finger-sized at any zoom, the same rule the vacuum fit frame uses — and is invisible; the bead you actually see (.bdknob) is a quarter of it (owner, 2026-08-05: «уменьшить в 4 раза… они постоянно гигантские»). The clickable area is unchanged; only the ink shrank, so the frame stops covering the picture it frames. The same split now governs the text block (docs/LIVE-TEXT.md §3), the room-resize corners and the vacuum fit. The outline never takes a pointer; the handles do, with setPointerCapture and nwse-resize / nesw-resize cursors. Under the picture's own tool the stage cursor is grab, and grabbing while a gesture is live.

Move — press anywhere inside the picture and drag, under the «Картинка-подложка» tool. Why a tool and not just the select tool: the picture's body is most of the screen, and claiming it would take away the one-finger pan of the whole plane, which the owner asked for on 2026-08-04 («таскать план при любом масштабе») and smoke_pan_any_zoom guards. The corner handles are precise targets and need no such protection — they are live whenever the frame is. The gesture is also only started INSIDE the rectangle, so pressing beside the picture pans even under its own tool.

…and that tool is ARMED when the editor opens (owner, 2026-08-05: «не получается двигать картинку-подложку в режиме редактора подложки»). The frame is drawn on open, which promises a draggable picture, while the promise was only kept once the user found a tool they had no reason to look for. So _setMode('decor') selects backdrop instead of select whenever the space HAS a picture — the editor is named after it. Nothing else changes: select is one click away and still leaves the body to the pan, a space with no picture still opens on select, and Esc still returns to select. This is a discoverability fix, not a new gesture.

Nothing may rescale the stage mid-gesture. Two things wanted to, and both moved the picture away from the finger before they were stopped:

• the picture is a content item, so dragging it GROWS the editor's content frame, which rescales the view — _frameOf() therefore returns the memoized frame untouched while _bdDrag is live, and catches up on release;
• «Вернуть картинку» appears the moment the picture has moved, and the toolbar sits above the stage — so it is withheld until the gesture ends.

Scale — pull a corner. Uniform, about the opposite corner, which stays exactly where it was (the mechanic borrowed from the vacuum calibration panel). k = max(|dx| / base.w, |dy| / base.h), so the gesture follows whichever axis you pulled harder, and both sides then follow k.

Nothing else moves. Rooms, openings, devices, decor and room labels are untouched by both gestures — this is a picture-only transform, and the smoke asserts the room geometry is byte-identical afterwards.

Undo is the «Вернуть картинку» button in the backdrop toolbar: it appears only once the picture HAS been moved, and it deletes the three fields (back to centred, own size).

---

§3 THE PAPER IS THE ROOMS — and only the rooms

This is a behaviour CHANGE, deliberately.

The opaque "paper" exists so the scene background — bg_color, or the daynight sky (docs/SUN.md) — never bleeds through the plan itself. Until v1.58.0 it had two forms: the ROOM CONTOURS for a drawn plan, and the image rectangle for a picture plan.

The second form is gone. The paper is now paperRoomShapes(space.rooms) in every case (or paperRoomShapesWithWalls when a space carries wall thickness — docs/WALL-THICKNESS.md §4 — so the sheet grows under shared slabs and the scene never shows through a hatched body):

• one opaque shape per room, in exactly the room's own geometry — an L-shaped house or a pair of detached buildings never grows a bounding rectangle;
• an empty space has no paper at all, image or no image;
• its colour is unchanged (styles.ts .hp-paper): white on a hand-drawn plan (.stage.noplan), the theme card background where an image is attached in View; every editor (plan / devices / decor) forces white under the grid even with a backdrop, so the drawing sheet stays the same sheet as a hand-drawn plan. daynight dims it via the .zoomwrap brightness filter only — its alpha stays 1.

Layer order, top to bottom, in both renderers:

devices / labels
sun wedges and rays
walls, openings, room fills, decor
THE PICTURE                     ← above the paper, below the geometry
the paper (room contours)
the scene background (bg_color / the daynight sky)

The consequence, and the owner knows it: a picture with transparency over a space with no rooms drawn shows the scene background through itself. That is the honest reading of "the paper belongs to the rooms" — draw the rooms and the paper appears under them.

---

§4 The picture is content

contentItems() has always counted the image rectangle as one content item alongside the rooms; it now counts the transformed one. So the frame, «Вписать всё», the zoom floor and the pan slack (docs/CANVAS.md §4–§5) all follow the picture wherever it is dragged, and a picture scaled down to a quarter tightens the frame around it instead of framing empty plane.

iconUnit() deliberately does not count it: an icon is a percentage of the drawn plan (docs/CANVAS.md §6), and scaling the backdrop must not resize every marker on it.

---

§5 Snap

Both gestures obey the canvas snap contract (docs/CANVAS.md §9):

Gesture	What is snapped
move	the resulting top-left corner — the anchor, not the delta, so one drag is enough to put a legacy off-grid picture onto the lattice
scale	the dragged corner along the picture's longer side; the scale is then read back off it

The fixed corner of a scale keeps its (on-grid) place and the long side lands on a node. The short side follows from the aspect ratio and generally does not — that is what "uniform, no stretch" costs, and it is the right trade: a picture whose proportions drift is a broken picture.

Shift suspends the snap for the duration of the gesture, exactly as everywhere else (§9.4). The ±CANVAS_LIMIT clamp rides along regardless — _snap() and clampCanvasN are the only bound either gesture has.

---

§6 Live measurements

While the picture is dragged or scaled, one badge rides its centre with the picture's real size, width × height, through the space's cell_cm and the HA unit system (metres or feet). It is the same _fmtLen (segmentCm → formatLength) and the same .measurelabel element the wall ruler, the opening shoulders and the room resize use — the card states a length exactly one way.

---

§6b One tool at a time — a drawing tool owns the canvas

The backdrop editor has seven tools, and they are exclusive: only select talks to an existing shape, only erase deletes one, only «Картинка-подложка» grabs the picture's body, and the four drawing tools (line, rect, ellipse, text) do nothing but create.

The rule exists because of a concrete failure (owner, 2026-08-04): «нельзя поставить начало линии на конец другой — при клике на конец выделяется первая линия, а не начинает рисоваться новая». The shape's own pointerdown handler ran first, stopped the event and did nothing under a drawing tool, so the press never reached the stage and no draft was born — exactly on the one spot where a new line most wants to start, since §5's snap anchors include every line end.

So, under a drawing tool (and under the picture tool):

• .dshape is pointer-events: none — an existing figure is not a target at all, and the cursor is the stage's;
• _decorShapeDown returns before stopPropagation for any tool that is not select/erase, so a synthetic press cannot swallow the gesture either;
• _decorPointerDown only looks for a shape under the pointer for select/erase, and otherwise starts the draft at the pressed point;
• the transform frame's corner handles stay off (§2) — they were the first thing taught not to swallow the first point of a line.

Selecting, moving and the text dialog's double-click therefore live in the select tool only. demo/smoke_decor.mjs asserts both halves: a press on an existing line starts a new line from that end under the line tool, and still selects and grabs it under select.

---

§7 What is deliberately NOT done

• No rotation. A skewed scan is a scan to re-take, not a plan to skew the whole editor's maths for.
• No non-uniform scale. See above: the picture keeps its ratio.
• No numeric fields in the space dialog. The frame is the interface; the numbers exist for the config, not for typing.
• No per-room clipping of the picture. It is one rectangle.
• No transform for the sun's paper/wedges. Those follow the rooms, and now so does the paper — one rule, no second geometry.

---

§8 Where it lives

Concern	File
the rectangle (planRect, PLAN_SCALE_MIN/MAX), content items	src/space-geometry.ts
the frame, the gestures, the live badge, the reset	src/houseplan-card.ts (_bd*, _renderBackdropFrame)
the frame's look, the paper, the cursors	src/styles.ts (.bdframe, .hp-paper)
the static card's copy of the paper + picture order	src/space-render.ts
the stored ranges	custom_components/houseplan/validation.py
unit coverage	test/backdrop.test.mjs
DOM coverage	demo/smoke_backdrop.mjs, demo/smoke_bg_color.mjs §11
screenshots	demo/shot_backdrop.mjs