/** Thirty minutes in milliseconds. */
export const THIRTY_MINUTES_MS = 30 * 60_000;

/** Ninety minutes in milliseconds. */
export const NINETY_MINUTES_MS = 90 * 60_000;

/** Minimum tick speed multiplier for the virtual clock. */
export const MIN_TICK_SPEED = 1;

/** Maximum tick speed multiplier for the virtual clock. */
export const MAX_TICK_SPEED = 1000;

/** Default temperature in Celsius when weather data is unavailable. */
export const DEFAULT_TEMP_CELSIUS = 20;

/** Default background color (black) when no bg-color attribute or computed style is available. */
export const DEFAULT_BG_COLOR: { r: number; g: number; b: number } = { r: 0, g: 0, b: 0 };

/** Fallback sky color for night when no gradient data is available. Matches SKY_PHASES[0]. */
export const FALLBACK_NIGHT_SKY_RGB = "rgb(14,26,58)";

/** Moon glow color (warm cream) as CSS rgba channel values. Matches #e8e8d0. */
export const MOON_GLOW_COLOR_RGB = "232, 232, 208";

/** Moon glow blur radius in pixels. */
export const MOON_GLOW_BLUR_PX = 10;

/**
 * Returns sunrise/sunset timestamps with fallback to defaults.
 * Consolidates the null-check-and-fallback pattern used by multiple consumers.
 */
export function getSunTimesWithDefaults(
  sunrise: number | null | undefined,
  sunset: number | null | undefined,
): { sunrise: number; sunset: number } {
  if (sunrise != null && sunset != null) {
    return { sunrise, sunset };
  }
  return getDefaultSunTimes();
}

export function getCurrentSkyGradient(now: number, sunrise: number | null, sunset: number | null): SkyGradient {
  const { sunrise: sr, sunset: ss } = getSunTimesWithDefaults(sunrise, sunset);
  const { phaseIdx, nextIdx, t } = findPhasePosition(now, sr, ss);
  return lerpGradient(SKY_PHASES[phaseIdx].gradient, SKY_PHASES[nextIdx].gradient, t);
}

