weatherSceneModule.js

// =============================================================================
// LIVE SKY — weatherSceneModule.js
// A single braille animation that runs the WHOLE TIME and morphs to the live
// weather + day/night via a simple logic tree. No talking head, no idle-mode
// menu — one delightful, low-cost scene that always tells you, at a glance,
// what it's doing outside in Clermont right now.
//
// THE SCENE (rebuilt 2026-06-14): a Florida lakeside, designed around ONE clear
// hero. The tall panel was dead space, so it's now a *place* — sky weather up top,
// a living Clermont lake (drifting ripples) across the bottom, and a single
// resident FLAMINGO mascot standing in it, centred so it owns the frame. The
// flamingo is the heart of it: a Tamagotchi-level idle character that reacts to
// the weather — pops an umbrella in the rain, huddles + ducks under it in a storm,
// leans into the wind, switches which leg it stands on, blinks and gently looks
// around. It is ALWAYS awake with its head + beak OUT (first principle: it must
// always read as a flamingo at a glance — no sleep/tuck pose). Nothing else
// competes for attention (an
// earlier palm + water-reflection were dropped — one element + the weather pops
// more). Pink bird, moving teal water, weather-coloured sky — multi-hue braille
// via the canvas layer map, matching the rest of the dashboard's palette.
//
// Design goals (per the owner):
//   - runs continuously, never "off"; fills the panel, never empty
//   - changes dynamically with day/night + weather_code
//   - super simple + clearly readable as a weather condition
//   - LIGHT: bounded particle counts, ~8 fps, one small braille canvas, all
//     drawing is cheap primitives — it must never bog the dashboard down.
//
// Data: store.signals.weather (published by weatherVoiceModule) →
//   { temp, windMph, code (WMO), isDay (0/1), ... }. Everything is null-safe:
//   a missing signal falls back to a calm "calibrating" scene (the flamingo is
//   still there, standing by), never a crash.
// =============================================================================

const blessed = require('blessed');
const store = require('../core/store');
const { createBrailleCanvas } = require('./brailleCanvas');

// Colour layers for the canvas layer-map → blessed tags. Higher id wins a cell,
// so the order is also the paint priority (umbrella over bird over water/sky).
// Layer id = paint priority (higher wins a shared braille cell), so small details
// (wing shade, beak) sit on top of the pink body. The flamingo is the ONE hero
// element; everything else is sky weather + moving water around it.
const LAYER = { SKY: 0, WATER: 1, FLAMINGO: 2, ROSE: 3, BEAK: 4, UMBRELLA: 5 };
const FLAMINGO_TAG = '{#ff7ec0-fg}'; // bright flamingo pink (on-brand w/ telemetry magenta)
const ROSE_TAG     = '{#e34da0-fg}'; // deeper rose for the wing shade
const BEAK_TAG     = '{#ffa733-fg}'; // orange beak
const WATER_TAG    = '{#2aa6c0-fg}'; // dim lake teal
const UMBRELLA_TAG = '{#ffd23f-fg}'; // cheerful yellow canopy (distinct by brightness)

