fix: first-open boot veil — no residual jump under HA panels (HP-1552)

In normal (non-kiosk) mode the stage is calc(100dvh - _hdrH), and _hdrH is
measured from HA's chrome, which finishes loading AFTER the card's first
paint — late panels nudged the height and the freshly painted plan visibly
jumped (kiosk is a flat 100dvh, hence 'perfect in kiosk').

Fix, per the owner's sketch:
- until the stage height reads the same twice in a row (200 ms cadence) or
  a hard ~600 ms cap, the plan stays hidden (.hpboot) and is revealed only
  after a refit — not a single frame paints at a stale height;
- that window is covered by a quiet product-style preloader: dark veil,
  small pulsing outline house (the card's own mdi:home-city outline,
  inline SVG), no text, 0.15 s opacity fade-out;
- prefers-reduced-motion gets a static house; kiosk never shows the veil;
  first open of the card instance only — floor/mode switches are untouched.

smoke_preloader simulates an HA panel landing at t=300 ms and asserts the
veil, zero plan-visible frames at a non-final height, the kiosk opt-out and
the reduced-motion variant; serve.mjs starts every smoke after the reveal,
where the user starts.

demo/serve.mjs

@@ -56,6 +56,10 @@ export async function launch(viewport = { width: 820, height: 760 }, scale = 1)
   });
   await page.goto('http://demo.local/demo.html', { waitUntil: 'domcontentloaded' });
   await page.waitForFunction(() => window.__card?._model?.length > 0, { timeout: 9000 });
+  // HP-1552: the first-open boot veil hides the plan (visibility:hidden) until
+  // the stage height settles — real pointer interaction cannot hit a hidden
+  // plan, so every smoke starts where the user does: with the plan revealed.
+  await page.waitForFunction(() => window.__card._booting === false, { timeout: 9000 });
   // hass flows continuously in production; the stub sets it once — nudge a rebuild
   await page.evaluate(() => { const c = window.__card; c.hass = { ...c.hass }; });
   await page.waitForFunction(() => window.__card._devices.length > 0, { timeout: 9000 });

demo/smoke_preloader.mjs