export function buildPhaseInfo(state: StoreState, now: number): PhaseInfo {
  const { sunrise: sr, sunset: ss } = getSunTimesWithDefaults(state.weather.sunrise, state.weather.sunset);

import { getSunTimesWithDefaults, findPhasePosition } from "./sky-gradient";

    const { sunrise, sunset, now } = state.computed.phase;
    const { sunrise: sr, sunset: ss } = getSunTimesWithDefaults(sunrise, sunset);

import { getSunTimesWithDefaults } from "../../utils/sky-gradient";

    const { sunrise, sunset, now } = state.computed.phase;
    const { sunrise: sr, sunset: ss } = getSunTimesWithDefaults(sunrise, sunset);

import { getSunTimesWithDefaults } from "../../utils/sky-gradient";

// Before:
const MIN30 = 30 * 60_000;
const MIN60 = 60 * 60_000;
const MIN90 = 90 * 60_000;

import { THIRTY_MINUTES_MS, ONE_HOUR_MS, NINETY_MINUTES_MS } from "./constants";

  // Before:
  const phaseEnd =
    nextIdx === 0
      ? (() => {
          const eod = new Date(now);
          eod.setHours(23, 59, 59, 999);
          return eod.getTime();
        })()
      : timestamps[nextIdx];

  let phaseEnd: number;
  if (nextIdx === 0) {
    // Last phase wraps to end of day
    const endOfDay = new Date(now);
    endOfDay.setHours(23, 59, 59, 999);
    phaseEnd = endOfDay.getTime();
  } else {
    phaseEnd = timestamps[nextIdx];
  }

// Before (line 32):
const ARC_Y_AMPLITUDE = 42;

// After:
/** Maximum vertical travel from horizon to zenith, in percent of container height. */
const ARC_Y_AMPLITUDE = 42;

  // Map elapsed time since solar noon to a full rotation (one day = 2π)
  const angle = ((elapsed / ONE_DAY_MS) * TWO_PI) % TWO_PI;

export function getArcPosition(angle: number): ArcPosition {
  // Normalize angle to [0, 2π)
  const normalizedAngle = ((angle % TWO_PI) + TWO_PI) % TWO_PI;
  const visible = normalizedAngle <= HALF_PI || normalizedAngle >= THREE_HALF_PI;

  if (!visible) {
    return { x: DEFAULT_ARC_X, y: DEFAULT_ARC_Y, visible: false };
  }

  // Rotate so the visible arc [3π/2 → 0 → π/2] maps to [0 → π]
  // This makes the rising edge (3π/2) map to 0 and setting edge (π/2) map to π
  let rotatedAngle = normalizedAngle + HALF_PI;
  if (rotatedAngle >= TWO_PI) rotatedAngle -= TWO_PI;
  const progress = rotatedAngle / Math.PI;

  const x = ARC_X_MIN + progress * ARC_X_RANGE;
  const y = ARC_Y_BASE - Math.sin(progress * Math.PI) * ARC_Y_AMPLITUDE;

  return { x, y, visible };
}

/**
 * Calculate the relative luminance of an RGB color per WCAG 2.0.
 * Returns a value between 0 (black) and 1 (white).
 * @see https://www.w3.org/TR/WCAG20/#relativeluminancedef
 */

    // Standard RGB → HSL conversion

    // Binary search for minimum lightness meeting contrast ratio
    // 16 iterations → precision ~0.002% of lightness range

/**
 * Mulberry32 PRNG — deterministic random from a 32-bit seed.
 * Returns a function that produces values in [0, 1).
 * @see https://gist.github.com/tommyettinger/46a874533244883189143505d203312c
 */

/**
 * Cache version — increment when the stored shape changes.
 * v6: Added timezone to location, overrideMoonPhase to attrs.
 */
export const CACHE_VERSION = 6;
export const STORAGE_KEY = "liveWindowStore";

import { loadState, saveState, DEFAULT_STORE, CACHE_VERSION, STORAGE_KEY } from "../state";

// Before:
export const WEATHER_RATE_LIMIT = 30 * 60_000;

// After:
import { THIRTY_MINUTES_MS } from "./utils/constants";

export const WEATHER_RATE_LIMIT = THIRTY_MINUTES_MS;

/** Valid precipitation config keys — must match PRECIP_CONFIG object keys. */
export type PrecipType =
  | "lightRain" | "rain" | "snow" | "sleet" | "drizzle" | "showerRain"
  | "freezingRain" | "lightSnow" | "heavySnow" | "showerSnow"
  | "drizzleLight" | "drizzleHeavy" | "showerDrizzle" | "heavyRain"
  | "extremeRain" | "showerSleet";

export interface PrecipLayer {
  type: PrecipType;
  intensityScale: number;
}

export const PRECIP_CONFIG: Record<PrecipType, PrecipConfig> = {

import type {
  PrecipConfig,
  PrecipType,
  ...
} from "./weather-types";

export const ATMOSPHERE_CONFIG: Record<string, AtmosphereConfig> = {

/** Atmosphere overlay configs keyed by weather condition name. */
export const ATMOSPHERE_CONFIG: Record<string, AtmosphereConfig> = {

export const CLOUD_COLORS: Record<Exclude<CloudDensity, "none">, [string, string]> = {

export const SKY_TINT_STRENGTH: Record<Exclude<CloudDensity, "none">, number> = {

/** Helper to construct a WeatherEffectConfig with sensible defaults. */
function createWeatherEffect(
  clouds: WeatherEffectConfig["clouds"],
  precip: PrecipLayer[],
  opts?: {
    lightning?: LightningVariant;
    atmosphere?: AtmosphereConfig;
    wind?: WindLevel;
    atmosphereParticles?: AtmosphereParticleConfig;
  },
): WeatherEffectConfig {
  return {
    clouds,
    precip,
    lightning: opts?.lightning ?? false,
    atmosphere: opts?.atmosphere ?? null,
    wind: opts?.wind ?? "none",
    atmosphereParticles: opts?.atmosphereParticles ?? null,
  };
}

/** Helper to construct a PrecipLayer entry. */
function precipLayer(type: PrecipType, intensityScale = 1.0): PrecipLayer {
  return { type, intensityScale };
}

import type { CloudDensity, LightningVariant } from "./weather-types";

const CLOUD_DARKEN: Record<Exclude<CloudDensity, "none">, number> = {
  light: 0.05,
  medium: 0.12,
  heavy: 0.22,
  storm: 0.28,
};

const LIGHTNING_DARKEN: Record<LightningVariant, number> = { intense: 0.16, distant: 0.06, standard: 0.12 };

/** Average the upper and lower sky gradient bands — gives the dominant sky color at cloud altitude. */
function averageSkyBands(skyGradient: SkyGradient): string {
  return rgbToHex({
    r: Math.round((skyGradient.upper.r + skyGradient.lower.r) / 2),
    g: Math.round((skyGradient.upper.g + skyGradient.lower.g) / 2),
    b: Math.round((skyGradient.upper.b + skyGradient.lower.b) / 2),
  });
}

      const warmColor = averageSkyBands(skyGradient);

      const warmColor = averageSkyBands(skyGradient);

// --- Deterministic animation timing ranges ---
// Each element gets a pseudo-random duration and a negative delay
// (negative delays start the animation mid-cycle so elements aren't synchronized)

/** Cloud floating animation: duration 4.0s–9.9s */
const CLOUD_BASE_DURATION = 4;
const CLOUD_DURATION_JITTER = 6; // range in seconds (via hash % 60 / 10)
/** Cloud animation negative delay: 0.0s to -7.9s */
const CLOUD_MAX_NEGATIVE_DELAY = 8; // (via hash % 80 / 10)

/** Precipitation sway: duration 2.0s–3.7s */
const SWAY_BASE_DURATION = 2;
const SWAY_DURATION_JITTER = 1.8; // (via hash % 18 / 10)
/** Precipitation sway negative delay: 0.0s to -3.9s */
const SWAY_MAX_NEGATIVE_DELAY = 4; // (via hash % 40 / 10)

/** Atmosphere particle jitter added to base speed: 0.0s–2.9s */
const ATMO_DURATION_JITTER = 3; // (via hash % 30 / 10)
/** Atmosphere particle negative delay: 0.0s to -7.9s */
const ATMO_MAX_NEGATIVE_DELAY = 8; // (via hash % 80 / 10)

/** Atmosphere particles are constrained to the top 80% of the scene. */
const ATMO_Y_RANGE = 80;

/** Golden ratio conjugate — produces evenly-spaced distribution across [0, 1) when used as (i * φ) % 1. */
const GOLDEN_RATIO = 0.618033;
/** Initial offset for golden ratio cloud distribution. */
const GOLDEN_RATIO_OFFSET = 0.3;
/** Cloud X range: -5% to 105% of container width (allows clouds to partially overflow). */
const CLOUD_X_SCALE = 110;
const CLOUD_X_OFFSET = -5;

/** Second hash constant for Y-position, decorrelated from Knuth hash. */
const Y_HASH_MULTIPLIER = 1597334677;
/** Prime multiplier for decorrelating Y positions from X positions. */
const POSITION_DECORRELATION_PRIME = 37;

    const yHash = ((i + 1) * Y_HASH_MULTIPLIER) >>> 0;
    const left = ((i * GOLDEN_RATIO + GOLDEN_RATIO_OFFSET) % 1) * CLOUD_X_SCALE + CLOUD_X_OFFSET;
    const top = config.yRange[0] + (yHash % (ySpan + 1));
    const size = config.sizeRange[0] + (h % (sizeRange + 1));
    const opacity = (config.opacityRange[0] + ((h >>> 4) % (opRange + 1))) / 100;

    const floatName = FLOAT_NAMES[i % 3];
    const dur = (CLOUD_BASE_DURATION + ((h >>> 12) % (CLOUD_DURATION_JITTER * 10)) / 10).toFixed(1);
    const delay = (-((h >>> 16) % (CLOUD_MAX_NEGATIVE_DELAY * 10)) / 10).toFixed(1);

    const top = ((h >>> 8) ^ (i * POSITION_DECORRELATION_PRIME)) % 100;
    ...
      const dur = (SWAY_BASE_DURATION + ((h >>> 12) % (SWAY_DURATION_JITTER * 10)) / 10).toFixed(1);
      const delay = (-((h >>> 16) % (SWAY_MAX_NEGATIVE_DELAY * 10)) / 10).toFixed(1);

    const top = ((h >>> 8) ^ (i * POSITION_DECORRELATION_PRIME)) % ATMO_Y_RANGE;
    ...
    const dur = parseFloat(config.speed) + ((h >>> 12) % (ATMO_DURATION_JITTER * 10)) / 10;
    const delay = -((h >>> 16) % (ATMO_MAX_NEGATIVE_DELAY * 10)) / 10;

import type { SceneComponent, LiveWindowState } from "../../types";
import type { CloudDensity } from "./weather/weather-types";
import { WEATHER_EFFECTS, CLOUD_CONFIGS, PRECIP_CONFIG } from "./weather/weather-configs";
import { getCloudColor, getAtmosphereColor, getSkyDarkenOpacity } from "./weather/weather-colors";
import { cloudHTML, particleHTML, atmosphereParticleHTML, lightningHTML } from "./weather/weather-html";

/** Fraction of clouds rendered behind precipitation/lightning (rest go in front). */
const BACK_CLOUD_RATIO = 0.4;

/** Wind skew angle in degrees per wind level. */
const WIND_SKEW_DEG: Record<import("./weather/weather-types").WindLevel, number> = {
  strong: 15,
  moderate: 8,
  light: 3,
  none: 0,
};

/** CSS size classes for atmosphere layers, applied in order. */
const ATMOSPHERE_SIZES = ["lg", "md", "sm"] as const;

      const total = CLOUD_CONFIGS[config.clouds as Exclude<CloudDensity, "none">].count;
      const backCount = Math.ceil(total * BACK_CLOUD_RATIO);

    const skewDeg = WIND_SKEW_DEG[config.wind];

      const sizes = ATMOSPHERE_SIZES;

import { FALLBACK_NIGHT_SKY_RGB, MOON_GLOW_COLOR_RGB, MOON_GLOW_BLUR_PX } from "../../utils/constants";

      const skyColor = g ? this.sampleSkyAt(g, pos.y / 100) : FALLBACK_NIGHT_SKY_RGB;

      // Shadow displacement: maps phase 0–1 to a sliding shadow across the moon disc.
      // phase 0 (new moon): dx = 0, shadow covers the full moon
      // phase 0.25: dx = -MOON_DIAMETER/2, half lit (first quarter)
      // phase 0.5 (full moon): dx = -MOON_DIAMETER, shadow fully off-screen
      // phase 0.75: dx = MOON_DIAMETER/2, half lit (last quarter)
      let dx: number;

      // Lit fraction: 0 at new moon (phase 0), 1 at full moon (0.5), 0 at next new (1)
      const litAmount = moonPhase <= 0.5 ? moonPhase * 2 : (1 - moonPhase) * 2;
      const glowOpacity = (MOON_GLOW_OPACITY * litAmount).toFixed(2);
      const glowSpread = Math.round(MOON_GLOW_SPREAD_MIN + MOON_GLOW_SPREAD_RANGE * litAmount);
      this.moon.style.boxShadow = `0 0 ${MOON_GLOW_BLUR_PX}px ${glowSpread}px rgba(${MOON_GLOW_COLOR_RGB}, ${glowOpacity})`;

// Final collapse ratio: between MIN_COLLAPSE_RATIO and MIN_COLLAPSE_RATIO + COLLAPSE_RATIO_RANGE
// (e.g., 0.7 to 0.95 = 70–95% of blinds collapse upward when opened)
const MIN_COLLAPSE_RATIO = 0.7;
const COLLAPSE_RATIO_RANGE = 0.25;

    // Double requestAnimationFrame ensures the browser has fully computed layout
    // before we measure element positions for the string height calculation
    requestAnimationFrame(() => requestAnimationFrame(() => this.updateStrings()));

  /**
   * Compute the skew + rotation transform for an individual open blind slat.
   * The total skew is distributed linearly across open blinds, creating a
   * perspective-like fan effect. blindIndex counts from the top (0 = topmost open slat).
   */
  private getSkewAndRotateTransform(blindIndex: number): string {
    const state = this.blindsState;
    // Count from bottom: currBlind = 1 for the bottom slat
    const currBlind = NUM_BLINDS - blindIndex;
    const numOpen = NUM_BLINDS - state.numBlindsCollapsed;
    // Each open slat gets an equal fraction of the total skew
    const skewSteps = numOpen > 0 ? state.blindsSkewDeg / numOpen : 0;

    let skewDeg = 0;
    if (state.skewDirection !== 0 && state.blindsSkewDeg >= 0) {
      // Linearly distribute skew: topmost open slat gets full skew, bottom gets zero
      skewDeg = state.blindsSkewDeg - (currBlind - state.numBlindsCollapsed - 1) * skewSteps;
    }

    const rot = state.blindsOpenDeg;
    return `rotateX(${rot}deg) skewY(${skewDeg * state.skewDirection}deg)`;
  }

  private getSkewOnlyTransform(): string {
    const state = this.blindsState;
    let skewDeg = 0;
    if (state.skewDirection !== 0 && state.blindsSkewDeg >= 0) {
      // Collapsed group and slat bar sit at the midpoint of the total skew
      skewDeg = state.blindsSkewDeg / 2;
    }
    return `skewY(${skewDeg * state.skewDirection}deg)`;
  }

      // Intl.DateTimeFormat returns 24 for midnight in hour12:false mode in some locales
      if (raw === 24) raw = 0;

    if (this.hourEl) this.hourEl.textContent = String(h).padStart(2, "0");
    if (this.minuteEl) this.minuteEl.textContent = String(m).padStart(2, "0");

  // Order matters: GradientLayer must be first because it writes state.ref.currentGradient,
  // which MoonLayer and WeatherLayer read during the same update cycle.
  private children: SceneComponent[] = [
    new GradientLayer(),
    new StarsLayer(),
    new SunLayer(),
    new MoonLayer(),
    new WeatherLayer(),
  ];

/** Google Fonts stylesheet URL for the clock font. */
const FONT_STYLESHEET_URL = "https://fonts.googleapis.com/css2?family=Squada+One&display=swap";

/** Data attribute used to detect/mark the font <link> element in the host document. */
const FONT_DATA_ATTR = "data-live-window-font";

/**
 * OpenWeatherMap weather group ID → icon code.
 * The group is derived as Math.floor(weatherId / 100).
 */
const WEATHER_GROUP_ICON: Record<number, string> = {
  2: "11", // Thunderstorm
  3: "09", // Drizzle → shower rain icon
  5: "10", // Rain
  6: "13", // Snow
  7: "50", // Atmosphere (fog/mist)
  8: "01", // Clear/Clouds (overridden below for specific cloud IDs)
};

/**
 * Specific OWM weather IDs for cloud coverage → icon code.
 * These override the group-level mapping above.
 */
const CLOUD_COVERAGE_ICON: Record<number, string> = {
  800: "01", // Clear sky
  801: "02", // Few clouds (11-25%)
  802: "03", // Scattered clouds (25-50%)
  803: "04", // Broken clouds (51-84%)
  804: "04", // Overcast clouds (85-100%)
};

import { ONE_DAY_MS, ONE_HOUR_MS, CLOCK_INTERVAL_MS, SKY_UPDATE_INTERVAL_MS, MIN_TICK_SPEED, MAX_TICK_SPEED, DEFAULT_TEMP_CELSIUS, DEFAULT_BG_COLOR } from "./utils/constants";

    connectedCallback() {
      if (!document.querySelector(`link[${FONT_DATA_ATTR}]`)) {
        const link = document.createElement("link");
        link.rel = "stylesheet";
        link.href = FONT_STYLESHEET_URL;
        link.setAttribute(FONT_DATA_ATTR, "");
        // Font loaded in host document <head> because Shadow DOM can't load
        // external @font-face stylesheets internally
        document.head.appendChild(link);
      }

      const tickSpeed = tickSpeedRaw ? Math.max(MIN_TICK_SPEED, Math.min(MAX_TICK_SPEED, parseFloat(tickSpeedRaw))) : 1;

      const timezone = this.state.attrs.timezone;
      ...
      const sunriseOverride = overrideSunrise ? this.parseTimeToTimestamp(overrideSunrise) : null;
      const sunsetOverride = overrideSunset ? this.parseTimeToTimestamp(overrideSunset) : null;

  /**
   * Derive the OWM icon code from a weather ID + day/night flag.
   * First checks specific cloud-coverage IDs, then falls back to group-level mapping.
   */
  private deriveWeatherIcon(weatherId: number, isDaytime: boolean): string {
    const iconBase = CLOUD_COVERAGE_ICON[weatherId]
      ?? WEATHER_GROUP_ICON[Math.floor(weatherId / 100)]
      ?? "01";
    return iconBase + (isDaytime ? "d" : "n");
  }

      if (overrideWeather) {
        const weatherId = parseInt(overrideWeather, 10);
        const isDaytime = now >= (store.weather.sunrise ?? 0) && now <= (store.weather.sunset ?? 0);

        store = {
          ...store,
          weather: {
            ...store.weather,
            current: {
              id: weatherId,
              main: WEATHER_DESCRIPTIONS[weatherId]?.split(" ")[0] ?? "Unknown",
              description: WEATHER_DESCRIPTIONS[weatherId] ?? "",
              icon: this.deriveWeatherIcon(weatherId, isDaytime),
              temp: store.weather.current?.temp ?? DEFAULT_TEMP_CELSIUS,
            },
          },
        };
      }

      return parseComputedColor(computed) ?? DEFAULT_BG_COLOR;

  /**
   * Returns the effective "now" timestamp, accounting for overrides and virtual clock.
   *
   * Four modes (checked in order):
   * 1. Virtual clock advancing — virtualTime + scaled elapsed real time, wraps at midnight
   * 2. Static virtual time — frozen at virtualTime (paused virtual clock)
   * 3. Override time attribute — parsed from "HH:MM" string
   * 4. Normal real time — Date.now() with optional timezone shift
   */

`.sky` container. Each layer implements the `SceneComponent` interface

Current layers (bottom to top):

1. **GradientLayer** — renders the sky color gradient
2. **StarsLayer** — renders procedurally generated stars with twinkle animation
3. **SunLayer** — positions the sun along a celestial arc
4. **MoonLayer** — positions the moon with lunar phase shadow
5. **WeatherLayer** — renders clouds, rain, snow, lightning, mist

Adding a new layer:

1. Create `components/sky/<Name>Layer.ts` implementing `SceneComponent`
2. Register it in the `children` array in `SkyComponent.ts`
3. Add styles to `live-window.css`

## Files

| File                                | Purpose                                              |
| ----------------------------------- | ---------------------------------------------------- |
| `LiveWindow.ts`                     | Web Component orchestrator, lifecycle, intervals     |
| `live-window.css`                   | All styles (loaded into Shadow DOM via `<link>`)     |
| `types.ts`                          | Shared interfaces: RGB, SkyGradient, PhaseInfo, etc. |
| `state.ts`                          | localStorage persistence, cache versioning           |
| `api.ts`                            | Location + weather fetch via Worker + rate limiting   |
| `components/ClockComponent.ts`      | Clock rendering + time format logic                  |
| `components/BlindsComponent.ts`     | Blinds animation + rendering                         |
| `components/InfoPanelComponent.ts`  | Location, weather text, and coords display           |
| `components/SkyComponent.ts`        | Sky layer orchestrator (ordering + lifecycle)         |
| `components/sky/GradientLayer.ts`   | Sky color gradient (16 phases)                       |
| `components/sky/StarsLayer.ts`      | Procedural star field with twinkle                   |
| `components/sky/SunLayer.ts`        | Sun positioning along celestial arc                  |
| `components/sky/MoonLayer.ts`       | Moon positioning with lunar phase shadow             |
| `components/sky/WeatherLayer.ts`    | Clouds, rain, snow, lightning, mist                  |
| `utils/celestial.ts`                | Sun/moon angle + arc position math                   |
| `utils/color.ts`                    | WCAG contrast, luminance, hex/RGB conversion         |
| `utils/constants.ts`                | Shared numeric/timing constants                      |
| `utils/math.ts`                     | clamp01, lerp, smoothstep, knuthHash                 |
| `utils/phase.ts`                    | PhaseInfo builder + sun position calculation         |
| `utils/sky-gradient.ts`             | 16-phase sky gradient, phase timestamps              |
| `utils/stars.ts`                    | Star field generation, Mulberry32 PRNG               |
| `utils/timezone.ts`                 | Timezone-shifted timestamp utilities                 |