// --- LOGIC TREE: WMO weather_code (+ day flag) -> a scene descriptor ----------
// open-meteo weather_code reference:
//   0 clear · 1,2 mainly/partly · 3 overcast · 45,48 fog · 51-57 drizzle
//   61-67 rain · 71-77/85,86 snow · 80-82 rain showers · 95-99 thunderstorm
function classify(weather) {
  if (!weather || typeof weather.code !== 'number') {
    // No live weather yet (first fetch still in flight, ~seconds at startup).
    // Don't show a "broken" calibrating scan — fall back to a calm, real-looking
    // sky picked from the LOCAL clock (sun by day, moon+stars by night) so the
    // panel is always alive. Flips to the true condition the moment data lands.
    const hr = new Date().getHours();
    const day = hr >= 7 && hr < 19;
    return { key: 'clear', name: 'SYNCING', glyph: day ? '☀' : '☾',
             color: day ? 'yellow' : 'white', day, calibrating: true };
  }
  const code = weather.code;
  const day = weather.isDay !== 0;
  if (code >= 95) return { key: 'storm',    name: 'THUNDERSTORM',  glyph: '⚡', color: 'yellow', day, intensity: 1 };
  if (code >= 80) return { key: 'rain',     name: 'RAIN SHOWERS',  glyph: '☂', color: 'cyan',   day, intensity: code >= 82 ? 1 : 0.65 };
  // No snow scene — this is Clermont, FL; it never snows here. The WMO snow codes
  // (71-77, 85, 86) fall through to the rain branches below (harmless if they
  // ever appear), and that whole logic budget went to wind expression instead.
  if (code >= 61) return { key: 'rain',     name: 'RAIN',          glyph: '☂', color: 'cyan',   day, intensity: code >= 65 ? 1 : code >= 63 ? 0.7 : 0.45 };
  if (code >= 51) return { key: 'rain',     name: 'DRIZZLE',       glyph: '☂', color: 'cyan',   day, intensity: 0.3 };
  if (code === 45 || code === 48)
                  return { key: 'fog',      name: 'FOG',           glyph: '≡', color: 'gray',   day };
  if (code === 3) return { key: 'overcast', name: 'OVERCAST',      glyph: '☁', color: 'white',  day };
  if (code === 1 || code === 2)
                  return { key: 'partly',   name: 'PARTLY CLOUDY', glyph: day ? '⛅' : '☁', color: day ? 'yellow' : 'white', day };
  return            { key: 'clear',    name: day ? 'CLEAR' : 'CLEAR NIGHT', glyph: day ? '☀' : '☾', color: day ? 'yellow' : 'white', day };
}