@@ -0,0 +1,144 @@
+// HP-1552: residual jump on first open in NORMAL (non-kiosk) mode. The stage is
+// calc(100dvh - _hdrH) and _hdrH is measured from HA's chrome, which loads
+// AFTER the card's first paint — so the plan painted, then jumped when the
+// panels landed. The fix hides the plan behind a boot veil (pulsing house)
+// until the height reads the same twice in a row (or ~600 ms). This smoke
+// simulates the late HA panel: a spacer above the card grows 0 → 56 px at
+// t=300 ms. Assertions: the veil is shown, and there is NOT A SINGLE frame
+// where the plan is visible at a non-final stage height. Kiosk: no veil ever.
+import { launch, check, finish } from './serve.mjs';
+
+const { page, browser } = await launch({ width: 820, height: 760 });
+
+// ---------- phase 1: normal mode, HA panel lands late ----------
+const res = await page.evaluate(async () => {
+  const out = {};
+  const spacer = document.createElement('div');
+  spacer.style.cssText = 'height:0px';
+  const c = document.createElement('houseplan-card');
+  c.setConfig({ type: 'custom:houseplan-card' });
+  c.hass = window.__card.hass;
+  const wrap = document.createElement('div');
+  wrap.style.cssText = 'position:fixed;left:0;top:0;width:800px;z-index:99;background:#000';
+  wrap.append(spacer, c);
+  document.body.appendChild(wrap);
+
+  const frames = [];
+  const sr = () => c.shadowRoot || c.renderRoot;
+  const t0 = performance.now();
+  let grown = false;
+  await new Promise((done) => {
+    const sample = () => {
+      const t = performance.now() - t0;
+      if (!grown && t >= 300) {
+        grown = true; // the "HA panel" arrives: everything above the card grows
+        spacer.style.height = '56px';
+        window.dispatchEvent(new Event('resize'));
+      }
+      const stage = sr().querySelector('.stage');
+      if (stage) {
+        const veil = sr().querySelector('.bootveil');
+        const wrapEl = stage.querySelector(':scope > .zoomwrap');
+        const planHidden =
+          !wrapEl ||
+          getComputedStyle(wrapEl).visibility === 'hidden' ||
+          (veil && !veil.classList.contains('off') && getComputedStyle(veil).opacity !== '0');
+        frames.push({
+          t: Math.round(t),
+          planVisible: !planHidden,
+          veil: !!veil,
+          veilBg: veil ? getComputedStyle(veil).backgroundColor : null,
+          house: !!(veil && veil.querySelector('.boothouse path')),
+          stageH: stage.clientHeight,
+        });
+      } else {
+        frames.push(null);
+      }
+      if (t < 1400) requestAnimationFrame(sample);
+      else done();
+    };
+    requestAnimationFrame(sample);
+  });
+
+  const seen = frames.filter(Boolean);
+  const finalH = seen[seen.length - 1].stageH;
+  out.sampledFrames = seen.length > 40;
+  out.veilShownWhileSettling = seen.some((f) => f.veil && !f.planVisible && f.house);
+  out.veilIsDark = (() => {
+    const f = seen.find((x) => x.veilBg);
+    const m = f && f.veilBg.match(/(\d+),\s*(\d+),\s*(\d+)/);
+    return !!m && +m[1] + +m[2] + +m[3] < 300; // dark, not white/transparent
+  })();
+  // THE assertion: no frame may show the plan at a stale (pre-panel) height
+  const bad = seen.filter((f) => f.planVisible && Math.abs(f.stageH - finalH) > 2);
+  out.noVisibleFrameAtStaleHeight = bad.length === 0
+    ? true
+    : `plan visible at h=${bad[0].stageH} (final ${finalH}) at t=${bad[0].t}ms — the jump is visible`;
+  const shown = seen.filter((f) => f.planVisible);
+  out.planShownAfterSettle = shown.length >= 5 && Math.abs(shown[0].stageH - finalH) <= 2;
+  out.veilGoneInTheEnd = !seen[seen.length - 1].veil;
+  out.heightReactedToPanel = finalH !== seen[0].stageH; // the simulated panel actually moved the stage
+  wrap.remove();
+  return out;
+});
+for (const [k, v] of Object.entries(res)) check(k, v);
+
+// ---------- phase 2: kiosk never shows the veil ----------
+const kiosk = await page.evaluate(async () => {
+  const out = {};
+  const c = document.createElement('houseplan-card');
+  c.setConfig({ type: 'custom:houseplan-card', kiosk: true, cycle: 0 });
+  c.hass = window.__card.hass;
+  c.style.cssText = 'position:fixed;left:0;top:0;width:800px;height:700px;z-index:99';
+  document.body.appendChild(c);
+  const sr = () => c.shadowRoot || c.renderRoot;
+  let veilEver = false;
+  let planHiddenEver = false;
+  const t0 = performance.now();
+  await new Promise((done) => {
+    const sample = () => {
+      const stage = sr().querySelector('.stage');
+      if (stage) {
+        if (sr().querySelector('.bootveil')) veilEver = true;
+        const wrapEl = stage.querySelector(':scope > .zoomwrap');
+        if (wrapEl && getComputedStyle(wrapEl).visibility === 'hidden') planHiddenEver = true;
+      }
+      if (performance.now() - t0 < 900) requestAnimationFrame(sample);
+      else done();
+    };
+    requestAnimationFrame(sample);
+  });
+  out.kioskNoVeil = !veilEver;
+  out.kioskPlanNeverHidden = !planHiddenEver;
+  c.remove();
+  return out;
+});
+check('kioskNoVeil', kiosk.kioskNoVeil);
+check('kioskPlanNeverHidden', kiosk.kioskPlanNeverHidden);
+
+// ---------- phase 3: prefers-reduced-motion → the house does not pulse ----------
+await page.emulateMedia({ reducedMotion: 'reduce' });
+const reduced = await page.evaluate(async () => {
+  const c = document.createElement('houseplan-card');
+  c.setConfig({ type: 'custom:houseplan-card' });
+  c.hass = window.__card.hass;
+  c.style.cssText = 'position:fixed;left:0;top:0;width:800px;z-index:99';
+  document.body.appendChild(c);
+  const sr = () => c.shadowRoot || c.renderRoot;
+  const t0 = performance.now();
+  let anim = 'missed';
+  await new Promise((done) => {
+    const tick = () => {
+      const house = sr().querySelector('.bootveil .boothouse');
+      if (house) { anim = getComputedStyle(house).animationName; done(); return; }
+      if (performance.now() - t0 < 500) requestAnimationFrame(tick);
+      else done();
+    };
+    requestAnimationFrame(tick);
+  });
+  c.remove();
+  return { anim };
+});
+check('reducedMotionStaticHouse', reduced.anim, 'none');
+
+await finish(browser, { ...res, ...kiosk, ...reduced });