function createWeatherSceneModule(parentBox, screen) {
  const skyBox = blessed.box({
    parent: parentBox,
    top: 0, left: 0, width: '34%', height: '100%',
    tags: true, wrap: false,
    border: { type: 'line' },
    label: ' CLERMONT SKY ',
    style: { fg: 'cyan', border: { fg: 'cyan' }, bg: 'black' },
    content: ''
  });

  let canvas = null, pw = 0, ph = 0, cols = 0, rows = 0;
  let frame = 0;
  let sceneKey = null;     // current scene key; particles rebuild when it changes
  let parts = null;        // particle sets for the active scene
  let flashUntil = -1;     // lightning flash frame window
  let nextBolt = 18;       // frames until next lightning bolt (~2s, then random)
  let timer = null;

  // A tiny seeded RNG so star/cloud layouts are STABLE between rebuilds (no
  // per-frame jitter that reads as noise). Deterministic given an index.
  function rnd(seed) {
    const x = Math.sin(seed * 99.13 + 7.7) * 43758.5453;
    return x - Math.floor(x);
  }

  function ensureCanvas() {
    const c = Math.max(8, (skyBox.width || 18) - 3);
    // height-4 leaves room for the weather label line below the canvas without
    // clipping it (content = canvasRows + 1 label line <= inner height).
    const r = Math.max(8, (skyBox.height || 24) - 4);
    if (!canvas || c !== cols || r !== rows) {
      cols = c; rows = r; pw = c * 2; ph = r * 4;
      canvas = createBrailleCanvas(pw, ph);
      parts = null; // force rebuild at new size
    }
  }

  // The waterline sits low so the sky owns most of the panel and the flamingo
  // gets a tall stage; the living lake fills the bottom band.
  function waterY() { return Math.round(ph * 0.80); }

  // Build the particle sets for a scene. Counts are bounded relative to canvas
  // size so it stays light on any terminal.
  function buildParts(scene) {
    const p = { clouds: [], drops: [], stars: [], fog: [] };

    const wantClouds =
      ['partly', 'overcast', 'fog', 'rain', 'storm'].includes(scene.key);
    if (wantClouds) {
      const n = scene.key === 'partly' ? 2 : 3;
      for (let i = 0; i < n; i++) {
        p.clouds.push({
          x: rnd(i + 1) * pw,
          y: ph * (0.10 + rnd(i + 9) * 0.18),
          scale: 0.7 + rnd(i + 3) * 0.6,
          speed: 0.10 + rnd(i + 5) * 0.18
        });
      }
    }

    // Stars at night for clear AND partly skies — kept up in the SKY BAND (top
    // ~third) so they read as a starfield, not noise scattered around the bird.
    // Each gets its own twinkle speed/phase so the field shimmers, never static.
    if (!scene.day && (scene.key === 'clear' || scene.key === 'partly')) {
      const n = Math.min(13, Math.round(cols * 0.55));
      for (let i = 0; i < n; i++) {
        p.stars.push({
          x: rnd(i + 2) * pw,
          y: (0.04 + rnd(i + 40) * 0.28) * ph,
          ph: rnd(i + 13) * 6.28,
          tw: 0.05 + rnd(i + 7) * 0.07   // per-star twinkle speed
        });
      }
    }

    if (scene.key === 'rain' || scene.key === 'storm') {
      const base = scene.key === 'storm' ? 0.9 : (scene.intensity || 0.6);
      const n = Math.min(40, Math.round(cols * base));
      for (let i = 0; i < n; i++) {
        p.drops.push({
          x: rnd(i + 1) * pw,
          y: rnd(i + 50) * ph,
          len: 3 + Math.round(rnd(i + 7) * 4),
          speed: 4 + rnd(i + 11) * 4
        });
      }
    }

    if (scene.key === 'fog') {
      const n = Math.min(7, Math.round(rows * 0.4));
      for (let i = 0; i < n; i++) {
        p.fog.push({ y: (i + 0.5) * (ph / (n + 0.5)), dir: i % 2 ? 1 : -1, off: rnd(i + 1) * pw });
      }
    }

    return p;
  }

  // --- sky painters (upper band) ---------------------------------------------
  function paintSun(t) {
    const cx = pw * 0.5, cy = ph * 0.18, r = Math.max(3, Math.min(pw, ph) * 0.09);
    canvas.fillEllipse(cx, cy, r, r, 1);
    for (let i = 0; i < 12; i++) {
      const a = (i / 12) * Math.PI * 2 + t * 0.02;
      const r0 = r + 2, r1 = r + 2 + (3 + 2 * Math.sin(t * 0.15 + i));
      canvas.line(cx + Math.cos(a) * r0, cy + Math.sin(a) * r0,
                  cx + Math.cos(a) * r1, cy + Math.sin(a) * r1, 0.9);
    }
  }

  function paintMoon(t) {
    const cx = pw * 0.62, cy = ph * 0.15, r = Math.max(3, Math.min(pw, ph) * 0.10);
    const sx = cx + r * 0.55, sr = r * 0.95; // shadow circle for the crescent
    for (let y = -r; y <= r; y++) {
      for (let x = -r; x <= r; x++) {
        const inMoon = x * x + y * y <= r * r;
        const dx = (cx + x) - sx, dy = y;
        const inShadow = dx * dx + dy * dy <= sr * sr;
        if (inMoon && !inShadow) canvas.set(cx + x, cy + y, 1);
      }
    }
    // a soft moonglow that gently BREATHES along the lit (left) edge — the
    // night-time analogue of the sun's rotating rays, so the sky is never static.
    const glow = 0.28 + 0.22 * (0.5 + 0.5 * Math.sin(t * 0.05));
    for (let a = Math.PI * 0.55; a <= Math.PI * 1.45; a += 0.16) {
      canvas.set(cx + Math.cos(a) * (r + 2), cy + Math.sin(a) * (r + 2), glow);
    }
  }

  function paintStars(t) {
    for (const s of parts.stars) {
      const tw = 0.5 + 0.5 * Math.sin(t * s.tw + s.ph); // 0..1 smooth twinkle
      const v = 0.3 + 0.7 * tw;
      canvas.set(s.x, s.y, v);
      if (tw > 0.8) { // a little sparkle cross at the peak of each twinkle
        const e = v * 0.6;
        canvas.set(s.x - 1, s.y, e); canvas.set(s.x + 1, s.y, e);
        canvas.set(s.x, s.y - 1, e); canvas.set(s.x, s.y + 1, e);
      }
    }
  }

  // An occasional shooting star streaking across the upper sky — deterministic
  // (fires once per period), cheap (a 5px tapering streak), and a clear bit of
  // night-time motion so "the sky is always animated".
  function paintShootingStar(t) {
    const PERIOD = 165, SPAN = 16;
    const phase = t % PERIOD;
    if (phase >= SPAN) return;
    const k = phase / SPAN;                 // 0..1 travel
    const sx = pw * 0.12 + k * pw * 0.7;
    const sy = ph * 0.05 + k * ph * 0.13;
    for (let j = 0; j < 5; j++) canvas.set(sx - j * 1.5, sy - j * 0.5, 1 - j * 0.18);
  }

  function paintCloud(c, t, v) {
    const cx = (c.x + t * c.speed) % (pw + 20) - 10;
    const rx = 6 * c.scale, ry = 2.4 * c.scale;
    canvas.fillEllipse(cx, c.y, rx, ry, v);
    canvas.fillEllipse(cx - rx * 0.6, c.y + ry * 0.4, rx * 0.6, ry * 0.7, v);
    canvas.fillEllipse(cx + rx * 0.6, c.y + ry * 0.4, rx * 0.7, ry * 0.8, v);
    canvas.fillEllipse(cx + rx * 0.1, c.y - ry * 0.5, rx * 0.6, ry * 0.7, v);
    return cx;
  }

  function paintRain(t, windMph, floorY) {
    const tilt = Math.max(-2, Math.min(2, (windMph || 0) / 12));
    for (const d of parts.drops) {
      d.y += d.speed;
      d.x += tilt;
      if (d.y > floorY) { d.y = -d.len; d.x = rnd(d.y + frame) * pw; }
      if (d.x > pw) d.x -= pw; if (d.x < 0) d.x += pw;
      canvas.line(d.x, d.y, d.x + tilt, d.y + d.len, 0.8);
    }
  }

  // High-wind cue: fast horizontal gust streaks drifting across the sky. Only
  // appears when it's actually blowing — Florida gets plenty of that.
  function paintWindStreaks(t, windMph) {
    if (windMph < 14) return;
    const n = Math.min(4, Math.floor(windMph / 8));
    for (let i = 0; i < n; i++) {
      const yy = ph * (0.14 + 0.11 * i);
      const xx = ((t * 3 + i * 17) % (pw + 14)) - 7;
      const len = 3 + windMph * 0.12;
      canvas.line(xx, yy, xx + len, yy, 0.45);
    }
  }

  function paintFog(t) {
    for (const b of parts.fog) {
      const shift = (b.off + t * 0.4 * b.dir);
      for (let x = 0; x < pw; x += 4) {
        const on = ((x + Math.floor(shift)) % 8) < 4;
        if (on) canvas.set(x, b.y + Math.round(Math.sin((x + shift) * 0.1)), 0.7);
      }
    }
  }

  function paintBolt(t) {
    // jagged vertical bolt from a cloud zone to the ground
    let x = pw * (0.35 + rnd(frame) * 0.3);
    let y = ph * 0.3;
    while (y < ph * 0.7) {
      const nx = x + (rnd(y + frame) - 0.5) * 8;
      const ny = y + 4 + rnd(y) * 3;
      canvas.line(x, y, nx, ny, 1);
      x = nx; y = ny;
    }
  }

  // --- the lake + the flamingo mascot ----------------------------------------
  function paintLake(t, wy, windMph) {
    canvas.setLayer(LAYER.WATER);
    const chop = windMph > 14;
    // The lake is a LIVING surface filling the lower band (waterline -> bottom):
    // drifting horizontal ripple-dashes, denser + faster nearer the foreground so
    // it reads in gentle perspective. Subtle brightness so it never competes with
    // the flamingo — it just keeps the water moving under the hero.
    for (let y = wy; y < ph; y++) {
      const row = y - wy;
      const drift = Math.floor(t * (0.5 + row * 0.12)); // foreground drifts faster
      const bright = (row === 0 ? 0.5 : 0.26 + row * 0.015) + (chop ? 0.12 : 0);
      for (let x = (row * 2) % 4; x < pw; x += 2) {
        // dashes that shift with drift → the surface shimmers and flows
        if (((x + drift + row * 3) % 6) < 2) canvas.set(x, y, bright);
      }
    }
    // whitecaps catching the light on the surface when it's breezy
    if (chop) {
      for (let x = 1; x < pw; x += 4) {
        if (((x + Math.floor(t * 1.2)) % 5) < 2) canvas.set(x, wy - 1, 0.72);
      }
    }
    canvas.setLayer(LAYER.SKY);
  }

  // Pose is a pure function of scene + frame (deterministic, no per-frame RNG).
  // FIRST PRINCIPLE: he is ALWAYS awake with his head + beak out, so the panel
  // always reads as "a flamingo" at a glance. No sleep/tuck pose — life comes
  // from a blink, a gentle look-around, the bob, and the leg switch instead.
  function flamingoPose(scene, t) {
    const umbrella = scene.key === 'rain' || scene.key === 'storm';
    const huddle   = scene.key === 'storm';
    const liftLeft = (Math.floor(t / 90) % 2) === 0;     // which leg is tucked up
    const blink    = (t % 88) < 2;                        // quick eye-blink
    return { umbrella, huddle, liftLeft, blink };
  }

  // Draw the neck as a smooth, 2px-thick S from (sx,sy) up to a head at (hx,hy),
  // bowing by `curve`. Returns the head point so the caller can hang the beak.
  function paintNeck(sx, sy, hx, hy, curve) {
    let lastx = sx, lasty = sy;
    for (let u = 0; u <= 1.0001; u += 0.045) {
      const x = sx + (hx - sx) * u + Math.sin(u * Math.PI) * curve;
      const y = sy + (hy - sy) * u;
      // thicken perpendicular-ish: the neck is mostly vertical, so a 2px-wide
      // horizontal smear reads as a clean tube without gaps.
      canvas.set(x, y, 1); canvas.set(x + 1, y, 1);
      if (Math.abs(x - lastx) > 1) canvas.line(lastx, lasty, x, y, 1); // bridge steep bends
      lastx = x; lasty = y;
    }
  }

  function paintFlamingo(t, scene, weather, wy) {
    const C = canvas;
    const pose = flamingoPose(scene, t);
    const windMph = (weather && weather.windMph) || 0;
    const lean = Math.max(-2.2, Math.min(2.2, windMph / 14)) * (pose.huddle ? 1.5 : 1);
    const bob = Math.sin(t * 0.07) * 1.0;

    const rx = Math.max(5, pw * 0.17);     // body half-width
    const ry = Math.max(4, ph * 0.052);    // body half-height
    // the one hero element — centred so it owns the frame against the weather
    const cx = pw * 0.46 + lean * 1.3;
    // body sits high so the long legs reach the water — reads as a wading bird.
    const bodyCy = wy - ph * 0.205 + bob + (pose.huddle ? ph * 0.04 : 0);
    const hipY = bodyCy + ry * 0.55;

    // --- legs (thin pink) — the classic flamingo "figure-4" stance --------------
    C.setLayer(LAYER.FLAMINGO);
    const legX = cx + lean * 0.4;
    if (pose.huddle) {
      // storm: both feet planted, braced against the wind
      C.line(legX - rx * 0.25, hipY, legX - rx * 0.25 + lean * 0.5, wy, 1);
      C.line(legX + rx * 0.25, hipY, legX + rx * 0.25 + lean * 0.5, wy, 1);
    } else {
      // one straight planted leg down to the waterline...
      C.line(legX, hipY, legX + lean * 0.4, wy, 1);
      // ...and the other tucked into a bent "4" against the planted shin
      const dir = pose.liftLeft ? -1 : 1;
      const kneeY = hipY + (wy - hipY) * 0.5;
      C.line(legX + dir * rx * 0.55, hipY, legX, kneeY, 0.95);     // thigh out + down
      C.line(legX, kneeY, legX + dir * rx * 0.28, kneeY + ry * 0.5, 0.9); // little foot kick
    }

    // --- body: a plump teardrop with pointed tail feathers ----------------------
    C.setLayer(LAYER.FLAMINGO);
    C.fillEllipse(cx, bodyCy, rx, ry, 1);
    // pointed tail (upper-left), two short tapering feathers off the rump
    C.line(cx - rx * 0.8, bodyCy - ry * 0.1, cx - rx * 1.25, bodyCy - ry * 0.95, 0.95);
    C.line(cx - rx * 0.8, bodyCy + ry * 0.2, cx - rx * 1.3, bodyCy - ry * 0.25, 0.9);

    // --- wing: a deeper-rose patch on the flank (the reference's wing shade) ----
    C.setLayer(LAYER.ROSE);
    C.fillEllipse(cx + rx * 0.18, bodyCy + ry * 0.08, rx * 0.52, ry * 0.62, 1);

    // --- neck + head: ALWAYS awake, head + beak OUT (so it always reads as a
    //     flamingo). A gentle look-around sway keeps it alive without hiding. ---
    C.setLayer(LAYER.FLAMINGO);
    const shoulderX = cx + rx * 0.55, shoulderY = bodyCy - ry * 0.45;
    const lookSway = Math.sin(t * 0.045) * 1.3;
    const headX = shoulderX + rx * 0.5 + lean * 1.1 + lookSway;
    const headY = bodyCy - ph * (pose.huddle ? 0.11 : 0.22); // long neck up toward mid-panel
    const curve = rx * 1.0;
    paintNeck(shoulderX, shoulderY, headX, headY, curve);
    C.fillEllipse(headX, headY, 2.1, 2.0, 1); // rounded head

    // --- beak: a chunky orange wedge that hooks down (THE recognizable bit) ---
    C.setLayer(LAYER.BEAK);
    C.fillEllipse(headX + 2.6, headY + 0.7, 1.9, 1.5, 1);   // beak mass
    C.line(headX + 1.4, headY + 0.2, headX + 4.2, headY + 1.6, 1); // top ridge
    C.line(headX + 4.2, headY + 1.6, headX + 3.0, headY + 3.0, 1); // hooked tip down
    // --- eye: negative space punched out of the head (closes briefly on a blink)
    if (!pose.blink) {
      C.unset(headX + 0.4, headY - 0.7);
      C.unset(headX + 1.1, headY - 0.7);
    }

    // --- umbrella (rain/storm) — a yellow dome on a handle over the bird --------
    if (pose.umbrella) {
      C.setLayer(LAYER.UMBRELLA);
      const ux = headX + lean, uy = headY - ph * 0.085;
      const urx = rx * 1.25, ury = Math.max(2, ph * 0.03);
      for (let a = Math.PI; a <= Math.PI * 2 + 0.001; a += 0.12) {
        C.set(ux + Math.cos(a) * urx, uy + Math.sin(a) * ury, 1); // top-half dome
      }
      for (let k = -2; k <= 2; k++) C.line(ux, uy, ux + k * urx * 0.5, uy + ury * 0.2, 0.85);
      C.line(ux, uy + ury * 0.2, headX, headY - 1, 0.85); // handle to the head
    }

    C.setLayer(LAYER.SKY);
    return { cx, bodyCy, rx, ry };
  }

  function buildFrame() {
    ensureCanvas();
    const weather = (store.getSignals() || {}).weather || null;
    const scene = classify(weather);

    // Rebuild particles when the scene OR the day/night flag changes — clear-day
    // and clear-night share key 'clear' but need different particle sets (stars).
    const fullKey = scene.key + (scene.day ? 'D' : 'N');
    if (fullKey !== sceneKey || !parts) {
      sceneKey = fullKey;
      parts = buildParts(scene);
    }

    canvas.clear();
    canvas.setLayer(LAYER.SKY);
    const t = frame;
    const wy = waterY();

    // 1) sky weather in the upper band
    switch (scene.key) {
      case 'clear':
        if (scene.day) paintSun(t);
        else { paintStars(t); paintMoon(t); paintShootingStar(t); }
        break;
      case 'partly':
        if (scene.day) paintSun(t); else { paintStars(t); paintMoon(t); }
        parts.clouds.forEach(c => paintCloud(c, t, 0.8));
        break;
      case 'overcast':
        parts.clouds.forEach(c => paintCloud(c, t, 0.85));
        break;
      case 'fog':
        parts.clouds.forEach(c => paintCloud(c, t, 0.5));
        paintFog(t);
        break;
      case 'rain':
        parts.clouds.forEach(c => paintCloud(c, t, 0.85));
        paintRain(t, weather && weather.windMph, wy);
        break;
      case 'storm':
        parts.clouds.forEach(c => paintCloud(c, t, 0.9));
        paintRain(t, weather && weather.windMph, wy);
        if (frame >= nextBolt) { flashUntil = frame + 2; nextBolt = frame + 40 + Math.floor(rnd(frame) * 60); }
        if (frame <= flashUntil) paintBolt(t);
        break;
      default: // safety net for any unknown key — show a calm clear sky
        if (scene.day) paintSun(t); else { paintStars(t); paintMoon(t); }
        break;
    }

    // 1b) wind, made visible — Florida's signature. Streaks aloft + chop below.
    const windMph = (weather && weather.windMph) || 0;
    paintWindStreaks(t, windMph);

    // 2) moving water + the one hero, the flamingo (always drawn — never empty)
    paintLake(t, wy, windMph);
    paintFlamingo(t, scene, weather, wy);

    // colour: scene colour for the sky/label, but a white flash on a lightning frame
    let color = scene.color;
    if (scene.key === 'storm' && frame <= flashUntil) color = 'white';
    skyBox.style.fg = color;
    skyBox.style.border.fg = color;

    // Day/night is shown visually (sun vs moon+stars, awake vs asleep), so it's
    // left out of the label text — that also keeps the label safely under the
    // panel width even for the longest name + a 3-digit temperature.
    const tempStr = weather && typeof weather.temp === 'number' ? `  ${Math.round(weather.temp)}°F` : '';
    // while syncing, animate trailing dots so it reads as actively loading
    const nameStr = scene.calibrating ? 'SYNCING' + '.'.repeat(Math.floor(frame / 4) % 4) : scene.name;
    const label = `{${color}-fg}${scene.glyph} ${nameStr}${tempStr}{/}`;

    // palette[SKY]='' → sky pixels inherit the box fg (lets the storm flash recolour
    // the whole sky for free); flamingo/water/umbrella get their own tags.
    const palette = [];
    palette[LAYER.SKY] = '';
    palette[LAYER.WATER] = WATER_TAG;
    palette[LAYER.FLAMINGO] = FLAMINGO_TAG;
    palette[LAYER.ROSE] = ROSE_TAG;
    palette[LAYER.BEAK] = BEAK_TAG;
    palette[LAYER.UMBRELLA] = UMBRELLA_TAG;

    skyBox.setContent(canvas.toBrailleColored(0.18, palette) + '\n' + label);
  }

  function startLoop() {
    if (timer) clearInterval(timer);
    // ~8 fps — deliberately gentle; this animation must never be the thing that
    // makes the dashboard feel heavy.
    timer = setInterval(() => {
      frame += 1;
      try { buildFrame(); } catch (_) { /* skip a bad frame, keep the loop alive */ }
      screen.render();
    }, 120);
  }

  function destroy() { if (timer) clearInterval(timer); }

  buildFrame();
  startLoop();

  // The scene is fully autonomous (weather + clock drive it), so the old
  // avatar verbs are no-ops kept only for interface compatibility with the
  // transcript/voice modules.
  return {
    setSpeaker() {},
    setTalking() {},
    reset() {},
    destroy,
    // Headless render seam for scripts/braillepreview.js — advance N frames and
    // return the box content. Not used by the live app.
    __debugRender(advance) {
      for (let i = 0; i < (advance || 1); i++) { frame += 1; try { buildFrame(); } catch (_) {} }
      return skyBox.getContent();
    }
  };
}

module.exports = createWeatherSceneModule;