src/houseplan-card.ts

@@ -29,6 +29,7 @@ import {
   simplifyPoly, areaM2, formatArea, MIN_ROOM_CM, type EdgeDragPlan,
 } from './resize';
 import { ContentSigner } from './signing';
+import { mdiHomeCityOutline } from '@mdi/js';
 import {
   Affine, applyAffine, solveAffine, affineResidual, readVacTelemetry, isVacSourceState,
   autoCalibrate, pushTrailPoint, isVacMoving, vacTrailMode, vacMapIdWithFallback, VAC_TELEPORT_GAP_MS, VAC_STALE_MS,
@@ -289,6 +290,17 @@ class HouseplanCard extends LitElement {
   private _roHdr?: ResizeObserver;
   private _onWinResize?: () => void;
   private _hdrH = 118; // measured px above the stage (see the observer in updated())
+  /** HP-1552: first-open boot veil. In normal (non-kiosk) mode the stage is
+   *  calc(100dvh - _hdrH), and _hdrH is measured from HA's chrome — which
+   *  finishes loading AFTER the card's first paint, so every late panel
+   *  nudged the height and the plan visibly jumped. Until the height reads
+   *  the same twice in a row (or ~600 ms pass) the plan hides behind a
+   *  pulsing-house veil. First open only; kiosk is 100dvh and never jumps. */
+  private _booting = true;
+  private _bootFading = false; // veil kept one beat for the opacity-out
+  private _bootTimer?: number;
+  private _bootLastH = -1;
+  private _bootStart = 0;
   /** The accidental-tap guard: pending confirmation for a toggle/run tap. */
   private _tapConfirm: { text: string; exec: () => void } | null = null;
   private _onboardingShown = false; // the auto space dialog is shown once per session
@@ -440,6 +452,8 @@ class HouseplanCard extends LitElement {
 
   static properties = {
     _hdrH: { state: true },
+    _booting: { state: true },
+    _bootFading: { state: true },
     _tapConfirm: { state: true },
     hass: { attribute: false },
     _config: { state: true },
@@ -515,6 +529,7 @@ class HouseplanCard extends LitElement {
     this._signer.dispose();
     clearTimeout(this._toastTimer);
     clearTimeout(this._slideTimer);
+    clearTimeout(this._bootTimer);
     this._saveConfigDebounced.flush(); // never leave an edit unsent on teardown
     window.removeEventListener('hashchange', this._onHashChange);
     clearTimeout(this._holdTimer);
@@ -650,6 +665,7 @@ class HouseplanCard extends LitElement {
 
   public setConfig(config: CardConfig): void {
     this._config = { icon_size: 2.5, show_temperature: true, live_states: true, show_signal: true, ...config };
+    if (this._config.kiosk) { this._booting = false; this._bootFading = false; } // kiosk: 100dvh, nothing to settle
     if (config.default_floor) this._space = config.default_floor;
     try {
       this._zoomBySpace = JSON.parse(localStorage.getItem(LS_ZOOM) || '{}') || {};
@@ -891,6 +907,7 @@ class HouseplanCard extends LitElement {
       this._roViewport = new ResizeObserver(() => this._refitView());
       this._roViewport.observe(stage);
     }
+    if (stage && this._booting && !this._bootTimer) this._bootWatch();
     // The stage fills the rest of the viewport. What sits above it inside the
     // CARD depends on the mode — the editor bars used to be billed against a
     // hard-coded 118px, so entering an editor pushed the plan down by the
@@ -1583,6 +1600,35 @@ class HouseplanCard extends LitElement {
     this._view = this._clampView({ x: ccx - w / 2, y: ccy - h / 2, w, h }, fit);
   }
 
+  /**
+   * HP-1552: poll the stage height until it settles — two equal reads in a
+   * row, or a hard cap of ~600 ms (HA's panels normally land well inside it).
+   * Only then is the plan revealed, already refit to the final geometry.
+   */
+  private _bootWatch(): void {
+    this._bootStart = Date.now();
+    this._bootLastH = -1; // the first read only arms the comparison
+    const tick = () => {
+      if (!this._booting) return;
+      const h = this._stageEl ? this._stageEl.clientHeight : 0;
+      if ((h > 0 && h === this._bootLastH) || Date.now() - this._bootStart >= 600) {
+        this._bootSettled();
+        return;
+      }
+      this._bootLastH = h;
+      this._bootTimer = window.setTimeout(tick, 200);
+    };
+    this._bootTimer = window.setTimeout(tick, 200);
+  }
+
+  private _bootSettled(): void {
+    if (!this._booting) return;
+    this._refitView(); // reveal in the final geometry, never mid-jump
+    this._booting = false;
+    this._bootFading = true; // one soft opacity-out, then out of the DOM
+    this._bootTimer = window.setTimeout(() => { this._bootFading = false; }, 220);
+  }
+
   /** Recompute the view for a new scene size, preserving zoom and center. */
   private _refitView(): void {
     if (!this._stageEl) return;
@@ -4678,7 +4724,7 @@ class HouseplanCard extends LitElement {
         ${this._markup ? this._renderMarkupBar() : this._mode === 'devices' ? this._renderDevicesBar() : this._mode === 'decor' ? this._renderDecorBar() : nothing}
         </div>
 
-        <div class="stage ${this._markup ? 'markup tool-' + this._tool + (this._tool === 'split' && !this._splitSel ? ' pickstage' : '') + (this._tool === 'openwall' && this._openWallHover ? ' wallhot' : '') : ''} ${this._mode === 'decor' ? 'dtool-' + this._decorTool : ''} ${space.bg ? '' : 'noplan'} mode-${this._mode}"
+        <div class="stage ${this._markup ? 'markup tool-' + this._tool + (this._tool === 'split' && !this._splitSel ? ' pickstage' : '') + (this._tool === 'openwall' && this._openWallHover ? ' wallhot' : '') : ''} ${this._mode === 'decor' ? 'dtool-' + this._decorTool : ''} ${space.bg ? '' : 'noplan'} mode-${this._mode}${this._booting ? ' hpboot' : ''}"
           style="height:${this._kiosk ? '100dvh' : `calc(100dvh - ${this._hdrH}px)`}${stageBg ? `;background:${stageBg}` : ''}"
           @click=${(e: MouseEvent) => this._markupClick(e)}
           @wheel=${(e: WheelEvent) => this._onWheel(e)}
@@ -4815,6 +4861,11 @@ class HouseplanCard extends LitElement {
           ${this._zoom > 1
             ? html`<div class="zoombadge">${Math.round(this._zoom * 100)}%</div>`
             : nothing}
+          ${this._booting || this._bootFading
+            ? html`<div class="bootveil ${this._booting ? '' : 'off'}" aria-hidden="true">
+                <svg class="boothouse" viewBox="0 0 24 24"><path d="${mdiHomeCityOutline}"></path></svg>
+              </div>`
+            : nothing}
         </div>
 
         ${this._roomDialog ? this._renderRoomDialog() : nothing}

src/styles.ts

@@ -151,6 +151,44 @@ export const cardStyles = css`
       position: absolute;
       inset: 0;
     }
+    /* HP-1552: first-open boot veil — the plan hides until the stage height settles */
+    .stage.hpboot .zoomwrap,
+    .stage.hpboot .zoombadge {
+      visibility: hidden;
+    }
+    .bootveil {
+      position: absolute;
+      inset: 0;
+      z-index: 40;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: var(--hp-bg, #16212e);
+      opacity: 1;
+      transition: opacity 0.15s ease;
+      pointer-events: none;
+    }
+    .bootveil.off {
+      opacity: 0;
+    }
+    .bootveil .boothouse {
+      position: static; /* .stage svg pins itself to inset:0 — not this one */
+      width: 56px;
+      height: 56px;
+      fill: var(--hp-accent);
+      opacity: 0.85;
+      animation: hp-boot-pulse 1.3s ease-in-out infinite;
+    }
+    @keyframes hp-boot-pulse {
+      0%, 100% { opacity: 0.3; transform: scale(0.94); }
+      50% { opacity: 0.9; transform: scale(1); }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      .bootveil .boothouse {
+        animation: none;
+        opacity: 0.7;
+      }
+    }
     .zoomctl {
       display: inline-flex;
       gap: 2px;